HyperFrames Core

Was macht HyperFrames Core?

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

Dieser Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist die Bauanleitung; detaillierte Informationen zu den einzelnen Themen findest du in references/ (als nächstes indexieren), die bei Bedarf gelesen werden. Andere Belange leben in den verwandten Domain-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes sagt, was jeder abdeckt.

Referenzen

Datei	Lies dies, um …
references/minimal-composition.md	mit dem kleinsten renderbaren Kompositionsskelett zu beginnen
references/composition-patterns.md	monolithisch vs. modular zu wählen; ein modulares index.html zu strukturieren; einen Sub-Kompositions-Archetyp auszuwählen
references/data-attributes.md	jedes data-* (Root / Clip / Sub-Comp-Host / Legacy-Alias) nachzuschlagen; class="clip" zu verwenden
references/tracks-and-clips.md	data-track-index auszuwählen, Überlappungen / z-Index auf demselben Track zu behandeln, einen Clip relativ zu einem anderen zu timen
references/sub-compositions.md	eine Sub-Komposition zu verdrahten (Host-Attribute, <template>, Instanzvariablen) 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 erstellen; Determinismus-Verbote; die Animierbare-Eigenschaften-Whitelist; Layout / Text-Fit
references/full-screen-motion.md	Vollbild-Bewegung mit gemeinsam genutzten 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 durchzuführen – gemeinsam genutzt von allen Storyboard-Planungs-Workflows
references/production-loop.md	einen genehmigten Plan in ein ausgeliefertes Video umzusetzen – die Stufenabhängigkeiten (Audio, Frames, Assembly, Übergänge, Untertitel, Verifizieren, Ausliefern) folgt direkt einem Freiform-Build
references/brief-contract.md	die Grundregeln des Briefings – Modus-Ableitung (kollaborativ / autonom), gemeinsames Feldregister, Fragen-Invarianten (die Frage selbst lebt in /hyperframes → der Absichts-Ebene)
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 Narration zu verfassen
references/subagent-dispatch.md	Sub-Agent-Dispatch-Verben (paralleles Fan-Out / Hintergrund / Warten) auf dein Harness abzubilden
references/frame-worker-core.md	den gemeinsamen Frame-Worker-Rollenvertrag – jeder narrative Workflow-Paket-Builder stellt ihn seinem sub-agents/frame-worker.md-Delta voran
references/tailwind.md	in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; Laufzeitvertrag unterscheidet sich von Studio's v3)

Details zu Animationslaufzeiten (GSAP API, Lottie, Three.js usw.) findest du in hyperframes-animation → adapters/<runtime>.md.

Eine Komposition erstellen

Zwei Wurzelformen (nicht austauschbar)

• Eigenständig (top-level index.html) – Root <div data-composition-id="…"> liegt direkt im <body>, kein <template>-Wrapper (ein Wrapper würde den gesamten Inhalt verstecken und das Rendering zerstören).
• Sub-Komposition (geladen über data-composition-src) – Root muss in <template> gewickelt sein.

⚠ Transportregel: Die Laufzeit klont nur <template>-Inhalte; alles außerhalb (inkl. <head>-Styles/Skripte) wird verworfen – setze <style>/<script> innerhalb des Templates. ⚠ Host-ID-Regel: Die data-composition-id des Host-Slots muss exakt der data-composition-id des inneren Templates und dem window.__timelines["<id>"]-Schlüssel 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 eigenständige 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 – sonst fällt ein flex/100%-Kind auf ~0 zusammen und der Inhalt stapelt sich in der oberen linken Ecke. Verlasse dich nicht allein auf automatisierte Gates, um dies zu erkennen; überprüfe einen Schnappschuss. Skelett → references/minimal-composition.md.

Eine pausierte Zeitleiste

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

First-Pass-Lint-Stolperfallen (ein garantierter erster Build-Fehler)

Zwei Regeln, die lint wohl erkennt, aber erst im Nachhinein – schreibe sie gleich beim ersten Mal richtig:

