immich-folio/docs/superpowers/plans/2026-08-15-portfolio-features.md

# Portfolio-Features: Auffindbarkeit, Zoom, Sequenzierung, Ortsauflösung

> **For agentic workers:** Steps use checkbox (`- [ ]`) syntax for tracking. Die vier Tasks sind
> **voneinander unabhängig** und können einzeln umgesetzt, getestet und gemerged werden.

**Goal:** Vier Vorschläge aus [`brainstorm-2026-08-15.md`](../../brainstorm-2026-08-15.md) umsetzen —
E (Auffindbarkeit), B2 (1:1-Zoom), B1 (Sequenzierung), C1 (Ortsauflösung). Reihenfolge nach
steigendem Risiko: erst zwei abgeschlossene Kleinigkeiten, dann der größte Eingriff, dann ein
Datenschutz-Feature mit klarer Angriffsfläche.

**Architecture:** Vier getrennte Eingriffe ohne gemeinsame Dateien — bis auf `lib/config/schema.ts`
und `lib/config/index.ts`, die von B1 und C1 beide angefasst werden (verschiedene Felder, kein
inhaltlicher Konflikt). Jede neue Per-Album-Option folgt dem etablierten Muster: ein
`Record<albumId, X>` in `AppConfig`, befüllt in `deriveGallery()`, genau wie `albumGrids` und
`albumCoverPositions` es seit #431 vormachen.

**Tech Stack:** Next.js 16 (App Router, React 19), TypeScript strict, Vitest 4 (node environment),
Playwright, Vanilla CSS, keine neuen Laufzeit-Dependencies.

---

## Global Constraints

- **Keine neuen Runtime-Dependencies.** Das Projekt hat sieben; das bleibt so.
- **TypeScript strict** — kein untypisiertes `any`; Suppressions nur als `@ts-expect-error` mit Begründung.
- **Rohe Immich-UUIDs dürfen nie im Client-HTML/JS landen.** Immer `imageUrl()` / `encodeAssetId()`.
- **Vanilla CSS**, Tokens aus `app/tokens.css`.
- **Formatierung:** nur geänderte Dateien (`npx prettier --write <datei>`), nie `npm run format` im Root.
- **Vor jedem Commit grün:** `npm run test:unit`, `npx tsc --noEmit`, `npm run lint`, `npm run build`.
- **Baseline vor Beginn:** 443 Tests in 35 Dateien. Jede Task nennt die erwartete neue Summe.
- **Commit-Stil:** Conventional Commits. Experimentelle Optionen als `EXPERIMENTAL` in YAML-Kommentar
  und Admin-Label markieren, so wie #431 es gemacht hat.
- **Neue Env-Variablen** gehören in `lib/env.ts` **und** `.env.local.example`.
- **Vitest läuft im `node`-Environment** — es gibt kein jsdom. Komponentenlogik ist deshalb nur
  testbar, wenn die _reine_ Berechnung in einem eigenen Modul liegt; die DOM-Verdrahtung deckt
  Playwright ab. Das ist bei B1 und B2 jeweils eingeplant und ausdrücklich **kein** Verstoß gegen
  die CLAUDE.md-Regel (die verbietet, _Route_-Logik nur der Testbarkeit wegen nach `lib/` zu ziehen —
  hier geht es um echte, wiederverwendbare Geometrie- bzw. Gruppierungsfunktionen).

---

## Task E — Auffindbarkeit: Site-URL, `robots.txt`, `sitemap.xml`, JSON-LD

**Aufwand:** S (die Vorbedingung E1 und die Admin-UI machen daraus mehr als das im Brainstorm
geschätzte XS.)

### Befund vorab: es fehlt eine Site-URL

