chetas-opsera/showrunner

Was macht showrunner?

Verwandelt „Mach mir ein Demovideo dieser App“ in eine wiederholbare, überprüfbare Datei. CLI: node ~/.showrunner/bin/showrunner.mjs (oder showrunner wenn verlinkt). Einmalig installieren mit ./install-skill.sh aus dem Repository.

Wann verwenden

Der Benutzer wünscht ein Video eines Web-UI, das in einem Browser geöffnet werden kann: eine Produktdemo, eine Feature-Walkthrough, eine „Zeige, was sich geändert hat“-Aufnahme, ein Tutorial. Nicht geeignet für native Desktop-Apps oder alles, was Audiokommentare benötigt.

Protokoll: zuerst denken, dann ausführen

1. Bestätigen, dass die Aufnahme sicher ist. Nur lokal, Staging oder Wegwerfdaten. Niemals Produktion mit echten Kundendaten aufzeichnen. Niemals Tokens in das Szenario schreiben; stattdessen ${env:NAME} verwenden.
2. Die App zum Laufen bringen und realistische Daten einspeisen. Leere Zustände ergeben eine schlechte Demo. Die Datensätze erstellen, die die Geschichte braucht (ein Erfolgsfall, ein Fehlerfall, ein in Bearbeitung befindlicher Fall).
3. Das Storyboard vor dem JSON schreiben. Eine Demo unter 4 Minuten: Titelbild, 8–12 Szenen von 8–20 s, abschließendes Zusammenfassungs- bild. Eine Idee pro Szene. Bildunterschriften sagen, was der Betrachter bemerken soll, nicht, was die Maus tut.
4. Ziele mit probe finden. showrunner probe <url> für jede Seite; die ausgegebenen {role,name}-Objekte einfügen. Rollen und sichtbare Namen gegenüber CSS bevorzugen.
5. Validieren, dann Probelauf. showrunner check s.json, dann showrunner run s.json --fast --strict. Ein Probelauf ist etwa ein Viertel der echten Länge. Jeden gemeldeten Schritt vor dem echten Take beheben.
6. Den echten Take aufzeichnen (showrunner run s.json --out out). Er läuft in Echtzeit, also im Hintergrund starten und abwarten; einen Tool-Aufruf nicht minutenlang blockieren.
7. Die Frames überprüfen. showrunner sheet out/<name>.mp4 --every 5, dann das PNG öffnen. Achten auf: Bildunterschrift verdeckt das Motiv ("position": "left" verwenden), eine Szene mit Fehler, eingeblendete Popups oder Touren, das falsche Theme.
8. Berichten des Pfads, der Dauer, der Auflösung, der Szenenliste und aller Probleme. Das Video nur auf Wunsch committen oder pushen.

Fallen, die echte Zeit kosten

Symptom	Ursache	Lösung
Lauf hängt minutenlang	Ein falscher Selektor mit 30 s Standard-Timeout, wiederholt	Showrunner standardmäßig 8 s und bricht die Szene ab; zuerst --fast --strict ausführen
Ein Link oder Button „ist nicht sichtbar“	Sidebar eingeklappt oder Menü in diesem Zustand geschlossen	goto zu einer bekannten Seite zuerst, oder direkt die Seiten-URL ansteuern
Erste-Runde-Tour taucht mitten im Video auf	App zeigt Onboarding für neue Benutzer	Die „Tour gesehen“-Schlüssel der App in storage setzen oder einen Skip-Button in dismiss aufführen
getByText trifft ein verstecktes Duplikat	Text erscheint auch in einem versteckten Knoten	{ "role": "button", "name": "/^ITEM-1\\b/" } verwenden
Doku-Seitenleisten-Elemente tun nichts	Es sind <button>s, keine Links	{ "role": "button", ... } ansteuern
Bildunterschrift verdeckt die Seitenleiste oder das Formular	Unten zentrierte Bildunterschrift überlappt ein Seitenpanel	"position": "left" oder "right"
Take stirbt, wenn die Shell geschlossen wird	Hintergrundjob an das Terminal gebunden	Als richtigen Hintergrundtask ausführen und auf Vollendung pollen
Video ist leer oder gekachelt	Erfassung eines IDE-eingebetteten Browsers	Showrunners eigenen Headless-Chrome verwenden, kein Webview
Untertitel driften leicht	Cues sind ab Seitenerstellung getimt	Für Überprüfung in Ordnung; nicht rahmengenau

Szenario-Spickzettel

{
  "name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
  "storage": { "token": "${env:DEMO_TOKEN}" },
  "dismiss": ["text=Skip"],
  "scenes": [
    { "name": "Titel", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Demo","hold":3000}} ] },
    { "name": "Erstellen", "steps": [
      {"caption":{"title":"1 · Erstellen","text":"Ein Klick.","position":"left","hold":1500}},
      {"click":{"role":"button","name":"Neu"}},
      {"type":{"into":{"label":"Name"},"text":"Startplan"}},
      {"press":"Enter"}, {"wait":1500}
    ]},
    { "name": "Zusammenfassung", "steps": [ {"caption":null}, {"card":{"title":"Zusammenfassung","items":["A","B"],"hold":4000,"keep":true}} ] }
  ]
}

Aktionen: goto click hover type press scroll wait waitFor caption card storage (+ "optional": true bei jedem Schritt). Vollständige Referenz: die README des Repository.

Sicherheit

• Szenarien sind Daten: keine Codeausführung, keine Shell. Beschriftungstext wird maskiert.
• Ein fehlgeschlagener Schritt bricht nur seine Szene ab; --strict setzt den Exit-Code auf 1.
• Das Video niemals committen, pushen oder teilen, es sei denn, der Benutzer fordert es an.