• Das Root-Kompositionselement muss data-start="0" tragen (neben data-composition-id/data-width/data-height); das Weglassen führt zu einem lint-Fehler mit root_composition_missing_data_start.
• Kombiniere niemals ein CSS transform initial mit einem GSAP-Tween auf derselben Eigenschaft – der CSS-Wert und der Tween-Start kämpfen und lint lehnt es mit gsap_css_transform_conflict ab. Setze den Anfangszustand innerhalb des Tweens mit gsap.fromTo(el, { x: -40 }, { x: 0 }) anstelle eines CSS transform: translateX(-40px).

Unverhandelbare Regeln (stille Fehler, die automatisierte Gates übersehen können)

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

• Keine Render-Zeit-Uhren / ungesäter Math.random / Netzwerk / Eingabezustand; kein repeat: -1 (verwende eine endliche Anzahl). → determinism-rules.md
• Nur die visuelle Eigenschaften-Whitelist animieren; niemals display oder reines visibility twenen. GSAP autoAlpha und Null-Dauer-Zeitleisten-Grenzwerte sind die einzigen Sichtbarkeitsausnahmen, und nur auf Nicht-Clip-Elementen oder Wrappern innerhalb eines Clips. Das Framework allein steuert die .clip-Sichtbarkeit. Verwende kein gsap.set für spätere Szenen-Clips beim Laden der Seite. → determinism-rules.md
• Kein <br> im Fließtext; transformierte Elemente müssen Block-Level + dimensioniert sein; pulsierende absolute dekorative Elemente benötigen Spitzenabstand. → determinism-rules.md
• <video>/<audio> funktionieren in jeder Verschachtelungstiefe (auch innerhalb eines Sub-Kompositions-<template> oder Wrappers); das Framework besitzt die Wiedergabe und sucht/decodiert Medien, wo immer sie sich befinden. Die eine Einschränkung betrifft Zeitleisten, nicht die Platzierung: Eine Sub-Kompositions-Zeitleiste kann keine Host-Root-Elemente animieren. → variables-and-media.md
• Jede id muss über die montierte Seite hinweg eindeutig sein; innerhalb einer Sub-Komposition prefixe ids mit der Kompositions-ID (#<id>-hero). Doppelte <video>/<img>-ids rendern leer – der Produzent injiziert Frames per getElementById, und dateiübergreifende Duplikate schlüpfen an lint vorbei. → composition-patterns.md
• Ein Vollbild-Szenen-Füller wird auf ein vollflächiges Kind (position:absolute; inset:0) gesetzt, niemals auf den Kompositions-Root selbst – die Frame-Komposition des Produzenten kann das background des Root-Elements selbst fallen lassen (der Frame rendert schwarz), auch wenn die Vorschau/snapshot es korrekt anzeigen. → composition-patterns.md

Vorhandene Kompositionen bearbeiten

• Lies zuerst die Dateien. Erhalte nicht zusammenhängendes Timing, Tracks, IDs, Variablen, Medienpfade.
• Stimme vorhandene Kompositions-IDs und Zeitleisten-Schlüssel ab.
• Hinzufügen eines Clips: Wähle einen nicht überlappenden data-track-index oder passe das umgebende Timing absichtlich 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 durch das Zeitleisten-Auge-Symbol von Studio umgeschaltet.
• Hinzufügen einer Sub-Komposition: Überprüfe ihre interne data-composition-id, bevor du den Host verdrahtest.

Validierung

Verwende hyperframes-cli für Befehlsdetails

• npx hyperframes check ist erfolgreich (0 Befunde bei Lint, Laufzeit, Layout, Bewegung und Kontrast)
• Projekte mit Sub-Kompositionen: npx hyperframes snapshot --at <midpoints> und jeden Frame überprüfen
• npx hyperframes preview zur Überprüfung (der Benutzer kann alles in Studios Zeitleiste bearbeiten)
• npx hyperframes render erst nach Genehmigung durch den Benutzer