`lib/env.ts` kennt keine `SITE_URL`, `settings.yaml` keine `url:`, und `app/layout.tsx` setzt
**keine `metadataBase`**. OG-Bilder werden heute als relativer Pfad angegeben
(`app/layout.tsx:57`). Für `sitemap.xml` ist das ein hartes Hindernis: Der Sitemap-Standard
verlangt absolute URLs, und `app/sitemap.ts` läuft ohne Request-Kontext — der Host lässt sich also
nicht aus Headern ableiten.

**Entscheidung:** `url` in `settings.yaml`, überschreibbar durch `SITE_URL`. Env gewinnt — dasselbe
Präzedenzmuster wie bei Titel und Credentials. In `settings.yaml`, **weil der Wert im Admin-Panel
setzbar sein muss**: Wer per `docker run` startet, soll die Site-URL nicht in einer Env-Variable
nachtragen und neu starten müssen, sondern sie dort eingeben, wo er ohnehin Titel und SEO pflegt.

### Die Falle dabei — und warum E1b im Plan steht

Env gewinnt über YAML. Setzt jemand `SITE_URL` **und** trägt im Admin etwas anderes ein, speichert
das Panel brav, ändert aber nichts — der Wert wird stillschweigend überstimmt. Genau dieser Zustand
existiert heute schon unbemerkt bei `SITE_TITLE`/`SITE_SUBTITLE`: `lib/env.ts:98-99` schlägt
`settings.yaml` und **das Admin-Panel sagt es nirgends**. Eine repo-weite Suche findet in
`SettingsEditor.tsx`, `AdminDashboard.tsx` und `/api/admin/status` keinen einzigen Hinweis auf
Env-Überschreibungen.

Weil dieses Feld nun ausdrücklich über die UI bedienbar sein soll, wird die Anzeige mitgebaut —
klein, generisch und für die bestehenden Felder gleich mitverwendet.

### Schritte

- [ ] **E1 — Site-URL einführen**
  - `SITE_URL` in `lib/env.ts` (`interface Env` + `parseEnv()`), validiert über `new URL()`,
    trailing Slash entfernt — analog zur bestehenden Behandlung von `IMMICH_API_URL:26-32`.
  - `url?: string` in `SettingsYaml` (`lib/config/schema.ts`) und `siteUrl: string` in `AppConfig`.
  - Auflösung in `lib/config/index.ts`: `env.SITE_URL || settings.url || ''`.
  - `metadataBase` in `app/layout.tsx` setzen, wenn `siteUrl` nicht leer ist.
  - In `settings.yaml.example` dokumentieren, inklusive des Hinweises, dass ohne diesen Wert
    Sitemap und JSON-LD entfallen.
- [ ] **E1a — Feld im Admin-Panel** (`app/admin/components/SettingsEditor.tsx`, Sektion `seo`,
      `SETTINGS_SECTIONS:197`)
  - Textfeld **„Site URL"** als erstes Feld der SEO-Sektion, über „SEO Title" — es ist die
    Voraussetzung für alles andere dort. Anbindung wie die Nachbarfelder: `update('url', …)`.
    (Achtung: `url` liegt auf oberster Ebene, nicht unter `seo.` — sonst landet es beim Auflösen
    an der falschen Stelle.)
  - Placeholder `https://folio.example.com`, Hilfetext: wofür der Wert gebraucht wird (Sitemap,
    `robots.txt`, JSON-LD, absolute OG-Bild-URLs).
  - **Validierung im Feld, nicht erst beim Speichern:** muss mit `http://` oder `https://`
    beginnen und über `new URL()` parsebar sein; trailing Slash beim Speichern abschneiden, damit
    aus Nutzersicht egal ist, ob er einen setzt. Ungültige Eingabe blockiert das Speichern mit
    einer Meldung am Feld — eine kaputte Site-URL erzeugt sonst eine Sitemap voller kaputter Links.
  - Leeres Feld ist ein gültiger Zustand (= Funktionen aus, wie heute), keine Fehlermeldung.
  - Ein Hinweis in der SEO-Sektion, solange das Feld leer ist: „Ohne Site URL werden `sitemap.xml`
    und JSON-LD nicht ausgeliefert." Sonst sucht jemand den Fehler an der falschen Stelle.
