HyperFrames Core
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM das Timing mit data-*-Attributen deklariert, deren Animationslaufzeit seekbar 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; Details zu einzelnen Themen finden sich in references/ (Index als nächstes), lies sie bei Bedarf. Andere Belange werden in den verwandten Domänenskills behandelt – hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jeder abdeckt.
Referenzen
| Datei | Lies sie, um… |
|---|---|
references/minimal-composition.md | von der kleinsten renderbaren Kompositionsstruktur zu starten |
references/composition-patterns.md | monolithisch vs. modular zu wählen; eine modulare index.html zu strukturieren; einen Subkompositions-Archetyp auszuwä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, gleichzeitige Track-Überlappung / z-Index zu handhaben, einen Clip relativ zu einem anderen zu timen |
references/sub-compositions.md | eine Subkomposition zu verdrahten (Host-Attribute, <template>, instanzspezifische 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 seekbare Timeline zu erstellen; Determinismus-Verbote; die Whitelist animierbarer Eigenschaften; Layout / Textfit |
references/full-screen-motion.md | Vollbildbewegung mit gemeinsamen Hintergründen zu authorisieren |
references/storyboard-format.md | einen STORYBOARD.md-Plan zu authorisieren (+ das geparste Manifest) |
references/script-format.md | das optionale SCRIPT.md-Textskript zu authorisieren |
references/subagent-dispatch.md | Subagenten-Dispatch-Verben (paralleles Fan-Out / Hintergrund / Warten) auf deine Harness abzubilden |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; Laufzeitvertrag unterscheidet sich von Studio's v3) |
Für spezifische Animationslaufzeiten (GSAP API, Lottie, Three.js usw.) gehe zu hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Wurzelformen (nicht austauschbar)
- Standalone (Top-Level
index.html) – die Wurzel<div data-composition-id="…">sitzt direkt in<body>, ohne<template>-Wrapper (ein Wrapper versteckt den gesamten Inhalt und bricht das Rendern). - Subkomposition (geladen über
data-composition-src) – die Wurzel muss in<template>eingewickelt sein.
⚠ Transportregel: Die Laufzeit klont nur
<template>-Inhalte; alles außerhalb (einschließlich<head>-Styles/Skripte) wird verworfen – setze<style>/<script>innerhalb des Templates. ⚠ Host-ID-Regel: Diedata-composition-iddes Host-Slots muss exakt gleich derdata-composition-iddes inneren Templates und demwindow.__timelines["<id>"]-Schlüssel sein – kein-mount/-slot/-host-Suffix.
Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.
Wurzel muss dimensioniert sein (stiller Layout-Fehler)
Die Standalone-Wurzel benötigt eine explizite dimensionierte Box (width/height in px), und jeder Vorfahre bis zu einem height:100%-Element 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. lint/validate/inspect fangen dies nicht. Struktur → references/minimal-composition.md.
Eine pausierte Timeline
Jede Komposition registriert genau eine gsap.timeline({ paused: true }) bei window.__timelines["<id>"] (Schlüssel = Wurzel data-composition-id), die synchron beim Seitenladen erstellt wird. Renderdauer = Wurzel data-duration, nicht Timeline-Länge. Verschachtle nicht manuell Subtimelines in den Host. Vollständiger Vertrag (einschließlich Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Nicht verhandelbare Regeln (stille Fehler, die lint/validate/inspect nicht fangen)
Hier aufgelistet; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Renderzeit-Uhren / ungesätes
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(verwende eine endliche Anzahl). →determinism-rules.md - Nur die visuelle Eigenschafts-Whitelist animieren; niemals
display/visibility; keingsap.setauf Clips späterer Szenen. →determinism-rules.md - Kein
<br>im Textkörper; transformierte Elemente müssen auf Blockebene + dimensioniert sein; pulsierende absolute Dekorationen benötigen Spitzenabstand. →determinism-rules.md <video>/<audio>muss ein direktes Kind der Host-Wurzel sein (niemals innerhalb eines Subkompositions-<template>/Wrappers); das Framework besitzt die Wiedergabe. →variables-and-media.md- Jede
idmuss über die gesamte montierte Seite eindeutig sein; innerhalb einer Subkomposition ids mit der Kompositions-ID voranstellen (#<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 geht auf ein randloses Kind (
position:absolute; inset:0), niemals auf die Kompositionswurzel selbst – die Frame-Kompositionierung des Producers kann das eigenebackgrounddes Wurzelelements fallen lassen (der Frame rendert schwarz), auch wenn Vorschau/snapshotes korrekt anzeigen. →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lies die Dateien zuerst. Bewahre unabhängiges Timing, Tracks, IDs, Variablen, Medienpfade.
- Gleiche vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
- Einen Clip hinzufügen: Wähle einen nicht überlappenden
data-track-indexoder passe das umgebende Timing absichtlich an. - Eine Subkomposition hinzufügen: Überprüfe ihre interne
data-composition-idvor dem Verdrahten des Hosts.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes lintbestanden (0 Fehler) -
npx hyperframes validatebestanden (0 Konsolenfehler) -
npx hyperframes inspectbestanden (0 Fehler) - Projekte mit Subkompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Frame visuell prüfen -
npx hyperframes previewzur Überprüfung (der Benutzer kann alles in der Studio-Timeline bearbeiten) -
npx hyperframes rendernur nach Freigabe durch den Benutzer