journey-demo

Was macht journey-demo?

Schreibe einen Journey, führe ihn aus, schneide ihn. Claude führt eine Benutzerreise in Chrome aus, speichert jeden Bildschirm als eingefrorene HTML-Seite, legt die Bilder auf einem Storyboard an, das der Benutzer im Browser bearbeitet, und rendert erst nach Genehmigung ein MP4 mit HyperFrames. Es wird keine Bildschirmaufnahme gemacht, sodass jedes Wort auf jedem Bildschirm später geändert werden kann, ohne die Reise erneut auszuführen.

Quelle der Wahrheit: STORYBOARD.md + snapshots/*.html im Demo-Ordner. Alles andere wird generiert.

Voraussetzungen

• Chrome mit der Claude in Chrome-Erweiterung (um die Reise auszuführen und aufzuzeichnen)
• Node 18+ und npx hyperframes (Standbilder und das Rendering; kein Installationsschritt)
• Skripte in dieser Fähigkeit: scripts/freeze.js (Aufnahme), scripts/demo.mjs (Erstellung und das bearbeitbare Board). Führe sie über den Pfad aus: node <diese-faehigkeit>/scripts/demo.mjs …

Der Demo-Ordner

docs/demos/<slug>/ im Repository der Person, es sei denn, sie nennen einen anderen Ort:

STORYBOARD.md        der Plan: Bilder, Bildunterschriften, Klicks, Timing, Anmerkungen      (bearbeiten)
snapshots/*.html     die aufgenommenen Bildschirme                                    (nur Text bearbeiten)
index.html scenes/ boards/ .build/    generiert von demo.mjs                 (niemals bearbeiten)
out/<slug>.mp4       das Rendering

Schlage vor, scenes/ .build/ boards/stills/ out/ in die Git-Ignorierliste aufzunehmen.

1. Der Journey

Verwende eine Journey-Datei, wenn eine vorhanden ist (docs/journeys/*.md: Start:, nummerierte Schritte, Expect:-Prüfungen, > Note:-Zeilen). Wenn die Fähigkeit browser-journeys installiert ist, besitzt sie dieses Format und seine Ausführungsregeln, und du befolgst sie. Noch kein Journey? Schreibe zuerst einen mit der Person: Die Demo ist nur so gut wie die Schritte.

Frage vor der Ausführung in einer Nachricht, mit deiner Empfehlung für jeden Punkt:

• Host: lokal oder Staging; niemals Produktion, es sei denn, sie sagen es.
• Branch: Wenn der Journey eine Wahl bietet (aus Bibliothek kopieren oder neu schreiben, gespeicherte Karte oder neue Karte), welchen Pfad die Demo zeigt. Standard: der kürzeste Happy Path.
• Werte: Die Testwerte des Journeys („Journey-Test – bitte ignorieren“) oder demofreundliche Werte, die du vorschlägst. Standard: demofreundliche vorschlagen und überall verwenden, wo sie erscheinen.
• Nachricht und Zielgruppe: Beides aus dem Journey entwerfen; sie bestätigen.
• Nebenwirkungen: Sage, was der Lauf auf diesem Host erstellt (Konten, Bestellungen, Gebote) und die Bereinigung des Journeys, falls vorhanden.

Ein Journey, der für einen anderen Host geschrieben wurde (Start: local, Seed-Befehle, Codes aus einem Entwicklungslog)? Seine Setup-Zeilen gehören zu diesem Host: Frage nach den Äquivalenten auf diesem, rate niemals.

2. Ausführen und aufnehmen

1. resize_window auf 1440×900 und diese Größe für den gesamten Lauf beibehalten: Jedes Bild muss einen Viewport teilen, und die Erstellung verweigert gemischte Größen.
2. Jeden Schritt so ausführen, wie der Journey es sagt. Jede Expect:-Prüfung durchführen; bei einem Fehler anhalten und melden. Eine Demo wird niemals auf einem fehlerhaften Flow erstellt. Ein Aufnahmelauf muss nicht in einem ansehbaren Tempo erfolgen: Warte nur, bis die Seite sich gesetzt hat, bevor du jedes Bild einfrierst.
3. Anmeldung und Personenwechsel sind Sache der Person. Sage „Melde dich als an und sag mir, wenn du fertig bist“, warte, dann mach weiter. Ein Code, den der Journey in ein von dir gestartetes Entwicklungslog druckt, darf von dir eingegeben werden; niemals ein Passwort oder ein Code aus dem Posteingang einer Person. Friere keine Anmeldebildschirme ein (sie zeigen E-Mails): Das Storyboard schneidet von vor der Anmeldung zu danach.
4. Wähle die Bilder: ein Klick pro Bild. Ein Bild ist der Bildschirm direkt vor einem Klick, den der Betrachter braucht, um dem Flow zu folgen. Tippen, Ankreuzen und Auswählen geschehen vor dem Einfrieren, sodass das Bild sie erledigt zeigt; wenn das Bild ein leeres Feld zeigen soll, friere vor dem Tippen ein. Ein Bildschirm, der per URL erreicht wird oder nichts zu drücken hat, ist ein Bild ohne click (es blendet ein). Überspringe Setup und Anmeldung. Ziel: 4–8 Bilder, und friere immer den letzten Bildschirm ein.
5. Einfrieren: Füge den gesamten Inhalt von scripts/freeze.js mit javascript_tool in die Seite ein (einmal pro Seitenaufruf; typeof window.__freeze zeigt dir den Status), dann await window.__freeze('03-open-the-orbit') (zweistellige Reihenfolge, dann ein Slug). Vergleiche den zurückgegebenen viewport mit dem des ersten Bildes; wenn er abweicht (weil ein Download- oder Infobanner geöffnet wurde), schließe das Banner und friere erneut ein.
6. Jeder Einfriervorgang lädt <name>.html in ~/Downloads herunter. Verschiebe sie nach snapshots/, wenn der Lauf endet. Wenn ein Name erneut eingefroren wird, speichert Chrome <name> (1).html: Lösche zuerst den alten Download. Falls Chrome fragt, ob mehrere Downloads erlaubt werden sollen, klickt die Person auf „Erlauben“.

3. STORYBOARD.md schreiben

Das Storyboard-Format von HyperFrames. Ein Bild pro eingefrorenem Bildschirm:

---
message: Ein Orbit in unter einer Minute öffnen
audience: YouTube-Ersteller, die überlegen, ob sie ShoutOrbit ausprobieren
journey: docs/journeys/create-an-orbit.md (Schritte 4–5, Staging, 2026-11-13)
url: staging.shoutorbit.com
status: draft
---

## Bild 3: Den Orbit öffnen (8-12s)
- duration: 4s
- snapshot: 03-open-the-orbit.html
- click: Den Orbit öffnen
- scene: Daten und Angebote füllen sich selbst aus

Der untere Teil des Formulars, Daten bereits ausgefüllt. Der Cursor drückt „Den Orbit öffnen“.
Offene Frage: Das Titelfeld zeigt noch seinen Platzhalter. Soll der Text auf dem Bildschirm eingetippt werden, oder bleibt es so?

• click: Das gesamte Label des Elements, exakt: sein sichtbarer Text, Wert, Platzhalter oder aria-label („Gebot abgeben · 25 $“, nicht „Gebot abgeben“). Die Erstellung findet es bei jedem Lauf und scheitert laut, wenn es nicht gefunden wird. Lasse es bei einem Bild ohne Klick weg.
• duration: Sekunden auf dem Bildschirm, 3–5; 4s, wenn weggelassen.
• scene: Die Bildunterschrift auf dem Bildschirm: kurz, darüber, was der Betrachter bekommt („Daten füllen sich selbst aus“), nicht, was er drückt.
• Planzeilen: Was das Bild zeigt und was der Cursor tut, in einfachen Worten.
• Offene Frage: Eine Zeile pro Sache, die die Person entscheiden muss. Schaue jeden eingefrorenen Bildschirm an auf: Test- oder Schattendaten auf dem Bildschirm; persönliche Daten (E-Mails, echte Namen, Kontonummern); Platzhalter, wo echte Werte hingehören; eine Bildunterschrift, die der Bildschirm widerspricht („live“ über „Noch keine Gebote“); veraltete Daten. Hebe sie hervor; behebe sie niemals stillschweigend.

4. Erstellen und Board übergeben

node <skill>/scripts/demo.mjs serve docs/demos/<slug> --port 4321   # im Hintergrund ausführen

Es erstellt und bedient dann http://127.0.0.1:4321/. Öffne es für die Person (Chrome oder open) und stoppe. Auf dem Board können sie Bildunterschriften, Klicks, Sekunden, Titel und Reihenfolge ändern, Bilder entfernen, Notizen für Claude schreiben, Wörter auf der aufgenommenen Seite selbst neu tippen (Seitentext bearbeiten; das Umbenennen des angeklickten Elements überträgt den Klick mit) und Für Rendering freigeben drücken. Jede Speicherung baut die Standbilder neu auf.

5. Auf Notizen reagieren

Wenn sie sagen, dass sie Notizen hinterlassen haben, lies STORYBOARD.md. Für jede > Note:-Zeile:

Sie fragen nach	Änderung
Bildunterschrift, Timing, Reihenfolge, Klick	Die Schlüssel des Bildes in STORYBOARD.md
Andere Wörter auf der Seite	Text in dieser snapshots/*.html (nur Text: Tags und Klassen behalten)
Ein Bildschirm, der nicht aufgenommen wurde, oder ein anderer Zustand	Führe diesen Journey-Schritt erneut aus und friere ihn ein
Etwas, das der Flow nicht zeigen kann	Sage das; biete die nächstliegende wahre Version an

Wandle dann die Notiz in > Erledigt: <was geändert wurde> um (das Board zeigt diese als erledigt), setze status: draft im Frontmatter (nur die Person gibt frei), führe node <skill>/scripts/demo.mjs build docs/demos/<slug> aus und sage ihnen, sie sollen das Board aktualisieren. Der Server kann weiterlaufen.

6. Rendern

Nur wenn das Frontmatter status: approved sagt oder die Person im Chat grünes Licht gibt:

cd docs/demos/<slug> && npx hyperframes check && npx hyperframes render -o out/<slug>.mp4

check-Warnungen zu Unterkompositionen, Spurdichte und einem stummen Film sind zu erwarten. Öffne das MP4 für sie. Falls sich die UI später ändert, führe den Journey erneut aus, friere die Bilder ein, deren Bildschirme sich geändert haben, behalte das Storyboard bei und rendere: Das ist das gesamte Update.

Häufige Fehler

Symptom	Ursache und Behebung
Cursor landet unter oder neben seinem Ziel	Bilder bei unterschiedlichen Fenstergrößen aufgenommen oder die Seite war beim Scrollen. Neuaufnahme bei einer Größe.
nichts mit der Bezeichnung „…“ von der Erstellung	Der click-Text stimmt nicht exakt mit dem Bildschirm überein (Groß-/Kleinschreibung, Leerzeichen, ein →). Kopiere ihn von der Seite.
Probe-Viewport war …	Das Fenster-Chrome von Headless-Chrome hat sich geändert; passe CHROME_UI in demo.mjs an.
Ein Bild zeigt ein leeres Feld	Vor dem Tippen eingefroren. Ausfüllen, dann einfrieren.
Bilder oder Schriftarten fehlen in einem Bild	Wurden ohne CORS von einer anderen Domain bereitgestellt, daher hat freeze.js die URL behalten; sie laden nur, solange dieser Host erreichbar ist. Notiere es als offene Frage.
Stripe oder andere iframes sind leer	freeze.js verwirft iframes. Friere den Bildschirm davor oder danach ein oder sage, was fehlt.
Chrome nicht gefunden	Setze CHROME=/pfad/zu/chrome.

Datenschutz

Ein Schnappschuss enthält alles, was auf dem Bildschirm war, mit eingebetteten Bildern. Bevor jemand das Board, den Ordner oder das Video teilt, überprüfe die Bilder auf personenbezogene Daten und hebe das Gefundene als offene Fragen hervor.