- [ ] **E1b — Env-Überschreibungen im Panel sichtbar machen** (klein, generisch)
  - `GET /api/admin/settings` (`app/api/admin/settings/route.ts:18-19`) gibt zusätzlich
    `envLocked: string[]` zurück — die Namen der Felder, die gerade aus der Umgebung kommen.
    Anfangs: `url` (wenn `SITE_URL` gesetzt), `title` (`SITE_TITLE`), `subtitle` (`SITE_SUBTITLE`).
    **Nur Feldnamen, keine Werte** — die Route soll keine Env-Inhalte spiegeln, die sonst nirgends
    im Panel stehen.
  - `SettingsEditor` rendert betroffene Felder deaktiviert mit dem Zusatz „Von der Umgebungsvariable
    `SITE_URL` gesetzt" statt eines editierbaren Eingabefelds. Damit ist der stille Fehlschlag
    weg — beim neuen Feld und bei Titel/Untertitel gleich mit.
  - Das ist die erste Stelle dieser Art im Projekt; entsprechend klein halten (eine Liste, ein
    `disabled`, ein Hinweistext) und nicht zu einem Mechanismus ausbauen.
- [ ] **E2 — `app/robots.ts`**
  - `Disallow` für `/admin`, `/install`, `/api`.
  - `seo.noIndex: true` → `Disallow: /` für alle Agents.
  - `sitemap:`-Verweis nur, wenn `siteUrl` gesetzt ist.
- [ ] **E3 — `app/sitemap.ts`**
  - Gibt `[]` zurück, wenn `siteUrl` leer ist oder `seo.noIndex` gilt — kein halber Zustand.
  - Enthalten: `/`, `/about` (nur wenn `aboutEnabled`), `/map` (nur wenn `config.map`),
    `/journal` und je Eintrag `/journal/<slug>`, Subpages und Alben.
  - **Ausschlussliste — der eigentliche Inhalt dieser Task:**
    | Ausgeschlossen                                        | Quelle                                                        |
    | ----------------------------------------------------- | ------------------------------------------------------------- |
    | Subpage mit `password`                                | `SubpageConfig.password`                                      |
    | Subpage mit `hidden: true`                            | `SubpageConfig.hidden`                                        |
    | Subpage mit `enabled: false`                          | `SubpageConfig.enabled`                                       |
    | Album mit eigenem Passwort                            | `config.albumPasswords`                                       |
    | Album unterhalb einer geschützten/versteckten Subpage | Vererbung, siehe unten                                        |
    | Journal-Draft                                         | `frontmatter.draft`                                           |
    | Journal-Eintrag mit Passwort                          | Frontmatter                                                   |
    | `/impressum`                                          | trägt bereits `robots: noindex` (`app/impressum/page.tsx:14`) |
  - **Vererbung nicht vergessen:** Ein öffentliches Album unter einer passwortgeschützten Subpage
    ist über `/<subpage>/<album>` nicht erreichbar. Die Prüfung muss den Pfad entlanglaufen, nicht
    nur das Album ansehen.
  - `lastModified` aus `album.updatedAt` bzw. dem Journal-Datum.
- [ ] **E4 — JSON-LD**
  - `Person` bzw. `ProfilePage` auf `/about`, gespeist aus dem Frontmatter von `content/about.md`.
  - `ImageObject` mit `creator` und optional `license` auf Album-Detailseiten.
  - **CSP-Falle:** `proxy.ts` setzt eine CSP mit Per-Request-Nonce und reicht sie über den
    `x-nonce`-Header an die Seiten. Ein `<script type="application/ld+json">` **muss** diese Nonce
    tragen, sonst blockt der Browser es still. Im Browser mit gesetzter CSP verifizieren, nicht nur
    im Markup nachsehen.
  - `license` als optionales Feld in `settings.yaml` (`seo.license`), leer = weglassen.
