topcheer/ggcode

HyperFrames Core

HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM das Timing mit data-*-Attributen deklariert, deren Animationslaufzeit suchbar ist und deren Medienwiedergabe vom Framework gesteuert wird.

Diese Fähigkeit ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Bauleitfaden; detaillierte Informationen zu einzelnen Themen befinden sich in references/ (als Nächstes indizieren), auf Abruf lesen. Andere Belange werden in den benachbarten Bereichsfähigkeiten behandelt – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jede abdeckt.

Referenzen

Datei	Lesen, um…
references/minimal-composition.md	mit dem kleinstmöglichen renderbaren Kompositionsskelett zu beginnen
references/composition-patterns.md	zwischen monolithisch und modular zu wählen; eine modulare index.html zu strukturieren; einen Unterkompositions-Archetyp auszuwählen
references/data-attributes.md	jedes data-* (Root / Clip / Unterkompositions-Host / Legacy-Aliase) nachzuschlagen; class="clip" zu verwenden
references/tracks-and-clips.md	data-track-index auszuwählen, Überlappungen / z-Index auf derselben Spur zu behandeln, einen Clip relativ zu einem anderen zu timen
references/sub-compositions.md	eine Unterkomposition zu verdrahten (Host-Attribute, <template>, pro-Instanz-Variablen) und darin zu animieren
references/variables-and-media.md	Variablen zu deklarieren; <video>/<audio> zu platzieren, Lautstärke einzustellen, zu trimmen
references/determinism-rules.md	eine suchbare Zeitleiste zu bauen; Determinismus-Verbote; die Whitelist animierbarer Eigenschaften; Layout / Textanpassung
references/full-screen-motion.md	Vollbildbewegung mit gemeinsamen Hintergründen zu erstellen
references/storyboard-format.md	einen STORYBOARD.md-Plan zu verfassen (+ das geparste Manifest)
references/review-loop.md	die Plan → Skizze → Bau-Review-Durchläufe auf einem Live-Board auszuführen – von jedem Storyboard-Planungs-Workflow gemeinsam genutzt
references/production-loop.md	einen genehmigten Plan zu einem ausgelieferten Video zu bringen – die Stufenabhängigkeiten (Audio, Frames, Montage, Übergänge, Untertitel, Verifizieren, Ausliefern) eines Freiform-Baus folgen direkt
references/brief-contract.md	die Grundregeln des Briefings – Modus-Ableitung (kollaborativ / autonom), gemeinsames Feldregister, Frage-Invarianten (das Fragen selbst liegt in /hyperframes → der Absichtsebene)
references/brief-format.md	BRIEF.md zu verfassen – das bestätigte Absichtsdokument, das der Setup eines Workflows schreibt und jeder spätere Schritt liest
references/script-format.md	das optionale SCRIPT.md mit festgelegter Erzählung zu verfassen
references/subagent-dispatch.md	die Verben der Unteragenten-Dispatch (parallel Fan-Out / Hintergrund / Warten) auf Ihre Umgebung abzubilden
references/frame-worker-core.md	den gemeinsamen Frame-Worker-Rollenvertrag – jeder narrative Workflow-Paket-Ersteller stellt ihn dem Delta des jeweiligen Workflows sub-agents/frame-worker.md voran
references/tailwind.md	in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; der Laufzeitvertrag unterscheidet sich von Studios v3)

Für spezifische Animationslaufzeiten (GSAP API, Lottie, Three.js, etc.) siehe hyperframes-animation → adapters/<runtime>.md.

Eine Komposition bauen

Zwei Wurzelformen (nicht austauschbar)

• Standalone (oberste index.html) – root <div data-composition-id="…"> liegt direkt in <body>, kein <template>-Wrapper (ein Wrapper versteckt den gesamten Inhalt und unterbricht das Rendering).
• Sub-Komposition (geladen über data-composition-src) – root muss in <template> eingewickelt sein.

⚠ Transportregel: Die Laufzeit klont nur den Inhalt von <template>; alles außerhalb (inkl. <head>-Styles/Skripte) wird verworfen – setzen Sie <style>/<script> innerhalb des Templates. ⚠ Host-ID-Regel: data-composition-id des Host-Slots muss exakt der data-composition-id des inneren Templates und dem Schlüssel window.__timelines["<id>"] entsprechen – kein -mount/-slot/-host Suffix.

Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.

