HyperFrames Core
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM das Timing mit data-*-Attributen deklariert, deren Animationslaufzeit suchbar ist und deren Medienwiedergabe dem Framework gehört.
Dieser Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Bauleitfaden; detaillierte Themen leben in references/ (Index als nächstes), die bei Bedarf gelesen werden. Andere Belange sind in den zugehörigen Domän-Skills behandelt – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jeder abdeckt.
Referenzen
| Datei | Lesen, 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 Sub-Kompositions-Archetyp zu wä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 innerhalb des gleichen Tracks zu handhaben, einen Clip relativ zu einem anderen zu timen |
references/sub-compositions.md | eine Unterkomposition einzurichten (Host-Attribute, <template>, Instanzvariablen) und darin zu animieren |
references/variables-and-media.md | Variablen zu deklarieren; <video>/<audio> zu platzieren, Lautstärke und Trimmung einzustellen |
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 geteilten Hintergründen zu gestalten |
references/storyboard-format.md | einen STORYBOARD.md-Plan zu erstellen (+ das geparste Manifest) |
references/brief-contract.md | die Erfassung eines Erstellungs-Workflows durchzuführen – Interaktionsmodus (kollaborativ / autonom), gemeinsame Brief-Felder, Frageregeln |
references/script-format.md | das optionale, festgelegte SCRIPT.md-Erzähltext zu verfassen |
references/subagent-dispatch.md | Subagent-Dispatch-Verben (paralleles Fan-out / Hintergrund / Warten) auf Ihre Umgebung abzubilden |
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 erstellen
Zwei Root-Formen (nicht austauschbar)
- Standalone (top-level
index.html) – root<div data-composition-id="…">steht direkt im<body>, kein<template>-Wrapper (ein Wrapper versteckt den gesamten Inhalt und bricht das Rendering). - Sub-Composition (geladen über
data-composition-src) – root muss in<template>eingewickelt sein.
⚠ Transportregel: Die Laufzeit klont nur
<template>-Inhalte; alles außerhalb (inkl.<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 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 dimensioniert sein (stiller Layout-Bug)
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 – 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. 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), die synchron beim Seitenladen erstellt wird. Render-Dauer = root data-duration, nicht Timeline-Länge. Verschachtele keine Sub-Timelines manuell im Host. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Nicht verhandelbare Regeln (stille Fehler, die lint/validate/inspect nicht erkennen)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Renderzeit-Uhren / ungesäter
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(endliche Anzahl verwenden). →determinism-rules.md - Nur die visuelle Eigenschafts-Allowlist 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 des Host-Roots sein (niemals innerhalb eines Sub-Komp-<template>/Wrappers); das Framework besitzt die Wiedergabe. →variables-and-media.md- Jede
idmuss über die gesamte montierte Seite eindeutig sein; innerhalb einer Sub-Komp IDs mit der Kompositions-ID präfixieren (#<id>-hero). Doppelte<video>/<img>-IDs rendern leer – der Producer injiziert Frames pergetElementById, und dateiübergreifende Dubletten entgehenlint. →composition-patterns.md - Ein Vollbild-Szenen-Fill gehört auf ein randloses Kind (
position:absolute; inset:0), niemals auf den Kompositions-Root selbst – die Frame-Kompositionierung des Producers kann das eigenebackgrounddes Root-Elements wegwerfen (das Frame rendert schwarz), obwohl Vorschau/snapshotes korrekt zeigen. →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lies zuerst die Dateien. Erhalte nicht zusammenhängende Zeitangaben, Tracks, IDs, Variablen, Medienpfade.
- Stimme vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
- Einen Clip hinzufügen: wähle einen nicht überlappenden
data-track-indexoder passe die umgebende Zeit bewusst an. data-hiddenauf einem Kompositions-Element versteckt es sowohl in der VORSCHAU als auch im RENDER und überschreibt sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird vom Timeline-Augen-Symbol von Studio umgeschaltet.- Eine Sub-Komposition hinzufügen: überprüfe ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkläuft durch (0 Funde bei lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild begutachten -
npx hyperframes previewzur Überprüfung (der Benutzer kann alles in der Timeline von Studio bearbeiten) -
npx hyperframes rendererst nach Zustimmung des Benutzers