- [ ] **E5 — Tests**
  - `lib/__tests__/sitemap.test.ts`: **tabellengetrieben über die Ausschlusskategorien**, nicht als
    Einzelfälle — dann schlägt der Test auch bei einer künftig hinzugefügten Sichtbarkeitsregel an.
    Vorbild: `app/api/admin/__tests__/admin-guards.test.ts`. Zusätzlich: leere Sitemap bei fehlender
    `siteUrl`; `noIndex` unterdrückt alles.
  - `lib/__tests__/site-url.test.ts`: Präzedenz `SITE_URL` > `settings.url` > leer; trailing Slash
    wird entfernt; ungültige URL führt nicht zum Absturz, sondern zu „nicht gesetzt".
  - `app/api/admin/__tests__/settings-env-lock.test.ts`: `envLocked` enthält `url` genau dann, wenn
    `SITE_URL` gesetzt ist — und die Antwort enthält **nirgends den Env-Wert selbst**.
  - Erwartet: **+18 bis +24 Tests** (461–467 gesamt).

**Verifikation:**

1. **Ohne** `SITE_URL`: Im Admin unter SEO die Site URL eintragen, speichern, dann `/sitemap.xml`
   und `/robots.txt` abrufen — beide müssen ohne Neustart die neue Domain führen (`invalidateConfigCache()`
   läuft beim Speichern bereits). Feld leeren → Sitemap wird wieder leer, Hinweistext erscheint.
2. Ungültige Eingaben gegenprüfen: `folio.example.com` ohne Schema und `https://` allein müssen am
   Feld abgewiesen werden, nicht erst beim Rendern der Sitemap auffallen.
3. **Mit** gesetztem `SITE_URL`: Das Feld muss deaktiviert sein und die Herkunft nennen — dasselbe
   für Titel/Untertitel bei gesetztem `SITE_TITLE`.
4. Eine passwortgeschützte Subpage anlegen und prüfen, dass weder ihr Slug noch ihre Alben in der
   Sitemap auftauchen.
5. JSON-LD im Rich-Results-Test von Google gegenprüfen; Browser-Konsole auf CSP-Fehler ansehen.

**Commits:** `feat(seo): add a site URL setting, editable in the admin panel` ·
`feat(seo): add robots.txt, sitemap.xml and JSON-LD`

---

## Task B2 — 1:1-Zoom im Lightbox

**Aufwand:** S

### Befund

Der Lightbox rendert `current.previewUrl` (`components/Lightbox.tsx:237`), während sein Dateikopf
„Full-resolution image display" verspricht (`:5`). `imageUrl()` steht per Default auf `'preview'`
(`lib/urls.ts:29`), und **keine Stelle in `app/`, `components/` oder `lib/urls.ts` fordert
`'original'` an** — die oberste Stufe aus `lib/imageSize.ts` ist im Frontend unerreichbar.

Als Default ist das richtig. Für Schärfebeurteilung fehlt der Weg dorthin.

### Schritte

- [ ] **B2.1 — `originalUrl` durchreichen**
  - `originalUrl?: string` in `PhotoItem` (`app/[...path]/PhotoGrid.tsx:18-33`) — **optional**,
    damit `JournalStudio.tsx:616-617` (Admin-Thumbnails über eine andere Route) unverändert bleibt.
  - Befüllen an den zwei öffentlichen Stellen: `app/[...path]/page.tsx:117-118` und
    `app/journal/[slug]/page.tsx:179-180`, jeweils `imageUrl(a.id, 'original')`.
  - Fehlt `originalUrl`, wird der Zoom-Knopf nicht gerendert. Kein Fallback auf Preview — ein Zoom,
    der auf ein Preview zoomt, ist genau die Verwechslung, die es zu beheben gilt.
