werkbaum/frontend/CLAUDE.md

# Werkbaum · Frontend

Editor: Text links, Diagramm rechts, Toggles für transponierte Ansicht und
verworfene Elemente. Quelle sind ES-Module unter `src/`; `index.html` ist der
**Vite-Entry** (lädt im Dev-Server `src/app.js` als `<script type="module">`).

## Build & Entwicklung (D19)
- **Vite** ist Bündler + Testrunner (nur Dev-Abhängigkeiten, keine Laufzeit-
  Abhängigkeit — das Ergebnis ist framework-freies HTML/CSS/JS).
- `npm --prefix frontend run dev` — Dev-Server (Port 8137, `.claude/launch.json`).
  Direktes Öffnen von `frontend/index.html` per `file://` funktioniert **nicht**
  mehr (ES-`import` braucht http); stattdessen Dev-Server oder die gebaute Datei.
- `npm --prefix frontend run build` — `vite-plugin-singlefile` inlint JS + CSS +
  Favicon (als `data:`-URI, via `transformIndexHtml`-Plugin in `vite.config.js`)
  in **eine** self-contained `dist/index.html` — die bleibt `file://`-tauglich
  (D16) und ist die Deploy-Artefakt-Quelle (Pages-Workflow, siehe README).
- `npm --prefix frontend test` — Vitest (`tests/**/*.test.js`).
- `npm --prefix frontend run build:prod` — Produktions-Build **ohne** den
  Build-Hinweis hinter dem Titel (Vite-Modus `prod`, `.env.prod` setzt
  `VITE_BUILD_BADGE=none`). Nur die echte produktive Installation nutzt diesen
  Weg; Dev-Server (🔧) und Default-`build` (🚧, u. a. Pages-Deploy) zeigen den
  Hinweis. Logik: `mountBuildBadge()` in `app.js` (D16).
- `node_modules/` und `dist/` sind ge-`.gitignore`-t; `.env.prod` und
  `package-lock.json` sind eingecheckt (der Workflow nutzt `npm ci`).

## Konventionen
- Vanilla HTML/CSS/JS, ES-Module; keine Frameworks. Testwerkzeug: Vitest.
- Parser und Renderer müssen headless (ohne Editor-UI) nutzbar bleiben —
  Basis für SVG-Export und Mermaid-Plugin (docs/ROADMAP.md). `app.js` ist der
  DOM-/UI-Einstieg; reine Logik gehört in `parser.js`/`model.js`/`render.js`.
- Design: Farben/Typografie beibehalten (CSS-Variablen, IBM Plex);
  Statusfarben sind in SPEC §4 normiert. Marke nach ../brand/BRAND.md;
  Pastelltöne nie im Logo.
- IBM Plex ist **lokal eingebettet** (`src/fonts/*.woff2`, `@font-face` in
  `style.css`), **nicht** von Google Fonts geladen — kein externer Request,
  keine IP an Dritte (Datenschutz, D20). Keinen `googleapis`-`<link>` wieder
  einführen. Neue Schnitte: `woff2` per `npm pack @fontsource/…` beziehen (keine
  Projekt-Abhängigkeit, Dateien einchecken) und `@font-face` ergänzen.

## Stolperfallen
- Abzweig-Linien zielen auf die **Knotenmitte** (fester 23-px-Offset,
  `line-height: 1.3`), nicht auf die Mitte des Teilbaums — bei Layout-
  Änderungen alle drei Modi (horizontal/vertikal/kompakt) prüfen.
  Vertikal + kompakt teilen die transponierte Basis-CSS; nur vertikal
  bekommt den Rechts-Ausgang für „all of“, kompakt führt auch „all of“
  nach unten. Any-of ist in allen Modi grau: Linien gestrichelt grau und
  Alternative-Rahmen grau (Basis-CSS `ul.or`). Kein Petrol im Diagramm mehr;
  `var(--or)` nur noch für UI-Akzente/Logo (SPEC §9, D15).
