Sma1lboy/rove

HyperFrames CLI

Alles läuft über npx hyperframes, sofern die Projektanweisungen keinen lokalen Wrapper vorgeben. Halte dich genau an den lokalen Wrapper. Erfordert Node.js >= 22 und FFmpeg.

Arbeitsablauf

1. Gerüst erstellen — npx hyperframes init my-video (oder capture von einer URL)
2. Schreiben — HTML-Composition verfassen (siehe ../core)
3. Linten — npx hyperframes lint
4. Validieren — npx hyperframes validate (Laufzeitfehler + Kontrast)
5. Visuell inspizieren — npx hyperframes inspect
6. Vorschau — npx hyperframes preview öffnet Studio, den Timeline-Editor, in dem der Benutzer alles manuell bearbeiten kann (nicht nur ansehen). Dort überprüfen, dann vor dem Rendern fragen.
7. Rendern — Variante wählen:
   • Iterieren: npx hyperframes render --quality draft
   • Ausliefern: npx hyperframes render --quality high --output out.mp4
   • CI / hostübergreifende Reproduktion: npx hyperframes render --docker --strict --output out.mp4
   • Cloud (lang / groß): npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait (siehe Lambda unten)

Führe lint, validate und inspect vor der Vorschau aus. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Timelines. validate lädt die Composition in einem headless Chrome und meldet Laufzeit-Konsolenfehler sowie WCAG-Kontrastprobleme. inspect durchläuft die Timeline und meldet Text, der aus Blasen/Containern herausragt oder die Zeichenfläche verlässt – und, wenn eine *.motion.json-Beilage vorhanden ist, überprüft es die Bewegungsabsicht (Entrances, die beim Suchen feuern, Staffelungsreihenfolge, im Rahmen, Lebendigkeit) gegen dieselbe gesuchte Timeline.

Bevorzuge bei bewegungsintensiven Arbeiten eine Snapshot-gesteuerte Iteration und eine *.motion.json-Beilage – siehe references/lint-validate-inspect.md für die Disziplin und die Spezifikation zur Bewegungsüberprüfung.

Agentenkonventionen

Übergreifende Regeln, die für jeden Befehl gelten:

• --json ist für jeden Befehl außer render, preview und play verfügbar. Verwende es für jede Agenten-/CI-Aufrufung der unterstützten Befehle; die Ausgabe enthält einen _meta-Umschlag (CLI-Version, neueste verfügbare Version, Aktualisierungshinweis). render meldet den Status nur über stdout + Exit-Code – überprüfe den Erfolg mit der Post-Render-Prüfung unten; preview / play sind Server, kein JSON.
• doctor --json verlässt immer mit 0, selbst wenn die Umgebung defekt ist. Prüfe auf das ok-Feld der Nutzdaten: npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Versionswechseln.
• Nicht-TTY-Modus wird automatisch erkannt. Wenn stdout kein TTY ist (CI, Agenten, gepipte Ausgabe) schaltet die CLI automatisch auf nicht-interaktiv um; init erfordert dann --example. Übergib --non-interactive, um diesen Modus auch auf einem TTY zu erzwingen.
• CI-Absicherung beim Rendern: --strict schlägt bei Linting-Fehlern fehl, --strict-all auch bei Warnungen, --strict-variables schlägt bei nicht deklarierten --variables-Schlüsseln fehl.
• Pfade in --json werden geschwärzt – $HOME wird zum literalen $HOME, damit die Ausgabe sicher in Fehlerberichte und Agentenkontexte eingefügt werden kann.
• Das Rendern ist benutzergesteuert. Rendere niemals automatisch, sobald die Prüfungen bestanden sind. Halte bei der Vorschau an, teile dem Benutzer mit, dass das Video in Studio bearbeitet werden kann, und rendere erst, nachdem er zugestimmt hat.
• Post-Render-Überprüfung. Nachdem render mit Exit-Code 0 zurückgekehrt ist, bestätige, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor du den Erfolg meldest: [ -s "$OUTPUT" ] || echo "render hat keine Ausgabe produziert". Die CLI gibt bei Erfolg ◇ <pfad> aus; bei langen Renderings überprüfe die Dauer zusätzlich mit ffprobe -i "$OUTPUT" -show_format -v error.

Weiterleitung