- [ ] **B2.2 — Zoom-Geometrie als reines Modul** (`lib/zoom.ts`)
  - `clampPan(offset, scale, viewport, natural)` → begrenzt den Bildausschnitt auf die Bildkanten.
  - `zoomAt(point, scale, offset, factor)` → zoomt auf den Cursor/Pinch-Mittelpunkt statt auf die
    Bildmitte. Das ist der Unterschied zwischen brauchbar und ärgerlich.
  - Pure Funktionen, keine DOM-Abhängigkeit — direkt unit-testbar.
- [ ] **B2.3 — Verdrahtung im Lightbox**
  - Zustand: `zoomed` (bool), `scale`, `offset`. Auslöser: Doppelklick/Doppeltipp, Pinch, Taste `z`;
    zusätzlich ein sichtbarer Knopf neben dem Info-Toggle.
  - **Das Original wird erst bei dieser Geste geladen**, nie vorher. Die bestehende
    Nachbar-Vorladung (`Lightbox.tsx:96-105`) bleibt auf `previewUrl` und wird **nicht** angefasst —
    sonst zieht sich jeder Besucher unbemerkt Originale.
  - Ladeindikator, solange das Original unterwegs ist; das Preview bleibt so lange skaliert stehen.
  - Verlassen: `Esc` (erste Stufe verlässt den Zoom, nicht den Lightbox), Doppelklick, Knopf.
  - Zurücksetzen bei jedem Bildwechsel — sonst hängt der Zoomfaktor des vorherigen Bildes am nächsten.
  - **Konflikte prüfen:** `useSwipe` (Pinch/Pan darf nicht als Wisch durchgehen) und
    `AssetProtection` (`dragstart` ist global unterdrückt — Pan muss über Pointer-Events laufen,
    nicht über natives Dragging).
  - Tastatur: `+` / `-` / `0`, `aria-label` am Knopf, Zoomzustand über `aria-pressed`.
- [ ] **B2.4 — Kommentar korrigieren**
  - `components/Lightbox.tsx:5` beschreibt eine Absicht, kein Verhalten. Auf „Preview-tier image,
    with opt-in 1:1 zoom to the original" ändern.
- [ ] **B2.5 — Tests**
  - `lib/__tests__/zoom.test.ts`: Clamping an allen vier Kanten, Zoom auf Punkt, Rückkehr auf
    `scale: 1` zentriert das Bild wieder. Erwartet: **+10 bis +12 Tests**.
  - `e2e/lightbox-zoom.spec.ts`: Zoom öffnet, lädt eine `?size=original`-URL (Request abfangen),
    Pan bleibt in den Grenzen, Bildwechsel setzt zurück.

**Verifikation:** Netzwerk-Tab — beim Öffnen des Lightbox darf **keine** `size=original`-Anfrage
stehen, erst nach der Zoom-Geste. Auf einem Touchgerät gegenprüfen, dass Pinch nicht mehr als Wisch
zum nächsten Bild interpretiert wird.

**Commit:** `feat(lightbox): add opt-in 1:1 zoom against the original asset`

---

## Task B1 — Sequenzierung wie im Fotobuch

**Aufwand:** M — der größte Eingriff hier, und der einzige mit UI-Anteil im Admin.

### Befund

`PhotoGrid` bildet die Assets flach auf ein einziges `.photo-grid`-Element ab
(`app/[...path]/PhotoGrid.tsx:132-243`); das Layout gilt für alle gleich. `assetOrder`
(`lib/config/schema.ts:224`) bestimmt nur die Reihenfolge. Die Essay-Ansicht kennt `fullbleed`,
`wide` und Paare bereits (`lib/journal.ts`) — das Album nicht.

### Designentscheidung: Hinweise leben in `assetOrder`

Eine zweite, parallele Liste (`sequence:`) würde die Reihenfolge doppelt führen und damit
zwangsläufig auseinanderlaufen. Stattdessen wird `assetOrder` erweitert — Sequenzierung setzt
ohnehin `sort: manual` voraus:

```yaml
- 'album-uuid':
    sort: manual
    assetOrder:
      - 'asset-opening': fullbleed # allein, volle Breite
      - 'asset-a': pair # diese beiden nebeneinander,
      - 'asset-b': pair #   auf gleiche Höhe gebracht
      - 'asset-c' # unverändert im normalen Raster
      - break # bewusste Lücke
```

`deriveGallery()` erzeugt daraus **zwei** Strukturen: `albumManualOrders` bleibt exakt wie heute
eine reine UUID-Liste (`break` herausgefiltert), damit `lib/albumSort.ts` unverändert
weiterfunktioniert — und neu `albumSequences: Record<albumId, SequenceEntry[]>` mit den Hinweisen.

### Die Invariante, an der dieses Feature scheitern kann

Der Lightbox-Index und die Permalinks `#photo-N` sind **positional** über `displayedAssets`
(`app/[...path]/PhotoGrid.tsx:51-107`, `openLightbox(index)`). Blockbildung darf deshalb
**ausschließlich gruppieren, niemals umsortieren, nichts auslassen und nichts doppeln**. Wird das
verletzt, öffnet ein Klick das falsche Foto und jeder geteilte Permalink zeigt woanders hin — ein
Fehler, der beim Entwickeln kaum auffällt und beim Kunden sofort.

### Schritte

- [ ] **B1.1 — Schema & Parser**
  - `SequenceHint = 'fullbleed' | 'pair' | 'break'`; `assetOrder?: Array<string | Record<string, string> | 'break'>`
    in `AlbumEntryObject`.
  - In `deriveGallery()` (`lib/config/index.ts:162-236`, direkt neben der `coverPosition`-Validierung):
    unbekannte Hinweise **werfen** mit nennender Meldung — dieselbe Linie wie beim `sort`-Wert, wo
    ein Tippfehler bewusst nicht still durchgeht.
  - `albumManualOrders` bleibt unverändert UUID-only; `albumSequences` kommt dazu (beides in
    `AppConfig`, `GalleryDerivation` und den drei Rückgabestellen in `lib/config/index.ts`).
  - Ein einzelnes `pair` ohne Partner fällt auf normales Verhalten zurück, statt zu werfen —
    beim Umsortieren im Admin ist dieser Zustand ein normaler Zwischenschritt.
- [ ] **B1.2 — Blockbildung als reines Modul** (`lib/sequence.ts`)
  - `buildSequenceBlocks(assets, hints)` → `Array<{ kind: 'grid' | 'pair' | 'fullbleed' | 'break', items: Array<{ asset, index }> }>`.
  - **Jedes Item trägt seinen ursprünglichen Index mit.** Das ist die technische Absicherung der
    Invariante oben.
  - Aufeinanderfolgende Assets ohne Hinweis landen in einem gemeinsamen `grid`-Block, damit das
    bestehende Layout (Masonry, Justified …) darin unverändert greift.
- [ ] **B1.3 — Rendering**
  - `PhotoGrid` rendert Blöcke statt einer flachen Liste; `openLightbox(item.index)` statt
    `openLightbox(index)`.
  - CSS: `.photo-sequence__pair` (zwei Spalten, auf gleiche Höhe normiert über die vorhandenen
    Aspect-Ratios), `.photo-sequence__fullbleed`, `.photo-sequence__break`. Mobil kollabieren Paare
    auf eine Spalte.
  - Ohne Hinweise entsteht genau ein `grid`-Block — das Markup bleibt dann identisch zu heute.
    **Das ist die Rückfallgarantie und gehört als Test festgeschrieben.**
- [ ] **B1.4 — Admin**
  - `AssetOrderEditor.tsx` bekommt pro Foto eine Hinweis-Auswahl und einen Trenner-Einfügen-Knopf.
  - Eine Andeutung der Blöcke in der Sortierliste (Paare zusammengefasst, Trenner als Linie).
    **Ohne diese Vorschau ist das Feature im Admin unbenutzbar** — das ist die halbe Arbeit an der
    Task, nicht das YAML-Schema.