- Extraktionsreihenfolge im Parser nicht umstellen: Kommentar → Zeichen/
  Status → URL → Größe → Tags (sonst kollidiert `@` in URLs).
- Fehlertoleranz (SPEC §4): der Parser erfasst die Statusbox als *beliebiges*
  Einzelzeichen `\[([^\]])\]` und validiert gegen `STATUS_BY_CODE`; unbekannte
  Codes → `parse().warnings` als `{type:'unknownStatus', line, code}`, Knoten
  neutral. `render()` in app.js führt Parser- und Renderer-Warnungen zusammen
  (nach Zeile sortiert) und zeigt sie via `formatWarning` (warnings.js). Neue
  Warnungstypen dort + i18n-Key in allen 9 Sprachen ergänzen.
- Modulteilung (D19): `parser.js` (Text→Baum, headless), `model.js` (Baum-/
  Kostenlogik: `gateOf`, `needsBreakdown`, `visibleChildren(n, showDiscarded)`,
  `computeCheapSet`, `cheapCls`), `render.js` (HTML-String via
  `renderTreeHtml(roots, {t, showDiscarded, cheapPath, cheapSet})`, headless),
  `app.js` (DOM/Events/i18n/Persistenz/Export). Modell/Renderer bekommen UI-State
  (verworfene einblenden, Pfad an/aus) als **Parameter** — keine Globals; nur
  `cheapPathOn` lebt als UI-State in `app.js`. Tests: `tests/*.test.js`.
- Günstigster Pfad: `markCheapest()`/`cheapestCost()` (in `model.js`) markieren
  die nötigen Knoten (Klassen `cheap`, `cheap-leaf`); `drawCheapPath()` (app.js)
  zeichnet nach jedem
  `render()` **und** nach `applyLayout()` zwei Overlay-SVGs in `#out` (hinten
  kräftige Linie, vorne abgetönte Kopie + Stationspunkte). Overlays erben den
  CSS-`zoom` von `#out`, Punkte in unskalierte `#out`-Koordinaten umrechnen
  (`/zoom`). `diagramToSvg()` zeichnet dieselbe Linie/Punkte nach (SPEC §9, D18).
- Zerlegt eine any-of-Alternative selbst all-of, wird der Teilbaum **nur
  horizontal** schmal transponiert (`ul.or>li.has-and>ul.and`, siehe D18) —
  sonst schiebt der breite Fächer den Elternbaum nach rechts. Bei Layout-
  Umbauten dieses Nesting mitprüfen.
- „verworfen" ist per Default ausgeblendet; Filterlogik steckt in
  `visibleChildren()` und muss bei Renderer-Umbauten erhalten bleiben.
- Barrierefreiheit (SPEC §9): `render.js` baut je Knoten einen sprechenden
  `aria-label` (Label + Status + Aufwand + Zuständige + Link, lokalisiert via
  `t`); die visuellen Badges (Größe, Tags, ↗) sind `aria-hidden`. Neue
  Knoten-Eigenschaften dort in `nodeAria()` mitpflegen und dafür a11y-i18n-Keys
  (`a11y*`) in **allen 9 Sprachen** anlegen. Knoten sind `tabindex="0"`
  (Fokus = Lesereihenfolge), `#warn` ist eine Live-Region.
- Zustand wird im `localStorage` gehalten (noch kein Backend): `werkbaum-lang`
  (Sprache), `werkbaum-docs` (JSON-Array der Dokumente `[{id,name,text}]`),
  `werkbaum-active` (id des aktiven Dokuments), `werkbaum-src` (Spiegel des
  aktiven Texts, Abwärtskompatibilität), `werkbaum-ui` (JSON: Modus, verworfene,
  günstigster Pfad, Split-Zustand inkl. `--col`/`--drow`, Zoom, Vollbild). Neue
  GUI-Einstellungen in `saveUI()`/`restoreState()` mitführen; `saveUI` liefert
  während `restoring===true` nichts, damit das Wiederherstellen nicht sofort
  zurückschreibt.
