# Zustand · Digitalisierungsplanung

Zustand visualisiert Firmenabläufe als klickbare State Charts. Der Editor bewahrt den etablierten Desktop- und Mobile-Arbeitsablauf:

- Eigenschaften links
- App-Vorschau rechts
- Vorlagen-Dock unten
- Canvas mit Single- und Mehrfachauswahl, Doubleclick, Drag, Pan, Wheel-Zoom und Rectangle-Select
- Touch mit Doubletap, Hold-to-drag, Pan und Pinch-Zoom
- mobile Ansichten für Vorlagen, Canvas, Bearbeitung und App

Der öffentliche Product Contract enthält die fünf frei einsetzbaren Basic-Presets und neun direkte Aufnahme-Presets. Das Canvas-, Drawer- und Eingabesystem bleibt davon unabhängig.

## Produktkern

1. States und Transitionen bilden einen realen Prozess ab.
2. **App-Flow** rendert immer das aktuelle Editor-Modell und lässt genau diesen Prozess durchklicken – unabhängig davon, ob States aufgenommen, importiert oder von Hand geändert wurden.
3. **Aufnahme** läuft über die Browser-Extension in einem normalen Chrome-/Edge-Tab. Ohne installierte Extension zeigt der Recorder direkt den integrierten Download und die Installationsanleitung.
4. Der Recorder speichert als Replay-Wahrheit ausschließlich bereinigte Rohaktionen mit Website-Zuordnung, Click-/Input-Ziel und Timing. Alle Zeiger- und Scrollbewegungen seit der vorherigen Aktion bleiben als zeitgestempelte Pfade im nächsten Click-/Input-/Key-State erhalten; Bewegung allein erzeugt keine zusätzlichen States. Endet die Aufnahme direkt nach einem Scroll, wird nur dieser letzte, sonst verlorene Abschluss als Scroll-State gesichert. Pro Aktions-State entsteht daneben ein echtes Website-Teil-GIF als Evidence; DOM-Kopien oder Checkpoints werden nicht gespeichert.
5. Jede Rohaktion wird als `recorded_input` direkt im erzeugten State gespeichert; Zustände und Transitionen wachsen während der Aufnahme im selben Editor-Modell. Nach Reload ist dieses Blueprint selbst die Replay-Quelle.
6. **Fertig** übernimmt die Aufnahme automatisch. Im App-Preview startet **Play** den aufgezeichneten State-Flow selbstständig und folgt dabei den State-IDs im Editor; manuelles Durchklicken ist nicht nötig.

Die fünf Basics sind Überschrift, Button, Textfeld, Dropdown und Checkbox. Aufgenommene States werden aus derselben globalen Rohaktion direkt als **Website-Start**, **Klick**, **Text eingeben**, **Geschützte Eingabe**, **Auswahl ändern**, **Checkbox setzen**, **Option wählen**, **Taste drücken** oder **Scrollen** dargestellt. Der Preset-Typ wird aus `recorded_action` und `recorded_input` abgeleitet und nicht als zweite Wahrheit gespeichert.

## Website aufnehmen

Der normale Ablauf ist bewusst kurz:

1. URL eingeben und **Aufnehmen** wählen. Ist die Extension nicht installiert, öffnet sich kein Ziel-Tab: Der Recorder zeigt direkt den integrierten Download und die Installationsanleitung.
2. Nach der Installation **Erneut prüfen** wählen und anschließend **Aufnahme starten**. Die Website öffnet sich dann in einem normalen Browser-Tab.
3. Website normal bedienen. Jede echte Browseraktion wird mit Timing, Ziel-Locator und – soweit vorhanden – Cursor- beziehungsweise Scrollpfad live als schlanke State-Transition in den Canvas geschrieben.
4. **Website-Replay abspielen** im Editor öffnet dieselbe Website und führt die gespeicherten Rohaktionen mit ihrem Timing aus.

Ein exportierter State-Blueprint wird im Editor über **State laden** importiert. Die Datei enthält die deterministischen Rohaktionen bereits in den State-Daten; danach steht **Website-Replay abspielen** auch nach einem Reload wieder zur Verfügung. Ältere `website-flow.json`-Pakete bleiben als kompatibler Import möglich.

Ist bereits ein inhaltlicher Chart vorhanden, fragt Zustand vor Beginn einmal nach, ob die Aufnahme ihn ersetzen darf. Ein expliziter Abbruch kann das vorherige Modell wiederherstellen.

Damit sieht die Zielwebsite den echten Nutzerbrowser mit seinem bestehenden Cookie-/Login-Kontext; es gibt keinen serverseitigen Bot-Browser, keine Recorder-Sessions und keinen serverseitigen Replay.

## Verträge

- `state-blueprint-definition`, `schemaVersion: 2`: Editorprojekt mit einem kanonischen `model`
- `flow/1`: kleiner öffentlicher Produktvertrag
- `website-recording/1`: transportables Aufnahme-Paket