Root muss dimensioniert sein (stiller Layout-Fehler)

Der Standalone-Root benötigt eine explizite dimensionierte Box (width/height in px), und jeder Vorfahre bis zu einem Element mit height:100% muss eine aufgelöste Höhe haben – andernfalls kollabiert ein Flex-/100%-Kind auf ~0 und Inhalt stapelt sich in der oberen linken Ecke. Verlassen Sie sich nicht allein auf automatisierte Tore, um dies zu erkennen; überprüfen Sie einen Screenshot. Skelett → references/minimal-composition.md.

Eine pausierte Zeitleiste

Jede Komposition registriert genau eine gsap.timeline({ paused: true }) unter window.__timelines["<id>"] (Schlüssel = root data-composition-id), die synchron beim Seitenladen erstellt wird. Render-Dauer = root data-duration, nicht Zeitleistenlänge. Verschachteln Sie keine Unter-Zeitleisten manuell im Host. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.

Nicht verhandelbare Regeln (stille Fehler, die automatisierte Tore übersehen können)

Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:

• Keine Render-Zeit-Uhren / ungesätetes Math.random / Netzwerk / Eingabezustand; kein repeat: -1 (endliche Anzahl verwenden). → determinism-rules.md
• Nur die visuelle Eigenschafts-Whitelist animieren; niemals display oder rohes visibility tweenen. GSAP autoAlpha und Null-Dauer-Zeitleisten-Grenzsetzungen sind die einzigen Sichtbarkeitsausnahmen, und nur auf Nicht-Clip-Elementen oder Wrappern innerhalb eines Clips. Das Framework allein steuert die .clip-Sichtbarkeit. Führen Sie kein gsap.set für spätere Szenen-Clips beim Seitenladen durch. → determinism-rules.md
• Kein <br> im Textkörper; transformierte Elemente müssen block-level + dimensioniert sein; pulsierende absolute Dekoelemente benötigen Spitzenabstand. → determinism-rules.md
• <video>/<audio> funktionieren auf jeder Verschachtelungstiefe (auch innerhalb eines Sub-Comp <template> oder Wrappers); das Framework besitzt die Wiedergabe und sucht/decodiert Medien, wo immer sie sind. Die einzige Einschränkung sind Zeitleisten, nicht die Platzierung: Eine Sub-Comp-Zeitleiste kann keine Host-Root-Elemente animieren. → variables-and-media.md
• Jede id muss über die assemblierte Seite hinweg eindeutig sein; innerhalb einer Sub-Komposition IDs mit der Kompositions-ID präfixieren (#<id>-hero). Doppelte <video>/<img>-IDs rendern leer – der Producer injiziert Frames mit getElementById, und dateiübergreifende Duplikate entgehen lint. → composition-patterns.md
• Eine Vollbild-Szenenfüllung erfolgt auf einem randlosen Kind (position:absolute; inset:0), niemals auf dem Kompositions-Root selbst – der Producer-Frame-Compositing kann den background des Root-Elements selbst verwerfen (der Frame rendert schwarz), auch wenn die Vorschau/snapshot es korrekt anzeigen. → composition-patterns.md

Vorhandene Kompositionen bearbeiten

• Lesen Sie zuerst die Dateien. Bewahren Sie nicht verwandtes Timing, Tracks, IDs, Variablen, Medienpfade.
• Passen Sie vorhandene Kompositions-IDs und Zeitleistenschlüssel an.
• Einen Clip hinzufügen: Wählen Sie einen nicht überlappenden data-track-index oder passen Sie das umgebende Timing gezielt an.
• data-hidden auf einem beliebigen Kompositionselement blendet es sowohl in der VORSCHAU als auch im RENDER aus und überschreibt sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird über das Timeline-Augen-Symbol von Studio umgeschaltet.
• Eine Sub-Komposition hinzufügen: Überprüfen Sie ihre interne data-composition-id, bevor Sie den Host verdrahten.

Validierung

Verwenden Sie hyperframes-cli für Befehlsdetails

• npx hyperframes check bestanden (0 Funde über Lint, Laufzeit, Layout, Bewegung und Kontrast hinweg)
• Projekte mit Sub-Kompositionen: npx hyperframes snapshot --at <midpoints> und jedes Bild begutachten
• npx hyperframes preview zur Überprüfung (der Benutzer kann alles in Studios Timeline bearbeiten)
• npx hyperframes render erst nach Benutzerfreigabe