HyperFrames Core
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM das Timing mit data-*-Attributen deklariert, deren Animations-Laufzeit suchbar ist und deren Medienwiedergabe vom Framework gesteuert wird.
Dieses Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Bauleitfaden; Details zu den einzelnen Themen befinden sich in references/ (nächster Index), die bei Bedarf gelesen werden. Weitere Belange sind in den verwandten Domänen-Skills enthalten – hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes sagt, was jedes abdeckt.
Referenzen
| Datei | Lies sie, um… |
|---|---|
references/minimal-composition.md | mit dem kleinsten renderbaren Kompositionsgerüst zu beginnen |
references/composition-patterns.md | monolithisch vs. modular zu wählen; ein modulares index.html zu strukturieren; einen Sub-Kompositions-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 derselben Spur zu behandeln, einen Clip relativ zu einem anderen zu timen |
references/sub-compositions.md | eine Sub-Komposition 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 suchbare Zeitleiste zu erstellen; Determinismus-Verbote; die Erlaubnisliste animierbarer Eigenschaften; Layout / Textanpassung |
references/full-screen-motion.md | Vollbildbewegungen mit gemeinsamen Hintergründen zu erstellen |
references/storyboard-format.md | einen STORYBOARD.md-Plan zu verfassen (+ das geparste Manifest) |
references/script-format.md | die optionale SCRIPT.md mit festgelegtem Erzähltext zu verfassen |
references/subagent-dispatch.md | die Subagent-Dispatch-Verben (parallele Verzweigung / Hintergrund / Warten) auf dein Hilfsprogramm abzubilden |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; der Laufzeitvertrag unterscheidet sich vom v3 von Studio) |
Details zur Animations-Laufzeit (GSAP API, Lottie, Three.js usw.) findest du unter hyperframes-animation → adapters/<runtime>.md.
Erstellen einer Komposition
Zwei Root-Formen (nicht austauschbar)
- Standalone (Top-Level
index.html) – Root<div data-composition-id="…">liegt direkt im<body>, kein<template>-Wrapper (ein Wrapper verbirgt den gesamten Inhalt und bricht das Rendering). - Sub-Komposition (geladen über
data-composition-src) – Root muss in<template>eingeschlossen sein.
⚠ Transportregel: Die Laufzeit klont nur den Inhalt von
<template>; alles außerhalb (einschließlich<head>-Styles/Scripts) wird verworfen – setze<style>/<script>innerhalb des Templates. ⚠ Host-ID-Regel: Diedata-composition-iddes Host-Slots muss exakt derdata-composition-iddes inneren Templates und dem Schlüsselwindow.__timelines["<id>"]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 Standalone-Root 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 – andernfalls 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 ab. Gerüst → 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 Laden der Seite erstellt wird. Render-Dauer = Root data-duration, nicht Zeitleistenlänge. Verschachtele keine Sub-Zeitleisten manuell im Host. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Unverhandelbare Regeln (stille Fehler, die lint/validate/inspect nicht abfangen)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Render-Zeit-Uhren / ungesäter
Math.random-Aufruf / Netzwerk / Eingabezustand; keinrepeat: -1(verwende eine endliche Anzahl). →determinism-rules.md - Nur die visuelle Eigenschaftserlaubnisliste animieren; niemals
display/visibility; keingsap.setauf Clips späterer Szenen. →determinism-rules.md - Kein
<br>im Fließtext; transformierte Elemente müssen Block-Ebene sein + dimensioniert; pulsierende absolute Dekorationselemente benötigen Spitzenfreiheit. →determinism-rules.md <video>/<audio>muss ein direktes Kind des Host-Roots sein (niemals innerhalb eines Sub-Comp<template>/Wrappers); das Framework besitzt die Wiedergabe. →variables-and-media.md- Jede
idmuss auf der zusammengebauten Seite eindeutig sein; innerhalb einer Sub-Komposition die IDs mit der Kompositions-ID (#<id>-hero) versehen. Doppelte<video>/<img>-IDs rendern leer – der Produzent injiziert Frames mittelsgetElementById, und dateiübergreifende Duplikate entgehenlint. →composition-patterns.md - Eine Vollbild-Szenenfüllung erfolgt auf einem randlosen Kind (
position:absolute; inset:0), niemals auf dem Kompositions-Root selbst – die Frame-Zusammensetzung des Produzenten kann das eigenebackgrounddes Root-Elements verwerfen (der Frame rendert schwarz), selbst wenn die Vorschau/snapshotes korrekt anzeigen. →composition-patterns.md
Bearbeiten vorhandener Kompositionen
- Lies zuerst die Dateien. Bewahre nicht zusammenhängendes Timing, Spuren, IDs, Variablen, Medienpfade.
- Verwende vorhandene Kompositions-IDs und Zeitleistenschlüssel.
- Beim Hinzufügen eines Clips: wähle einen nicht überlappenden
data-track-indexoder passe das umgebende Timing bewusst an. - Beim 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 lintbestanden (0 Fehler) -
npx hyperframes validatebestanden (0 Konsolenfehler) -
npx hyperframes inspectbestanden (0 Fehler) - Projekte mit Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild prüfen -
npx hyperframes previewzur Überprüfung (der Benutzer kann alles in der Studio-Zeitleiste bearbeiten) -
npx hyperframes rendererst nach Zustimmung des Benutzers