- [ ] **B1.5 — Tests**
  - `lib/__tests__/sequence.test.ts`: Indizes bleiben lückenlos und in Reihenfolge (die Invariante,
    als expliziter Test über ein Album mit allen Hinweisarten); leere Hinweise → genau ein Block;
    verwaistes `pair`; `break` am Anfang und am Ende; Hinweis auf ein Asset, das gar nicht im Album
    ist.
  - `lib/__tests__/config-sequence.test.ts`: Parser akzeptiert die neue Form, wirft bei unbekanntem
    Hinweis, `albumManualOrders` bleibt UUID-only.
  - Erwartet: **+20 bis +25 Tests**.
  - `e2e/sequence.spec.ts`: Klick auf das dritte Foto in einem sequenzierten Album öffnet das dritte
    Foto; `#photo-3` landet auf demselben.

**Verifikation:** Ein Album mit `fullbleed`, einem Paar und einem `break` anlegen, im Browser
ansehen, jedes Foto anklicken und den Lightbox-Zähler gegen die visuelle Position prüfen. Ein Album
**ohne** Hinweise gegen `git stash` vergleichen: das Markup muss identisch sein.

**Commit:** `feat(album): sequence photos into pairs, spreads and breaks (EXPERIMENTAL)`

---

## Task C1 — Ortsauflösung pro Album

**Aufwand:** S

### Befund, präzise

Die Map ist besser gebaut als erwartet: Passwortgeschützte Alben werden **vor** der Aggregation
gefiltert (`app/api/map/route.ts:63-90`), und `lib/mapService.ts:5-11` hält Alben ausdrücklich
getrennt, damit genau das möglich ist. Die öffentliche EXIF-Route gibt Koordinaten gar nicht heraus
— die Map ist die einzige öffentliche GPS-Fläche.

Die Lücke betrifft **öffentliche** Alben: Die Marker-Position ist der Mittelwert der tatsächlichen
Koordinaten (`app/api/map/route.ts:97-104`). Bei einem Album von _einem_ Ort — Garten, Studio,
Wohnung eines Kunden, empfindlicher Naturstandort — ist dieser Mittelwert genau dieser Ort. Der
Marker heißt nach der Stadt und steht auf dem Grundstück.

### Zwei Entwurfsentscheidungen, die vorab feststehen müssen

**1. Keine Geodaten-Abhängigkeit.** Für „Stadtzentrum" bräuchte es einen Ortsdatensatz. Stattdessen
wird die Koordinate **gerastert**: `city` auf 0,05° (~5 km), `country` auf 1° (~110 km). Das ist
dependency-frei, erklärbar und ausreichend — 5 km trennen zuverlässig ein Grundstück von einem
Stadtgebiet.

**2. Marker fassen mehrere Alben zusammen.** Liegen an einer Stadt ein `exact`- und ein
`city`-Album, gibt es trotzdem nur einen Marker. Regel: **die strengste Stufe unter den
beitragenden Alben gewinnt.** Sicherheitsentscheidungen fallen in die vorsichtige Richtung, und die
Alternative — Marker aufspalten — würde über die Kartenansicht verraten, dass ein Album
zurückhaltender eingestellt ist.

### Schritte

- [ ] **C1.1 — Konfiguration**
  - `location?: 'exact' | 'city' | 'country' | 'hidden'` in `AlbumEntryObject` und in
    `SubpageObjectValue`/`SubpageConfig`.
  - `albumLocationModes: Record<string, LocationMode>` in `AppConfig`, befüllt in `deriveGallery()`
    neben `albumCoverPositions`; unbekannter Wert wirft.
  - Präzedenz wie beim Grid: global (neu: `map.locationDefault` in `settings.yaml`, Default
    `exact` = heutiges Verhalten) < Subpage < Album.
