HyperFrames Core
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM mit data-*-Attributen Timing deklariert, deren Animationslaufzeit suchbar (seekable) 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 die Bauanleitung; Details zu einzelnen Themen leben in references/ (Index siehe unten), bei Bedarf lesen. Andere Belange befinden sich in den Schwesterfähigkeiten – hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes sagt, was jede abdeckt.
Referenzen
| Datei | Lese sie, 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 Unterkompositions-Archetyp zu wählen |
references/data-attributes.md | jedes data-* (root / clip / sub-comp 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 handhaben, 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 | Vollbild-Bewegung mit geteilten Hintergründen zu erstellen |
references/storyboard-format.md | einen STORYBOARD.md-Plan (+ das geparste Manifest) zu verfassen |
references/script-format.md | die optionale gesperrte Erzählung SCRIPT.md zu verfassen |
references/subagent-dispatch.md | Subagent-Dispatch-Verben (paralleles Fan-Out / Hintergrund / Warten) auf dein Harness abzubilden |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; 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 Wurzelformen (nicht austauschbar)
- Eigenständig (Top-Level
index.html) — Wurzel<div data-composition-id="…">sitzt direkt in<body>, kein<template>-Wrapper (ein Wrapper versteckt den gesamten Inhalt und bricht das Rendering). - Unterkomposition (geladen über
data-composition-src) — Wurzel muss in<template>eingewickelt sein.
⚠ Transportregel: Die Laufzeit klont nur den Inhalt von
<template>; alles außerhalb (einschließlich<head>-Styles/Scripts) wird verworfen – platziere<style>/<script>innerhalb des Templates. ⚠ Host-ID-Regel: Diedata-composition-iddes Host-Slots muss exakt mit derdata-composition-iddes inneren Templates und demwindow.__timelines["<id>"]-Schlüssel übereinstimmen – kein Suffix-mount/-slot/-host.
Dateistruktur, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.
Wurzel muss dimensioniert sein (stiller Layout-Fehler)
Die eigenständige Wurzel benötigt eine explizit dimensionierte Box (width/height in px), und jeder Vorfahre bis zu einem Element mit height:100% muss eine aufgelöste Höhe haben – andernfalls bricht ein Flex-/100%-Kind auf ~0 zusammen und Inhalt stapelt sich in der oberen linken Ecke. lint/validate/inspect fangen dies nicht ab. Skelett → references/minimal-composition.md.
Eine pausierte Zeitleiste
Jede Komposition registriert genau eine gsap.timeline({ paused: true }) unter window.__timelines["<id>"] (Schlüssel = Wurzel data-composition-id), die synchron beim Seitenladen aufgebaut wird. Renderdauer = Wurzel data-duration, nicht Zeitleistenlänge. Verschachtle keine Unterzeitleisten manuell im Host. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Unverhandelbare Regeln (stille Bugs, die lint/validate/inspect nicht fangen)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Renderzeit-Uhren / ungeseedetes
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(endliche Anzahl verwenden). →determinism-rules.md - Nur die Whitelist visueller Eigenschaften animieren; niemals
display/visibility; keingsap.setauf Clips späterer Szenen. →determinism-rules.md - Kein
<br>im Fließtext; transformierte Elemente müssen block-level + dimensioniert sein; pulsierende absolute Dekorationen benötigen Spitzenabstand. →determinism-rules.md <video>/<audio>muss ein direktes Kind der Host-Wurzel sein (nie innerhalb eines Unterkompositions-<template>/Wrappers); das Framework steuert die Wiedergabe. →variables-and-media.md- Jede
idmuss auf der montierten Seite eindeutig sein; innerhalb einer Unterkomposition IDs mit der Kompositions-ID präfixieren (#<id>-hero). Doppelte<video>/<img>-IDs rendern leer – der Producer injiziert Frames pergetElementById, und dateiübergreifende Duplikate schlüpfen anlintvorbei. →composition-patterns.md - Eine Vollbild-Szenenfüllung kommt auf ein randloses Kind (
position:absolute; inset:0), niemals auf die Kompositionswurzel selbst – der Producer-Frame-Compositing kann diebackgrounddes Wurzelelements fallen lassen (der Frame rendert schwarz), auch wenn Vorschau/snapshotes korrekt zeigen. →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lies zuerst die Dateien. Bewahre nicht zusammenhängendes Timing, Spuren, IDs, Variablen und Medienpfade.
- Stimme vorhandene Kompositions-IDs und Zeitleistenschlüssel ab.
- Ein Clip hinzufügen: Wähle einen nicht überlappenden
data-track-indexoder passe umgebendes Timing absichtlich an. - Eine Unterkomposition hinzufügen: Überprüfe ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes lintbesteht (0 Fehler) -
npx hyperframes validatebesteht (0 Konsolenfehler) -
npx hyperframes inspectbesteht (0 Fehler) - Projekte mit Unterkompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild prüfen -
npx hyperframes previewzur Überprüfung (der Benutzer kann alles in Studios Timeline bearbeiten) -
npx hyperframes rendernur nach Freigabe durch den Benutzer