Gewünschte Aktion	Lese
Ein Projekt erstellen (init, capture, skills)	references/init-and-scaffold.md
Korrektheit prüfen (lint, validate, inspect, snapshot)	references/lint-validate-inspect.md
Vorschau oder Rendern (preview, play, render, publish)	references/preview-render.md
Umgebung diagnostizieren (doctor, browser)	references/doctor-browser.md
Cloud-Rendering auf AWS Lambda (lambda deploy / sites / render / progress / destroy / policies)	references/lambda.md
Alles andere (info, upgrade, compositions, docs, benchmark, telemetry, Asset-Vorverarbeitung)	references/upgrade-info-misc.md

Abschnittsübergaben

• Tailwind-Projekte (init --tailwind) → siehe ../core/references/tailwind.md vor dem Bearbeiten von Klassen oder Theme-Token.
• Registry-Blöcke/Komponenten (hyperframes add, hyperframes catalog) → siehe ../registry für Installationspfade, Sub-Composition-Verkabelung und Snippet-Zusammenführung.
• Parametrisierte Renderings (--variables) → deklariert via data-composition-variables auf <html>; siehe ../core/references/variables-and-media.md für das vollständige Schema.

Lambda (Cloud-Rendering)

hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von deinem Laptop oder CI aus. Der gesamte Ablauf umfasst drei Befehle:

npx hyperframes lambda deploy                                             # SAM-Stack bereitstellen (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # abbauen (S3-Bucket bleibt erhalten)

Verwende Lambda, wenn ein Rendering zu lang / zu groß für einen einzelnen Host ist (mehrminütige Videos, 4K, große parallele Batches) und du AWS-Anmeldeinformationen konfiguriert hast. Für Entwicklungsiterationen bleibe beim lokalen render.

Siehe references/lambda.md für Voraussetzungen, alle 6 Unterbefehle (deploy, sites create, render, progress, destroy, policies), IAM-Richtlinienvalidierung, Zustandsdateien und Kosten-/Aufräumregeln.

Mindestabnahmeschwelle

Statische Prüfungen

npx hyperframes lint
npx hyperframes validate

Füge inspect für layoutkritische Arbeiten und render --strict in CI hinzu, um bei Linting-Fehlern zu scheitern.

Visueller Rauchtest – erforderlich, wenn das Projekt Sub-Compositions verwendet

lint / validate / inspect bewerten jede Composition isoliert. Sie laden niemals index.html und mounten Sub-Compositions über data-composition-src, daher können sie keine dateiübergreifenden Mount-Fehler erkennen (siehe ../core/references/sub-compositions.md, „Häufige Fallstricke"). Die einzige Prüfung, die sie erkennt, ist eine, die tatsächlich index.html lädt und die Timeline durchsucht.

Verwende hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (übt also denselben Mount-Pfad aus), erfasst aber nur die von dir angeforderten Zeitstempel, was Sekunden statt eines vollständigen Renderings dauert:

# Ein Bild in der Mitte jeder Sub-Composition erfassen.
# Mittelpunkte = data-start + data-duration/2 für jeden Host-Slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Oder, wenn keine zielszenengenaue Ausrichtung erforderlich ist, eine gleichmäßig verteilte Stichprobe:
npx hyperframes snapshot --frames 9

Die Ausgabe landet in snapshots/frame-NN-at-Xs.png. Überprüfe jedes Bild gegen die Szenenplanung.

Pro Bild auftretende Alarmzeichen (jedes ist einem bestimmten Fehlermodus zugeordnet, den die statischen Prüfungen übersehen):

Was du siehst	Ursache
Text erscheint winzig + ohne Stil in der oberen linken Ecke	<style>-Block blieb im <head> außerhalb von <template> (Fallstrick 1) – kein CSS erreichte das Live-DOM
SVG/Icon-Elemente auf zeichenflächengroße Größe aufgeblasen	Gleiche Ursache – keine width/height-Einschränkungen angewendet
Helden-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar	Host-id ≠ template id (Fallstrick 2) – Timeline wurde nie ausgeführt, Bild zum initialen Zustand erfasst
Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms	Fallstrick 2 – direkte Bestätigung

snapshots/ kann nach der Sichtprüfung gelöscht werden; das benutzerseitige endgültige Rendering ist ein separater Durchlauf mit npx hyperframes render.