hyperframes-core

HyperFrames Core

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

Diese Kompetenz ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist die Bauanleitung; Details zu einzelnen Themen befinden sich in references/ (Index als nächstes), auf Abruf lesen. Andere Belange befinden sich in den verwandten Bereichskompetenzen – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jede abdeckt.

Referenzen

Datei	Lies sie, um…
references/minimal-composition.md	mit dem kleinstmöglichen renderbaren Kompositionsskelett zu beginnen
references/composition-patterns.md	monolithisch vs. modular zu wählen; eine modulare index.html zu strukturieren; einen Sub-Komp-Archetyp auszuwählen
references/data-attributes.md	jedes data-* (Root / Clip / Sub-Komp-Host / Legacy-Aliase) nachzuschlagen; class="clip" zu verwenden
references/tracks-and-clips.md	data-track-index auszuwählen, Überlappungen / z-index auf demselben Track zu handhaben, einen Clip relativ zu einem anderen zu timen
references/creator-editing-recipes.md	wahrheitsgetreue Rezepte zum Trimmen/Neuordnen/Neutimen/Einfrieren/Kamera/Maske/Überblendung/Audio-Bearbeitung und deren Grenzen zu kopieren
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 Timeline zu bauen; Determinismus-Verbote; die Zulassungsliste animierbarer Eigenschaften; Layout / Textanpassung
references/full-screen-motion.md	Vollbild-Bewegung mit gemeinsamen Hintergründen zu erstellen
references/storyboard-format.md	einen STORYBOARD.md-Plan zu erstellen (+ das geparste Manifest)
references/review-loop.md	die Plan → Skizze → Bau-Review-Durchläufe auf einem Live-Board auszuführen – geteilt von jedem Storyboard-Planungs-Workflow
references/production-loop.md	einen genehmigten Plan in ein ausgeliefertes Video umzusetzen – die Stufenabhängigkeiten (Audio, Frames, Assembly, Übergänge, Untertitel, Verifizieren, Ausliefern), denen ein freiformatiger Build direkt folgt
references/brief-contract.md	die Grundregeln des Briefings – Modus-Ableitung (kollaborativ / autonom), gemeinsames Feldregister, Frageninvarianten (die Frage selbst lebt in /hyperframes → der Absichtsebene)
references/brief-format.md	BRIEF.md zu erstellen – das bestätigte Absichtsdokument, das der Setup-Schritt eines Workflows schreibt und das jeder spätere Schritt liest
references/script-format.md	das optionale SCRIPT.md-Sperr-Narrativ zu erstellen
references/subagent-dispatch.md	Subagenten-Dispatch-Verben (paralleles Aufteilen / Hintergrund / Warten) auf Ihre Umgebung abzubilden
references/frame-worker-core.md	den gemeinsamen Frame-Worker-Rollenvertrag – jeder narrative Workflow-Paket-Bauer stellt ihn seiner Workflow-sub-agents/frame-worker.md-Delta voran
references/tailwind.md	in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; der Laufzeitvertrag unterscheidet sich von Studios v3)

Für Details zur Animationslaufzeit (GSAP-API, Lottie, Three.js usw.) siehe hyperframes-animation → adapters/<runtime>.md.

Eine Komposition bauen

Zwei Root-Formen (nicht austauschbar)

• Standalone (top-level index.html) – root <div data-composition-id="…"> sitzt direkt im <body>, kein <template>-Wrapper (das Einpacken verbirgt den gesamten Inhalt und bricht das Rendering).
• Sub-Komposition (geladen über data-composition-src) – root muss in <template> eingepackt sein.

⚠ Transportregel: die Laufzeit klont nur <template>-Inhalte; alles außerhalb (inkl. <head>-Styles/Skripte) wird verworfen – setzen Sie <style>/<script> innerhalb des Templates. ⚠ Host-ID-Regel: die data-composition-id des Host-Slots muss exakt gleich der data-composition-id des inneren Templates und dem Schlüssel window.__timelines["<id>"] sein – 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 explizit dimensionierte Box (width/height in px), und jedes Vorfahrenelement bis zu einem height:100%-Element muss eine aufgelöste Höhe haben – andernfalls fällt ein flex/100%-Kind auf ~0 zusammen und der Inhalt stapelt sich in der oberen linken Ecke. Verlassen Sie sich nicht allein auf automatisierte Gates, um dies zu erkennen; inspizieren Sie einen Snapshot. Skelett → references/minimal-composition.md.

Eine pausierte Timeline

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

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

Zwei Regeln, die lint tatsächlich fängt, aber erst im Nachhinein – schreiben Sie 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 dazu, dass lint mit root_composition_missing_data_start fehlschlägt.
• Kombinieren Sie niemals einen CSS-Start-transform mit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Tween-Start kämpfen und lint lehnt ihn mit gsap_css_transform_conflict ab. Setzen Sie den Startzustand stattdessen 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 (eine endliche Anzahl verwenden). → determinism-rules.md
• Nur die Zulassungsliste visueller Eigenschaften animieren; niemals display oder rohes visibility tweenen. GSAP autoAlpha und Null-Dauer-Timeline-Grenzsätze 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 Clips späterer Szenen beim Seitenladen aus. → determinism-rules.md
• Keine <br> im Fließtext; transformierte Elemente müssen block-level + dimensioniert sein; pulsierende absolute Dekorationen benötigen Spitzenabstand. → determinism-rules.md
• <video>/<audio> funktionieren auf jeder Verschachtelungstiefe (auch innerhalb eines Sub-Komp-<template> oder Wrappers); das Framework besitzt die Wiedergabe und sucht/decodiert Medien, wo immer sie sich befinden. Die eine Einschränkung betrifft Timelines, nicht die Platzierung: Eine Sub-Komp-Timeline kann keine Host-Root-Elemente animieren. → variables-and-media.md
• Jede id muss über die zusammengesetzte Seite hinweg eindeutig sein; innerhalb einer Sub-Komposition ids mit der Kompositions-ID versehen (#<id>-hero). Doppelte <video>/<img>-IDs rendern leer – der Producer injiziert Frames per 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 – die Frame-Kompositionierung des Producers kann den eigenen background des Root-Elements fallen lassen (das Frame rendert schwarz), auch wenn die Vorschau/der snapshot es korrekt anzeigt. → composition-patterns.md

Bestehende Kompositionen bearbeiten

• Lesen Sie zuerst die Dateien. Bewahren Sie nicht zusammenhängendes Timing, Tracks, IDs, Variablen, Medienpfade.
• Passen Sie vorhandene Kompositions-IDs und Timeline-Schlüssel an.
• Hinzufügen eines Clips: Wählen Sie einen nicht überlappenden data-track-index oder passen Sie das umgebende Timing absichtlich an.
• data-hidden auf einem beliebigen Kompositionselement verbirgt es sowohl in der VORSCHAU als auch im RENDER und überschreibt sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird über das Timeline-Augen-Symbol von Studio umgeschaltet.
• Hinzufügen einer Sub-Komposition: Ü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 Befunde bei Lint, Laufzeit, Layout, Bewegung und Kontrast)
• Projekte mit Sub-Kompositionen: npx hyperframes snapshot --at <midpoints> und jedes Einzelbild begutachten
• npx hyperframes preview --background zur Überprüfung (der Benutzer kann alles in der Timeline von Studio bearbeiten, und der Server überlebt den aufrufenden Befehl)
• npx hyperframes render erst nach Genehmigung durch den Benutzer