HyperFrames Core
HyperFrames rendert Videos aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM mit data-*-Attributen das Timing vorgibt, 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 der Bauleitfaden; detaillierte Informationen zu jedem Thema finden sich in references/ (Index als nächstes), bei Bedarf abrufbar. Andere Belange liegen in den zugehörigen Bereichsskills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitslandkarte in /hyperframes sagt, was jeder abdeckt.
Referenzen
| Datei | Lies sie, um… |
|---|---|
references/minimal-composition.md | mit dem kleinsten renderbaren Kompositionsskelett zu beginnen |
references/composition-patterns.md | monolithisch vs. modular zu wählen; eine modulare 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 zu wählen, Überlappungen / z-index auf demselben Track zu handhaben, einen Clip relativ zu einem anderen zu timen |
references/sub-compositions.md | eine Unterkomposition 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 Allowlist 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 verfassen (+ das geparste Manifest) |
references/review-loop.md | die Plan → Skizze → Bau-Review-Durchläufe auf einem Live-Board auszuführen – gemeinsam für jeden Storyboard-Planungs-Workflow |
references/production-loop.md | einen genehmigten Plan zu einem ausgelieferten Video zu bringen – die Phasenabhängigkeiten (Audio, Frames, Assembly, Übergänge, Untertitel, verifizieren, ausliefern) einem freiformatigen Build direkt folgen |
references/brief-contract.md | die Grundregeln des Briefings – Modus-Ableitung (kollaborativ / autonom), gemeinsames Feld-Register, Frage-Invarianten (die Frage selbst lebt in /hyperframes → der Intentionsebene) |
references/brief-format.md | BRIEF.md zu verfassen – das bestätigte Absichtsdokument, das ein Workflow-Setup schreibt und jeder spätere Schritt liest |
references/script-format.md | das optionale SCRIPT.md-locked-Narration zu verfassen |
references/subagent-dispatch.md | die Subagent-Dispatch-Verben (paralleles Fan-out / Hintergrund / warten) auf deine Umgebung abzubilden |
references/frame-worker-core.md | den gemeinsamen Frame-Worker-Rollenvertrag – jeder narrative Workflow-Paket-Builder stellt ihn seinem 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 spezifische Animationslaufzeiten (GSAP-API, Lottie, Three.js usw.) gehe zu hyperframes-animation → adapters/<runtime>.md.
Eine Komposition bauen
Zwei Root-Formen (nicht austauschbar)
- Eigenständig (Top-Level
index.html) – root<div data-composition-id="…">liegt direkt in<body>, kein<template>-Wrapper (ein Wrapper versteckt den gesamten Inhalt und bricht das Rendering). - Unterkomposition (geladen über
data-composition-src) – root muss in<template>verpackt sein.
⚠ Transportregel: Die Laufzeit klont nur
<template>-Inhalte; alles außerhalb (inkl.<head>-Styles/Skripte) wird verworfen – platziere<style>/<script>innerhalb des Templates. ⚠ Host-ID-Regel: Diedata-composition-iddes Host-Slots muss exakt derdata-composition-iddes inneren Templates und demwindow.__timelines["<id>"]-Schlüssel entsprechen – kein-mount/-slot/-host-Suffix.
Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.
Root muss Größe haben (stiller Layout-Bug)
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 – andernfalls kollabiert ein flex/100%-Child auf ~0 und der Inhalt türmt sich in der oberen linken Ecke. Verlasse dich nicht allein auf automatisierte Gates, um dies zu erkennen; überprüfe einen Snapshot. Skelett → references/minimal-composition.md.
Eine pausierte Timeline
Jede Komposition registriert exakt eine gsap.timeline({ paused: true }) unter window.__timelines["<id>"] (Schlüssel = root data-composition-id), synchron beim Seitenladen erstellt. Render-Dauer = root data-duration, nicht Timelinelänge. Verschachtele keine Unter-Timelines manuell in den 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 zwar erkennt, aber erst nachträglich – schreibe sie gleich richtig:
- Das Root-Kompositionselement muss
data-start="0"tragen (nebendata-composition-id/data-width/data-height); das Weglassen führt beilintzuroot_composition_missing_data_start. - Kombiniere niemals ein CSS-initiales
transformmit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Tween-Start kämpfen, undlintlehnt es mitgsap_css_transform_conflictab. Setze den Initialzustand innerhalb des Tweens mitgsap.fromTo(el, { x: -40 }, { x: 0 })anstelle eines CSStransform: translateX(-40px).
Nicht verhandelbare Regeln (stille Bugs, die automatisierte Gates übersehen können)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Laufzeituhren / ungesätes
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(endliche Anzahl verwenden). →determinism-rules.md - Nur die Allowlist visueller Eigenschaften animieren; niemals
displayoder rohesvisibilitytweenen. GSAPautoAlphaund Timeline-Grenzen mit Dauer Null sind die einzigen Sichtbarkeitsausnahmen, und nur auf Nicht-Clip-Elementen oder Wrappern innerhalb eines Clips. Das Framework allein steuert die.clip-Sichtbarkeit. Führe keingsap.setfür später erscheinende Clips beim Seitenladen aus. →determinism-rules.md - Kein
<br>im Fließtext; transformierte Elemente müssen block-level + dimensioniert sein; pulsierende absolute Dekorationselemente benötigen Spitzenabstand. →determinism-rules.md <video>/<audio>funktionieren in jeder Verschachtelungstiefe (auch innerhalb eines Unterkompositions-<template>oder Wrappers); das Framework besitzt die Wiedergabe und sucht/decodiert Medien, wo immer sie sich befinden. Die einzige Einschränkung betrifft Timelines, nicht die Platzierung: Eine Unterkompositions-Timeline kann keine Host-Root-Elemente animieren. →variables-and-media.md- Jede
idmuss über die assemblierte Seite hinweg eindeutig sein; innerhalb einer Unterkomposition IDs mit der Kompositions-ID präfixen (#<id>-hero). Doppelte<video>/<img>-IDs rendern leer – der Producer injiziert Frames pergetElementById, und Dateiübergreifende Duplikate entgehenlint. →composition-patterns.md - Ein Vollbild-Szenenfill geht auf ein vollflächiges Child (
position:absolute; inset:0), niemals auf das Kompositions-Root selbst – das Frame-Compositing des Producers kann das eigenebackgrounddes Root-Elements fallen lassen (das Frame rendert schwarz), obwohl die Vorschau/snapshotes korrekt anzeigen. →composition-patterns.md
Bestehende Kompositionen bearbeiten
- Lies zuerst die Dateien. Erhalte nicht zusammenhängendes Timing, Tracks, IDs, Variablen, Medienpfade.
- Stimme vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
- Hinzufügen eines Clips: Wähle einen nicht überlappenden
data-track-indexoder passe umgebendes Timing absichtlich an. data-hiddenauf einem Kompositionselement versteckt es sowohl in der VORSCHAU als auch im RENDER und überschreibt sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird durch das Timeline-Augen-Symbol von Studio umgeschaltet.- Hinzufügen einer Unterkomposition: Überprüfe ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkbesteht (0 Befunde über lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Unterkompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Frame überprüfen -
npx hyperframes previewzur Überprüfung (der Benutzer kann alles in Studios Timeline bearbeiten) -
npx hyperframes rendererst nach Genehmigung durch den Benutzer