- Dokumente (D22): mehrere umschaltbare Notationstexte. `loadDocs()` migriert bei
  fehlendem `werkbaum-docs` den bestehenden `werkbaum-src` (oder `INITIAL`) in
  **ein** Dokument; `initDocs()` (Aufruf **nach** `applyLang`) holt den aktiven
  Text in den Editor. `saveSrc()` schreibt den Editortext ins aktive Dokument.
  Der Wähler ist ein Dropdown in der Editor-Titelzeile (`#docTrigger`/`#docMenu`,
  ersetzt die frühere feste „Struktur (Text)"-Beschriftung); Wechseln/Neu/
  Umbenennen/Löschen in `switchDoc/newDoc/renameDoc/deleteDoc`. Jedes Dokument ist
  nur Text + Name (kein Strukturformat, D14) — vorwärtskompatibel zum Backend
  (D13). Ansichts-State (`werkbaum-ui`) bleibt global über alle Dokumente. Ein
  leerer Editortext bleibt leer.
- Beispiel-Dokument (D22): reservierte id `EXAMPLE_ID = 'example'`, fester
  englischer Name `EXAMPLE_NAME = 'Example'` (nicht lokalisiert). `loadDocs()`
  adoptiert einen Alt-Zustand (zufällige id, „Beispiel") nur, wenn dessen
  `text === INITIAL` (nie echte Nutzerinhalte). `resetToDefaults()` setzt **nur**
  das Beispiel-Dokument (id `example`) auf `INITIAL`/„Example" zurück und verwirft
  `werkbaum-ui`/`werkbaum-lang`/Update-Flags — **andere Dokumente bleiben stehen**
  (nicht mehr pauschal alle `werkbaum-*` löschen!). Das letzte gelöschte Dokument
  wird als Beispiel neu gesät.
- Mitgeliefertes Dokument „Werkbaum" (D27): `app.js` importiert
  `../../docs/examples/example-werkbaum.werkbaum?raw` — die Beispieldatei ist
  damit **Build-Eingabe**, Umbenennen/Verschieben bricht den Build (Zugriff
  außerhalb des Roots erlaubt `server.fs.allow:['..']`). `seedShippedDocs()` legt
  es **einmalig** an (auch für Bestandsnutzer); ohne den Merker `werkbaum-seeded`
  käme ein gelöschtes Dokument bei jedem Laden zurück. Der Merker hält den
  **Fingerabdruck** der ausgelieferten Fassung: Ändert sich die Datei, wird der
  Text nur nachgezogen, wenn der Nutzer ihn **nicht** bearbeitet hat. Wer die
  Beispieldatei ändert, ändert damit das mitgelieferte Dokument mit.
  `resetToDefaults()` setzt beide mitgelieferten Dokumente **und** den Merker.
- Umbenennen ist **inline** (kein `window.prompt` — in manchen Browser-Kontexten
  unterdrückt): `renameDoc()` setzt `renamingId`, `renderDocMenu()` rendert dann
  ein `<input class="docrename">` (Enter = `commitRename`, Esc = `cancelRename`,
  Blur = commit). Doc-Namen sind Nutzerdaten und werden **nicht** übersetzt.
- `?sourceUrl=` (D23): `loadFromSourceUrl()` (Aufruf am Ende des Starts, async)
  holt eine externe Textdatei und führt sie als Dokument mit `id: 'url:<href>'`,
  `name`/`source` = URL. Nur `http(s)`, `credentials:'omit'`; bei jedem Laden wird
  neu geholt (URL = Quelle der Wahrheit, lokale Edits daran gehen verloren).
  Fehler landen als zeilenlose Warnung `{type:'sourceLoad', url, error}` in
  `sourceWarning` — ein **persistenter** Kanal, den `render()` jedem Warnungs-Satz
  voranstellt (überlebt Neu-Renderings, bis das Laden gelingt). Hauptstolperfalle
  ist **CORS**: fremde Hosts brauchen `Access-Control-Allow-Origin` (raw.github…
  ja, beliebiger Webserver oft nicht) — der Warntext nennt das ausdrücklich.
  `updateDocName()` setzt für solche Dokumente den vollen URL-Tooltip und muss
  deshalb **nach** dem `data-i18n-title`-Durchlauf in `applyLang()` laufen.
  Weder Endung noch `Content-Type` werden geprüft (`response.text()`); die
  Endung `.werkbaum` ist reine Konvention (D24, SPEC §12). Beispieldateien zum
  Ausprobieren: `docs/examples/*.werkbaum` (nacheinander geöffnet ergeben sie
  mehrere Dokumente im Wähler).
- `?etherpad=` (D31): `remoteSource()` liefert **einen** Beschreiber für beide
  Eingänge (`?sourceUrl=` und `?etherpad=`), `loadRemoteSource()` holt und legt
  das Dokument an — ein Fetch-Pfad, ein Warnkanal. Die Normalisierung der
  Pad-Adresse steht headless in **`remote.js`** (`padUrls`, Tests in
  `tests/remote.test.js`): Export-/Timeslider-Pfad, Query, Fragment und
  Schrägstriche fallen weg, verlangt wird `/p/<name>` am Ende. Name und id sind
  die **vollständige** Pad-URL (Pad-Namen sind nur pro Instanz eindeutig).
  `padSource` muss **vor** `loadActiveIntoEditor()` gesetzt werden — daran hängt
  der Schreibschutz. `pollPad()` hat drei Riegel, jeder aus einem echten Fehler:
  `padBusy` (höchstens ein Abruf unterwegs — sonst stapeln sich Anfragen und eine
  spät eintreffende alte Antwort überschreibt neueren Text, im
  Netzwerk-Mitschnitt beobachtet), `PAD_FETCH_TIMEOUT_MS` (ohne Abbruch bliebe
  `padBusy` bei hängender Gegenseite für immer zu) und `visibilityState`
  (+ `visibilitychange`-Handler, der bei Rückkehr sofort holt). Fehlschläge im
  Takt bleiben **stumm**; nur der erste Ladeversuch warnt. Der Stabilitätstakt
  (`padPending`) übernimmt erst beim zweiten gleichen Abruf — sonst sieht man die
  anderen mitten im Tippen. Beim Prüfen im Vorschau-Browser: `visibilityState`
  ist dort `hidden` (Polling also aus) und HMR lädt bei jeder Quelländerung neu —
  ein Reload sieht wie eine geglückte Übernahme aus. Marker auf `window` setzen
  und hinterher prüfen, sonst beweist der Test nichts.
- Sprung Diagramm ↔ Text (D25): `render.js` schreibt die Parser-Zeilennummer als
  `data-line` an jeden Knoten (Geister-Knoten bekommen keine). `jumpToLine()` in
  `app.js` klappt bei Bedarf das Editor-Panel auf (`revealEditor()`), markiert die
  **ganze Zeile** und scrollt über einen Spiegel-`div` (`offsetTopInEditor()`) —
  Zeilenhöhe × n scheitert an weichen Umbrüchen. Ausgelöst per Alt+Klick,
  Alt+Enter und langem Druck; der Klick-Handler **muss `preventDefault()`** rufen,
  sonst lädt Alt+Klick auf einen Link-Knoten das Ziel herunter. Gegenrichtung:
  `syncCaret()` setzt die Klasse `current` auf den Knoten der Cursor-Zeile;
  `render()` stellt sie nach jedem Neubau wieder her (ohne zu scrollen). Die
  CSS-Regel braucht den `#out`-Präfix (`ul.or .node{box-shadow:none}` ist
  spezifischer). Auffindbarkeit: `setAltMode()` setzt bei gedrückter Alt-Taste
  die Klasse `alt` an `#out` (Cursor + Ring am Knoten unter dem Zeiger) — der
  `blur`-Handler ist Pflicht, sonst bleibt der Modus nach Alt+Tab hängen; dazu
  `jumpHint` im Knoten-Tooltip und `hint_jump` als letzte Zeile der Legende.
- Touch-Langdruck (D25): Der Timer (500 ms) setzt **nur** die Klasse `armed`
  (Petrol-Ring); `jumpToLine()` läuft im `touchend`-Handler. Nicht zurück in den
  Timer verlegen — **`focus()` aus einem Timer gilt in mobilen Browsern nicht als
  Nutzergeste**, das Textfeld verliert den Fokus sofort wieder (Symptom: die
  Markierung flackert nur auf). Gegen die native Langdruck-Auswahl braucht es
  alle drei Schichten: `contextmenu`-`preventDefault` während des Drucks,
  `user-select:none` per `@media (hover:none) and (pointer:coarse)` und
  `-webkit-touch-callout:none` (nur iOS). Synthetische `TouchEvent`s prüfen
  davon **nichts** — nur die eigene Ereignis-Logik.
- Bildschirmtastatur (D25): `jumpToLine()` setzt vor dem Fokus `inputmode="none"`
  (`keyboardOnJump(true)`) — der Sprung ist „hinschauen". Der `pointerdown`-
  Handler am Textfeld hebt das wieder auf (läuft vor dem Fokus). Wer sonst
  irgendwo `src.focus()` ergänzt und dabei Tippen meint, muss vorher
  `keyboardOnJump(false)` rufen — so wie `newDoc()`.
- Legende (D26): **kein `<details>`** — Chrome legt Details-Inhalt in
  `::details-content`, dadurch war `.hint` kein Flex-Kind mehr und ließ sich nicht
  begrenzen (Inhalt geclippt statt scrollbar). Jetzt `div.agenda` +
  `button.agenda-summary`, Zustand an der Klasse `open` (`setAgendaOpen()` hält
  Klasse, `aria-expanded`, `#legendBtn` und die Sichtbarkeit des Splitters
  zusammen). Wer hier wieder ein natives Aufklapp-Element einsetzt, bricht das
  Scrollen. Der Splitter `#hintGutter` schreibt `--hcol` (nebeneinander) bzw.
  `--hrow` (gestapelt: `side` oder mobil) an `#app`; beide werden getrennt in
  `werkbaum-ui` gesichert. Die 85-%-Obergrenze steht **zusätzlich** als
  `max-width`/`max-height` im CSS — die gespeicherte px-Größe würde den Editor
  sonst erdrücken, wenn das Panel später schrumpft.
- „Was ist neu?" (D28): `freshProdSet(prevRoots, currRoots)` in `model.js` liefert
  die Knoten, die **neu `[^]`** sind (Identität = Label-Pfad, nicht Zeile).
  `render()` bildet die Menge **bei jedem Durchlauf neu** aus den gerade
  geparsten `roots` — eine vorab berechnete Menge stammte aus einem anderen
  Parse-Durchlauf und träfe per Objektidentität nie zu (genau dieser Fehler ist
  passiert: Zähler stimmte, nichts leuchtete). Vorgehalten wird nur
  `freshPrevRoots` (Basis, einmal geparst). Basis je Dokument in `werkbaum-seen`,
  fortgeschrieben **erst beim Bestätigen** über `#freshBtn`.
- Optionale Knoten `+` (D29): Der Parser setzt **`optional:true` und lässt
  `type:'and'`** — `+` gehört zum Knoten, nicht zur Gruppe. Deshalb bleiben
  `gateOf()` und die `mixedGate`-Warnung unverändert richtig (sie meldet nur
  `|` neben `-`/`+`). Aus dem günstigsten Pfad fallen optionale Knoten über
  **`pathChildren()`** heraus — die eine Stelle, die `cheapestCost()` und
  `markCheapest()` gemeinsam nutzen; deshalb wirkt sie samt Teilbaum. Der hohle
  Kreis ist `.node.opt::before`: **Grundfall links/50 %** (gestapelt), Ausnahme
  **oben/50 %** im horizontalen Fächer, Rück-Ausnahme wieder links für
  `ul.or>li.has-and>ul.and>li` (D18). Im SVG-Export muss er **nach** den Knoten
  gezeichnet werden (`optMarks`, Schritt 3a) — er liegt halb außerhalb der Box
  und würde sonst vom Knoten-Rechteck überdeckt. Der **Abzweig** ist zusätzlich
  gestrichelt (Tinte); dafür trägt auch das **`<li>`** die Klasse `opt`, denn den
  Abzweig zeichnen dessen Pseudoelemente. Gestrichelt wird nur die Kante zum
  Knoten, nie die Sammelleiste — im Fächer `border-left`/`-right`, gestapelt
  `border-top`.
- Treppe optionaler Endknoten (D29, Nachtrag 3): `applyOptStairs()` gruppiert
  **in app.js**, nicht im Renderer — die DOM-Ebene `li.opt-group > ul.opt-stair`
  gibt es semantisch nicht und müsste in den drei übrigen Anordnungen wieder
  neutralisiert werden. Deshalb: nur im Fächer bauen, beim Moduswechsel
  auflösen (die Funktion räumt immer zuerst auf, `applyLayout` arbeitet auf dem
  bereits gruppierten Baum). Reihenfolge: `applyOptStairs()` **vor**
  `alignStems()`/`drawCheapPath()`, es verschiebt Knoten. Bedingung ist „`<li>`
  hat genau ein Element-Kind, und das ist der Knoten" — also kein Teilbaum und
  kein Geister-Knoten, weil die Stufengeometrie Zellenhöhe == Knotenhöhe
  voraussetzt. Der SVG-Export hängt nur die **erste** Stufe an die Leiste und
  zieht die übrigen als Winkelkette nach; flach eingereiht lief die Linie zur
  dritten Stufe hinter der zweiten hindurch.
- `--stem-x` (D29, Nachtrag 2): Im horizontalen Fächer sitzt der Stiel bei 50 %
  des `<li>`. Das ist nur dann die Knotenmitte, wenn der Knoten in der Zelle
  zentriert steht — `li.has-or` ist aber linksbündig und die Zelle so breit wie
  der any-of-Teilbaum. `alignStems()` misst deshalb nach jedem `render()` (und
  in `applyLayout`) die Knotenmitte und setzt `--stem-x`; Fallback im CSS ist
  `50%`. Messwerte durch `zoom` zurückrechnen, sonst stimmt es nur bei 100 %.
- Kleiner Bildschirm: `body.mobile` (per `matchMedia`, ≤ 640 px) stapelt
  Diagramm/Editor mit **stufenlosem** Splitter (kein Snap/Collapse wie auf
  Desktop): der Gutter-Drag ruft `setMobileDrow()` (klemmt `--drow` zwischen den
  Kopfhöhen `--pmin-d`/`--pmin-e`, per `syncPanelMins()` gemessen), ein Tipp auf
  eine Titelzeile maximiert das Panel. `applyLayout` ruft auf Mobil **kein**
  `applySplit` (das würde `--drow` löschen). Dazu eigener Legenden-Umschalter
  (`#legendBtn`), schlanke Sprachwahl, Download-Overlay; Default Vollbild +
  Diagramm maximiert. Layout-CSS hängt an `body.mobile`, nicht an einer eigenen
  `@media`-Regel — beide Seiten müssen denselben 640-px-Schwellwert nutzen
  (SPEC §9, D17).