`website-recording/1` enthält nur die bereinigten Rohaktionen `click`, `input`, `key` und als Abschluss-Fallback `scroll` sowie URL-/Timing-Metadaten. Falls erfasst, gehören der zeitgestempelte Cursorpfad, der absolute `scrollPath` und die auf `0` bis `1` begrenzte Zielposition `relativeX`/`relativeY` zur nächsten ausgeführten Aktion. Der globale Aktions-State trägt zusätzlich sein `recording_evidence` als GIF des echten sichtbaren Website-Ausschnitts; dieser visuelle Beleg wird nie zu Replay-Input. Die direkte Preset-Darstellung wird aus dieser Rohaktion abgeleitet und erzeugt weder eine Preset-ID im State noch einen zweiten Aufnahmebaum. DOM-/HTML-Kopien, Checkpoints und Fingerprints sind ausdrücklich ausgeschlossen.

Beim Website-Replay prüft die Extension vor jeder Aktion URL und Ziel-Locator. Bei kleineren URL-/DOM-Abweichungen sucht sie ein kompatibles Ziel und führt den Ablauf weiter; ist ein einzelner Schritt nicht mehr ausführbar, wird nur dieser sichtbar markiert und übersprungen. Der Ziel-Tab bleibt für die Diagnose sichtbar und bietet **Zurück zum Editor**.

Der erste Schritt startet nach dem Browser-Ready-Gate spätestens nach 1,5 Sekunden zusätzlichem Leerlauf. Die bei der Aufnahme enthaltene Tab-Start-/Ladezeit wird nicht ein zweites Mal abgesessen. Spätere Benutzerpausen bleiben erhalten und werden im Replay-Overlay sichtbar angekündigt; Bewegungspausen halten den Cursor beziehungsweise Scrollstand fest, statt eine lange Zeitlupenfahrt zu erzeugen.

Details: [docs/state-contract.md](docs/state-contract.md).

## Lokal entwickeln

Voraussetzung: Node.js 24.

```bash
npm ci
npm run build:index
npm run test:server
```

Für die Browser-Tests wird Playwright ausschließlich als Entwicklungs-/CI-Werkzeug verwendet:

```bash
npx playwright install chromium
npm run test:browser
```

Runtime und Editor lokal starten:

```bash
npm run server:start
node tests/serve-state.mjs
```

- Editor: `http://127.0.0.1:8124/state.html`
- Runtime: `http://127.0.0.1:8788/healthz`

## Produktion

GitHub Pages liefert Editor, App und Recorder. `realtime.digitalisierungsplanung.de` liefert nur:

- Release-Health
- Product Contract
- begrenzten Import öffentlicher Bild-URLs

Es gibt keinen serverseitigen Recorder-Browser, keine Recorder-Sessions und keinen Server-Replay.

Der Pages-Auslieferungsvertrag lädt Editor, App und Recorder aus dem unveränderlichen Pfad `/releases/release-N/`. Bereits geladene immutable Releases starten ohne Runtime-Abhängigkeit; bei einem vorübergehenden Resolver-Ausfall verwendet der Einstieg den statischen Pages-Marker und blockiert die App nicht. Die Pipeline testet zuerst den Source-Commit, erzeugt danach einen monotonen `release-N`-Commit und wartet auf Produktionskonvergenz.

Der Server-Auto-Deploy prüft das vollständige veröffentlichte Bundle, bevor er den gesunden Checkout verändert. Unvollständige oder verzögerte Pages-Versionen werden nur protokolliert und beim nächsten Timer-Lauf erneut geprüft. Zehn immutable Releases bleiben für Rollbacks erhalten; der Deployment-Marker wird erst nach erfolgreicher Runtime- und Contract-Prüfung weitergeschaltet.

Ein Frontend-Release enthält `index.html`, `state.html`, `recorder.html`, `release-version.js` sowie `browser-recorder-extension.zip` und `INSTALL-BROWSER-RECORDER.md`; das Manifest weist diese sechs Dateien in dieser Reihenfolge aus.

- [digitalisierungsplanung.de](https://digitalisierungsplanung.de)
- [Runtime-Health](https://realtime.digitalisierungsplanung.de/healthz)
- [Product Contract](https://realtime.digitalisierungsplanung.de/contract)

## Relevante Dateien

- `state.html` – visueller Editor und generierte App-Vorschau
- `recorder.html` – Extension-Recorder, deterministische Rohaktionserfassung und Live-Sync
- `scripts/write-pages-release.mjs` – baut den unveränderlichen Frontend-Release
- `server/server.js` – kleine Runtime für Health, Contract und sicheren Bildimport
- `server/product-contract.js` und `server/preset-catalog.js` – Minimalvertrag, fünf Basics und neun direkte contract-konforme Aufnahme-Presets
- `server/deploy.sh` und `server/auto-deploy.sh` – Green-Release-Deploy und Rollback
- `tests/local-browser-recorder.spec.js` – Recorder-Integration und deterministischer Rohaktionsvertrag
- `scripts/production-smoke.mjs` – produktive Freigabeprüfung