HyperFrames Core
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM mit data-*-Attributen das Timing deklariert, deren Animationslaufzeit suchbar ist und deren Medienwiedergabe vom Framework verwaltet wird.
Dieses Skill ist der technische Vertrag. Andere Belange leben in benachbarten Skills:
hyperframes-animation— atomare Bewegungsregeln + Szenen-Blaupausen + Laufzeit-Adapter (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)hyperframes-creative— Paletten, Typografie, Narration, Beat-Planung, audio-reaktivhyperframes-media— TTS, Whisper-Transkription, Hintergrundentfernung, Untertitelhyperframes-registry— Blöcke und Komponenten installieren (hyperframes add)hyperframes-cli— Entwicklungs-Loop-Befehle (lint / validate / preview / render)
Für Tailwind v4 Projekte (hyperframes init --tailwind) siehe references/tailwind.md — der Browser-Laufzeitvertrag unterscheidet sich von Studios Tailwind v3 Setup.
Routing
| Möchten Sie… | Lesen Sie |
|---|---|
| Eine minimal renderbare Komposition sehen | references/minimal-composition.md |
| Zwischen monolithischer Einzeldatei- und modularer Unterkompositions-Architektur entscheiden | references/composition-patterns.md |
Ein modulares index.html strukturieren (Orchestrator + Slots + Root-Audio) | references/composition-patterns.md |
| Einen Unterkompositions-Archetyp wählen (Inhalt / Nur-Treiber / Multi-Szene-Merge / Audio-reaktiv) | references/composition-patterns.md |
Ein data-*-Attribut nachschlagen (Root, Clip, Sub-Comp-Host, Legacy-Aliase) | references/data-attributes.md |
class="clip" korrekt verwenden | references/data-attributes.md |
Einen data-track-index wählen; Überlappung auf gleichem Track; Track-Index vs CSS z-index | references/tracks-and-clips.md |
Einen Clip relativ zu einem anderen timen (data-start="intro + 2", Crossfade-Überlappung, Ketten) | references/tracks-and-clips.md |
Eine Unterkomposition verdrahten (Host-Attribute, <template>-Wrapper, Instanz-Variablen) | references/sub-compositions.md |
Innerhalb einer Unterkomposition animieren (gsap.fromTo statt gsap.from, Rückwärtssuch-Verhalten) | references/sub-compositions.md |
Variablen deklarieren (Typen, Zusatzoptionen, Standardwerte, --strict-variables in CI) | references/variables-and-media.md |
<video> / <audio> platzieren, Lautstärke setzen, mit data-media-start trimmen | references/variables-and-media.md |
Eine suchbare Timeline erstellen (pausiert, synchrone Konstruktion, gsap.set-Spätszenen-Falle) | references/determinism-rules.md |
Nicht-deterministischen Zustand vermeiden (Uhren, Math.random, repeat: -1, endliche Wiederholungsformel) | references/determinism-rules.md |
Wissen, was animiert werden kann / nicht animiert werden darf (visuelle Eigenschafts-Whitelist; nicht display/visibility) | references/determinism-rules.md |
Text anpassen und Überlauf verhindern (fitTextFontSize-Signatur, <br>-Regel, Layout-Vertrag) | references/determinism-rules.md |
| Vollbild-Bewegung mit gemeinsamen Hintergründen erstellen | references/full-screen-motion.md |
In einem Tailwind v4 Projekt arbeiten (init --tailwind) | references/tailwind.md |
Für Animationslaufzeit-Details (GSAP-API, Lottie, Three.js, etc.) gehen Sie zu hyperframes-animation → adapters/<runtime>.md.
Kompositionsstruktur
Zwei Wurzel-Formen; sie sind nicht austauschbar.
- Eigenständig (das oberste
index.html) — root<div data-composition-id="…">sitzt direkt in<body>. Kein<template>-Wrapper. Das Ummanteln eines eigenständigen Root in<template>versteckt alle Inhalte vor dem Browser und zerstört das Rendern. - Unterkomposition (eine Datei, die über
data-composition-srcgeladen wird) — root<div data-composition-id="…">muss in<template>umschlossen sein. Ohne den Wrapper kann die Laufzeitumgebung es nicht extrahieren und einhängen.
⚠ Unterkompositions-Transportregel: Die Laufzeitumgebung klont nur
<template>-Inhalte in das live DOM. Alles außerhalb des Templates — einschließlich<head>und alle<style>/<script>/<link>im<head>— wird verworfen. Platzieren Sie<style>- und<script>-Blöcke innerhalb<template>, nicht in<head>.⚠ Host-ID-Regel: In der Host-Datei muss
data-composition-idam Slot exakt gleich der innerendata-composition-iddes Templates und deswindow.__timelines["<id>"]-Schlüssels sein. Fügen Sie keine-mount/-slot/-host-Suffixe hinzu.
Siehe references/sub-compositions.md für die Dateiform, Host-Verdrahtung, Fallstrickbeispiele und die Pre-Render-Verifizierungs-Checkliste.
Root muss dimensioniert sein (stiller Layout-Fehler)
Der eigenständige Root muss einen explizit dimensionierten Kasten herstellen, und jeder Vorfahre zwischen ihm und einem height: 100%-Element muss eine aufgelöste Höhe haben. Wenn der Root oder ein Zwischenwrapper keine Höhe hat, fällt ein Flex-/height:100%-Inhaltscontainer auf ~0 zusammen und Inhalte stapeln sich in der linken oberen Ecke (oft wird das erste Zeichen bei x=0 abgeschnitten). lint, validate und inspect fangen dies nicht — inspect ersetzt das erstellte data-width/data-height für einen kollabierten Root und meldet "0 Layout-Probleme."
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- Zentrieren Sie robust: position:absolute + inset:0 füllt den dimensionierten Root unabhängig von
Zwischenwrappern; oder verwenden Sie einen Flex-Container NUR wenn seine Elternkette dimensioniert ist. -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>Titel</h1>
</section>
</div>
</body>
Behalten Sie das padding (≥80px) auf dem Zentrierungscontainer — es ist der titelsichere Rand, der verhindert, dass große Schrift die Rahmenkante berührt. Siehe references/minimal-composition.md.
Timeline-Vertrag (GSAP-Standard)
Jede Komposition registriert genau eine GSAP-Timeline.
- Erstellen mit
gsap.timeline({ paused: true })— der Player besitzt die Wiedergabe. - Registrieren bei
window.__timelines["<composition-id>"]; der Schlüssel muss exakt demdata-composition-iddes Root entsprechen. Dot-Syntax (window.__timelines.<id> = tl) ist äquivalent, wenn die ID ein gültiger Bezeichner ist; verwenden Sie Klammern, wenn die ID-enthält. - Bauen Sie die Timeline synchron während des Seitenladens — nicht innerhalb von
async,setTimeout,Promiseoder Ereignis-Handlern. Der Renderer erfasst nach Abschluss des Seitenladens; jede verzögerte Timline-Konstruktion verpasst die Erfassung. - Die Rendering-Dauer kommt von
data-durationam Root, nicht von der GSAP-Timeline-Länge. Polstern Sie die Timeline nicht mit leeren Tweens, um die Dauer zu setzen. - Für Unterkompositionen: Verschachteln Sie Unter-Timelines nicht manuell in den Host (
master.add(sub)); das Framework steuert sie unabhängig.
Für Nicht-GSAP-Laufzeiten (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU) lebt der äquivalente Vertrag in hyperframes-animation/adapters/<runtime>.md. Siehe references/determinism-rules.md für den laufzeitübergreifenden Animationslaufzeitvertrag.
Unverhandelbare Regeln
Diese brechen den Renderer — oder erzeugen stille visuelle Fehler, die lint/validate/inspect NICHT erkennen (Regeln 3, 7-8). (Synchroner Timline-Aufbau ist oben unter Timeline-Vertrag abgedeckt.)
- Kein
Math.random()/Date.now()/performance.now(), die Grafiken steuern — verwenden Sie einen gesähten PRNG. - Kein
repeat: -1. Verwenden Sierepeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)—floor, nichtceil(ceilüberschreitetdata-durationund löst dengsap_repeat_ceil_overshoot-Lint aus;max(0, …)vermeidet ein negatives Repeat = unendlich). <video>/<audio>muss ein direktes Kind des Host-Root (index.html) sein — niemals innerhalb eines Unterkompositions-<template>, niemals innerhalb eines Wrapper-<div>; sonst wird es nie dekodiert und rendert leer/schwarz (stiller Fehler). Das Framework besitzt die Wiedergabe: keinvideo.play()/audio.play()/currentTime = …. Eine Unterkomposition kann keine Host-Elemente steuern (Selektor oderquerySelector), also animieren Sie Host-Medien von der Haupt-Timeline zur globalen Zeit. Siehereferences/variables-and-media.md.- Kein
gsap.set()auf Clip-Elementen aus späteren Szenen (sie sind noch nicht im DOM). Verwenden Sietl.set(selector, vars, time)zum oder nach demdata-startdes Clips. - Kein Animieren von
display/visibility. Animieren Sieopacity/ Transformationen; der Clip-Lebenszyklus kümmert sich um Ein-/Ausblenden. - Kein
<br>im Fließtext. Lassen Sie Text übermax-widthumbrechen. - Transformierte Elemente müssen block-level + dimensioniert sein.
transform/scaleX/scaleYist ein No-op auf einem inline<span>, und das Skalieren eines auto-width (0px) Elements zeigt nichts → unsichtbare Balken/Füllungen. Geben Sie ihnendisplay: block/inline-block/flex-item und eine echtewidth/height(z.B.width: 100%innerhalb eines dimensionierten Elternteils). - Absolut positionierte dekorative Elemente (Badges, Pills, Tags), die pulsieren oder überschwingen (
yoyo-Skalierung,back.out), benötigen Platz auf ihrer maximalen Größe und dürfen keine Kante mitoverflow: hiddenüberschreiten — sonst überlappen sie einen Nachbarn oder werden abgeschnitten. Positionieren Sie für den größten Frame, nicht den Ruhezustand.
Bestehende Kompositionen bearbeiten
- Lesen Sie die tatsächlichen Dateien vor dem Bearbeiten.
- Erhalten Sie nicht verwandtes Timing, Tracks, IDs, Variablen und Medienpfade.
- Übereinstimmung mit bestehenden Kompositions-IDs und Timeline-Registry-Schlüsseln.
- Wenn Sie einen Clip hinzufügen, wählen Sie einen nicht überlappenden
data-track-indexoder passen Sie das umgebende Timing absichtlich an. - Wenn Sie eine Unterkomposition hinzufügen, überprüfen Sie deren interne
data-composition-id, bevor Sie den Host verdrahten.
Validierung
Verwenden Sie hyperframes-cli für Befehlsdetails.
-
npx hyperframes lintbesteht (0 Fehler) -
npx hyperframes validatebesteht (0 Konsolenfehler) -
npx hyperframes inspectbesteht, oder Überlauf ist absichtlich markiert - Projekte mit Unterkompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild ansehen