- [ ] **C1.2 — `lib/mapService.ts`**
  - Alben mit `hidden` überspringen, bevor gebucketet wird — das ist die einzige Stufe, die gar
    nicht erst in den Cache soll.
  - `locationMode` auf `MapAlbumEntry` mitführen. **Nicht** hier schon runden: gerundete Werte
    aufsummieren und danach mitteln ergibt wieder ungerundete Koordinaten.
- [ ] **C1.3 — `app/api/map/route.ts`**
  - Strengste Stufe der sichtbaren Alben je Marker bestimmen.
  - Mittelwert bilden wie heute, **danach** rastern: `city` → 0,05°, `country` → 1°, `exact` → unverändert.
  - Bei `country` das Stadtlabel weglassen (die Popup-Überschrift wäre sonst genauer als die Position).
  - Ist ein Marker nach dem Ausschluss leer, entfällt er — der Pfad existiert bereits (`allowedAlbums.length === 0`).
- [ ] **C1.4 — Admin & Doku**
  - Auswahlfeld pro Album und pro Subpage im `PageBuilder`, Standard in `SettingsEditor`.
  - `gallery.yaml.example` und `settings.yaml.example` ergänzen, mit einem Satz dazu, **warum** es
    das gibt.
- [ ] **C1.5 — Tests** (`lib/__tests__/map-location.test.ts`)
  - Rasterung: eine Koordinate auf einem Grundstück landet bei `city` sichtbar daneben, bleibt aber
    in derselben Stadt; `exact` verändert nichts.
  - Strengste Stufe gewinnt (alle sechs Paarungen).
  - `hidden` erscheint in keiner Ausgabe — auch dann nicht, wenn ein anderes Album dieselbe Stadt beisteuert.
  - Präzedenz global < Subpage < Album.
  - Erwartet: **+14 bis +18 Tests**.

**Verifikation:** Ein Album mit GPS-Daten von einem einzigen Ort anlegen, `/api/map` einmal mit
`exact` und einmal mit `city` abrufen und die Koordinaten vergleichen; auf der Karte gegenprüfen,
dass der Marker die Stadt trifft, aber nicht mehr die Adresse. Zusätzlich sicherstellen, dass ein
`hidden`-Album auch nach einem Cache-Durchlauf nicht auftaucht (`POST /api/admin/reload`).

**Commit:** `feat(map): make location precision configurable per album`

---

## Reihenfolge und Zusammenhänge

```
E  (Auffindbarkeit) ── unabhängig, bringt die Site-URL, die später auch ein Feed bräuchte
B2 (Zoom)           ── unabhängig, erste Stelle die Originale ausliefert
B1 (Sequenzierung)  ── größter Eingriff, berührt die Lightbox-Index-Invariante
C1 (Ortsauflösung)  ── unabhängig, Datenschutz
                       ↑ B1 und C1 fassen beide lib/config/{schema,index}.ts an,
                         aber verschiedene Felder — nacheinander mergen, nicht parallel
```

Vier PRs, in dieser Reihenfolge. E und B2 sind jeweils an einem Tag abgeschlossen und liefern
sofort etwas Sichtbares; B1 braucht am meisten Sorgfalt und sollte nicht unter Zeitdruck; C1 ist
klein, aber sicherheitsrelevant und verdient einen eigenen, ruhigen Review.

**Erwartete Testsumme am Ende:** 443 → etwa **516**.

## Was dieser Plan bewusst nicht enthält

Aus dem Brainstorm bleiben offen und sind hier **nicht** eingeplant: A1 (Client-Links), A2
(Anfrage-Formular), A3 (Proofing-Notizen), B3 (Farbmanagement-Messung), C2 (terminierte
Veröffentlichung) und D (RSS-Feed). Falls C2 und D später kommen: Beide brauchen dieselbe
Sichtbarkeitsprüfung, die in **E3** entsteht. Sie sollte dort so geschnitten werden, dass ein
zweiter Aufrufer sie wiederverwenden kann, statt sie zu kopieren.