HyperFrames Core
Agenten-Fallstricke (zuerst lesen):
- Zentriere mit Flex/
inset, nicht mit CSStransform: translate(-50%,-50%)auf einem Knoten, den du dann per GSAPx/yanimierst. Lint:gsap_css_transform_conflict. VerwendefromTooderxPercent/yPercent. - Füge keinen Szenenausgang
tl.set(..., {visibility:"hidden"})hinzu. Die Laufzeit blendet getimte Clips bereits aus. Opazitäts-Überblendungen auf inneren Knoten (oderopacityauf.clip) reichen aus. Caption-Hard-Kills folgen einer anderen Regel. window.__timelines["id"]muss mit der Root-data-composition-idübereinstimmen.- Lies nach dem
renderdie zweite Zeile der Zusammenfassung:beginframevs.screenshot, GPU-Modus, Stage-Timings.screenshot+software gpuauf Linux ist der langsame Pfad.
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 gesteuert wird.
Dieser Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Body ist der Bauleitfaden; detaillierte Informationen zu den einzelnen Themen findest du in references/ (Index siehe unten) – lies diese bei Bedarf. Prozessdokumente (Brief, Storyboard, Review, Produktion, Dispatch, Frame-Worker) befinden sich in /hyperframes → references/. Andere Aspekte sind in den verwandten Domänen-Skills zu finden – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes zeigt, was jeder Skill abdeckt.
Referenzen
| Datei | Lies es, um… |
|---|---|
references/minimal-composition.md | mit dem kleinstmöglichen, renderbaren Kompositionsgerüst zu beginnen |
references/composition-patterns.md | die Wahl zwischen monolithisch und modular zu treffen; eine modulare index.html zu strukturieren; einen Sub-Kompositions-Archetyp zu wählen |
references/data-attributes.md | jedes data-* (Root / Clip / Sub-Kompositions-Host / Legacy-Aliase) nachzuschlagen; class="clip" zu verwenden |
references/tracks-and-clips.md | zu verstehen, was data-track-index steuert (und was nicht), z-Index, einen Clip relativ zu einem anderen zu timen; jeden Track und Clip mit npx hyperframes timeline aufzulisten |
references/creator-editing-recipes.md | wahrheitsgemäße Cut/Trim/Reorder/Retime/Freeze/Camera/Mask/Crossfade/Audio-Editing-Rezepte und deren Grenzen zu kopieren |
references/sub-compositions.md | eine Sub-Komposition einzurichten (Host-Attribute, <template>, Instanz-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 Timeline zu bauen; Determinismus-Verbote zu kennen; Layout / Textanpassung |
references/full-screen-motion.md | Vollbild-Bewegungen mit gemeinsamen Hintergründen zu erstellen |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; der Laufzeitvertrag unterscheidet sich von Studios v3) |
Details zur Animationslaufzeit (GSAP-API, Lottie, Three.js usw.) findest du unter hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Root-Formen (nicht austauschbar)
- Standalone (Top-Level
index.html): Root<div data-composition-id="…">liegt direkt im<body>, kein<template>-Wrapper. Das Umwickeln eines Standalone-Roots verbirgt den gesamten Inhalt undlintlehnt es ab (standalone_composition_wrapped_in_template, Fehler). - Sub-Komposition (geladen über
data-composition-src): Wickle das Root in<template>. Das ist die empfohlene Schreibweise: Der Lader akzeptiert auch ein einfaches vollständiges Dokument und fällt auf dessen<body>zurück, aber die getemplatete Form wird in den Beispielen und Tools vorausgesetzt.
⚠ Transportregel: Für eine getemplatete Sub-Komposition verwirft der Assembler die eigenen
<head><style>/<script>der Datei (packages/core/src/compiler/compositionAssembly.ts, dashasTemplate-Gate). Platziere daher<style>/<script>innerhalb des Templates.<link>wird in jedem Fall nach oben verschoben. ⚠ Host-ID-Konvention: Gib dem Host-Slot, dem inneren Template und demwindow.__timelines["<id>"]-Schlüssel dieselbe ID. Eine andere lokale ID wird unterstützt (der Assembler fällt auf das erste Root in der Datei zurück), aber der Unterschied ist still, also gleiche sie ab, es sei denn, du hast einen Grund dagegen.
Dateiform, Host-Verdrahtung und Pre-Render-Checkliste → references/sub-compositions.md.
Root muss eine Größe haben (stiller Layout-Fehler)
Der Standalone-Root setzt width/height: 100%. Die Canvas-Größe wird durch data-width/data-height bestimmt. Die Laufzeit schreibt diese Pixel auf das Kompositions-Root. Hartcodiere nicht 1920px/1080px auf #root. Skelett → references/minimal-composition.md.
Eine pausierte Timeline
Jede Komposition registriert genau eine gsap.timeline({ paused: true }) unter window.__timelines["<id>"] (Schlüssel = Root-data-composition-id). Das Erstellen in einem asynchronen Callback (document.fonts.ready) wird unterstützt; wichtig ist, dass du erst nach Abschluss des Baus registrierst. Die Renderlänge ist die data-duration des Roots, nicht die Länge der Timeline: Eine Timeline, die darüber hinausläuft, wird abgeschnitten, und eine, die früher endet, hält ihren letzten Frame. Wird data-duration am Root weggelassen, wird die Länge stattdessen abgeleitet (Timeline, Medienfenster oder Adapter). Du benötigst kein window.__timelines = window.__timelines || {}: Die Laufzeit erstellt das Register, bevor deine Inline-Skripte ausgeführt werden, und lint fragt nicht mehr danach. Verschachtle Sub-Timelines nicht manuell im Host; die Laufzeit verschachtelt registrierte Child-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Lint-Fallen beim ersten Durchlauf (garantierter erster Build-Fehler)
Regeln, die lint zwar erkennt, aber erst im Nachhinein. Schreibe sie gleich richtig:
- Kombiniere niemals eine initiale CSS-
transformmit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Start des Tweens streiten sich undlintlehnt es mitgsap_css_transform_conflictab. Setze den Anfangszustand im Tween mitgsap.fromTo(el, { x: -40 }, { x: 0 })statt einem CSStransform: translateX(-40px). - Setze niemals
crossoriginauf<video>/<audio>.lintlehnt es bedingungslos mitmedia_crossorigin_breaks_preview(Fehler) ab, auch für Canvas/WebGL/WebAudio-Rücklesen. Es gibt keine Unterdrückung. - Gib einem
<video data-start>keinen Vorfahren, der ebenfallsdata-startträgt.lintlehnt es mitvideo_nested_in_timed_element(Fehler) ab. Timing auf den Wrapper oder das Video, niemals beide. - Jedes
<audio>benötigt eineid.lintlehnt es mitmedia_missing_idab, und ein<audio>ohne ID wird vom Mixer nie erfasst, daher ist der Render stumm. - Tweete niemals ein
.clip-Element mitautoAlphaodervisibility–lintlehnt es mitgsap_animates_clip_elementab. Animiere stattdessen ein Kindelement. - Ein benannter CSS-
font-familybenötigt ein@font-facein der Datei, das auf eine ausgelieferte lokale Datei verweist, sonst feuertlintfont_family_without_font_face. - Die Sub-Komposition
#rootverwendetwidth/height: 100%(oderinset: 0), nicht hartcodierte1920px/1080px. Die Canvas-Größe wird durchdata-width/data-heightbestimmt.
Ein Fehler im Lint schaltet auch die Layout- und Kontrast-Audits aus: check meldet dann 0 sample(s) und 0/0 text checks, was wie eine saubere Datei aussieht, aber bedeutet, dass nichts gelaufen ist. Behebe Lint-Fehler, bevor du diesen Zahlen vertraust.
Nicht verhandelbare Regeln (stille Fehler, die automatisierte Gates möglicherweise übersehen)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Render-Zeituhren / ungesätes
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(verwende eine endliche Anzahl). →determinism-rules.md - Niemals
display,visibilityoderautoAlphaauf einem.clip-Element animieren. Das Framework verwaltet die Clip-Sichtbarkeit, undlintlehnt es ab (gsap_animates_clip_element). Animiere stattdessen ein Kindelement. →determinism-rules.md - Kein
<br>im Fließtext; transformierte Elemente müssen block-level + groß sein; pulsierende absolute Dekorationselemente benötigen Peak-Freiraum. →determinism-rules.md <video>/<audio>werden durch eine flache Dokumentabfrage gefunden, daher sucht und dekodiert das Framework sie in beliebiger Verschachtelungstiefe (auch innerhalb eines Sub-Kompositions-<template>oder Wrappers). Eine harte Grenze:lintgibt einen Fehler aus, wenn ein<video data-start>in einem anderen einfachen Element sitzt, das ebenfallsdata-starthat, und der Fehler ist real (falsche Quellframes, dann verschwindet der Clip mitten im Slot). Setze das Timing also auf den Wrapper oder auf das Video, niemals beide. Sub-Kompositions-Hosts sind ausgenommen: Medien innerhalb einer Sub-Komposition werden korrekt gerendert. Der andere Vorbehalt betrifft Timelines, nicht die Platzierung: Eine Sub-Kompositions-Timeline kann keine Host-Root-Elemente animieren. →variables-and-media.md- Halte jede
idüber die assemblierte Seite hinweg eindeutig (stelle Sub-Kompositions-IDs das Kompositions-ID voran,#<id>-hero), damit deine eigenen#id-CSS- undgetElementById-Aufrufe funktionieren. Frame-Injection hängt nicht mehr davon ab: Der Compiler stempelt eine dokumenteindeutigedata-hf-render-idauf jedesvideo[src]/audio[src]/img[src]. Medien, die<source>-Kinder anstelle einessrc-Attributs verwenden, werden nicht gestempelt, daher sind eindeutige IDs dort immer noch wichtig. →composition-patterns.md - Eine Vollbildfüllung auf dem Kompositions-Root ist bei einem normalen Render in Ordnung. Sie wird nur auf dem geschichteten Composite-Pfad (HDR-Inhalt oder eine Komposition mit Shader-Übergängen) entfernt, wo die Engine jedes Kompositions-Root transparent macht, damit die darunter liegende Schicht durchscheint. Wenn deine Komposition Shader-Übergänge oder HDR-Medien verwendet, platziere die Füllung auf einem vollflächigen Kind (
position:absolute; inset:0). →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lies zuerst die Dateien. Bewahre nicht betroffene Timings, Tracks, IDs, Variablen, Medienpfade.
- Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Tracks, Clips, Starts, Enden, was abgespielt wird), führe
npx hyperframes timeline [--json]aus, anstattindex.htmlund jede Sub-Kompositionsdatei zu lesen. - Gleiche vorhandene Kompositions-IDs und Timeline-Keys ab.
- Hinzufügen eines Clips: Setze
data-start/data-durationabsichtlich in Bezug auf die umgebenden Clips.data-track-indexist eine Studio-Anzeigespur, keine Timing-Einschränkung, muss also nicht frei sein. data-hiddenauf einem beliebigen Kompositionselement blendet es sowohl in der Vorschau als auch im Render aus und überschreibt sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird durch das Timeline-Augen-Symbol von Studio umgeschaltet.- Hinzufügen einer Sub-Komposition: Überprüfe die interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkbesteht (0 Fundstellen in den Bereichen Lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jeden Frame in Augenschein nehmen -
npx hyperframes preview --backgroundfür Review (der Benutzer kann alles in Studios Timeline bearbeiten, und der Server überlebt den aufrufenden Befehl) -
npx hyperframes rendernur, nachdem der Benutzer zugestimmt hat