HyperFrames Kern
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 Szenen-Exit
tl.set(..., {visibility:"hidden"})hinzu. Die Laufzeit blendet getimte Clips bereits aus. Opazitäts-Überblendungen auf inneren Knoten (oderopacityauf.clip) sind ausreichend. Caption-Hard-Kills folgen einer anderen Regel. window.__timelines["id"]muss mit der Rootdata-composition-idübereinstimmen.- Nach
renderlies die zweite Zeile der Zusammenfassung:beginframevs.screenshot, GPU-Modus, Stufen-Timings.screenshot+software gpuunter Linux ist der langsame Pfad.
HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM das Timing mit data-*-Attributen deklariert, deren Animations-Laufzeit seekbar ist und deren Media-Playback vom Framework verwaltet wird.
Dieses Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Build-Leitfaden; detaillierte Themen finden sich in references/ (Index siehe nächster Abschnitt), auf Abruf lesen. Prozessdokumente (Briefing, Storyboard, Review, Produktion, Dispatch, Frame-Worker) leben in /hyperframes → references/. Andere Belange leben in den benachbarten Domain-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jedes Skill abdeckt.
Referenzen
| Datei | Lies es, um… |
|---|---|
references/minimal-composition.md | vom kleinsten renderbaren Kompositions-Skelett zu starten |
references/composition-patterns.md | monolithisch vs. modular zu wählen; ein modulares index.html zu strukturieren; einen Sub-Kompositions-Archetyp auszuwählen |
references/data-attributes.md | jedes data-*-Attribut (Root / Clip / Sub-Komp-Host / Legacy-Alias) nachzuschlagen; class="clip" zu verwenden |
references/tracks-and-clips.md | zu verstehen, was data-track-index (nicht) steuert, z-index, einen Clip relativ zu einem anderen zu timen; jeden Track und Clip mit npx hyperframes timeline aufzulisten |
references/creator-editing-recipes.md | wahrheitsgetreue Cut/Trim/Reorder/Retime/Freeze/Camera/Mask/Crossfade/Audio-Bearbeitungsrezepte und ihre Grenzen zu kopieren |
references/sub-compositions.md | eine Sub-Komposition zu verdrahten (Host-Attribute, <template>, Instanz-Variablen) 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 seekbare Timeline zu bauen; Determinismus-Verbote; Layout / Textfit |
references/full-screen-motion.md | Vollbild-Bewegung mit gemeinsamen Hintergründen zu erstellen |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; Laufzeitvertrag unterscheidet sich von Studio v3) |
Für Details zur Animations-Laufzeit (GSAP API, Lottie, Three.js, etc.) gehe zu hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Root-Formen (nicht austauschbar)
- Eigenständig (Top-Level
index.html): Root<div data-composition-id="…">direkt im<body>, kein<template>-Wrapper. Das Umwickeln einer eigenständigen Root versteckt den gesamten Inhalt undlintlehnt es ab (standalone_composition_wrapped_in_template, Fehler). - Sub-Komposition (geladen via
data-composition-src): Wickle die Root in<template>. Dies ist die zu schreibende Form: der Loader akzeptiert auch ein reines vollständiges Dokument und fällt auf dessen<body>zurück, aber die getemplatete Form wird von den Beispielen und Tools erwartet.
⚠ Transportregel: Bei einer getemplateten Sub-Komposition verwirft der Assembler die eigenen
<head>-<style>/<script>des Compilers (packages/core/src/compiler/compositionAssembly.ts, dashasTemplate-Gate). Platziere daher<style>/<script>innerhalb des Templates.<link>wird in beiden Fällen nach oben gehievt. ⚠ 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 die erste Root in der Datei zurück), aber die Diskrepanz ist still, also stimme sie überein, es sei denn, du hast einen Grund dagegen.
Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.
Root muss dimensioniert sein (stiller Layout-Bug)
Die eigenständige Root setzt width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit drückt diese Pixel auf die Kompositions-Root. Harte 1920px/1080px nicht auf #root setzen. 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). Der Aufbau innerhalb eines asynchronen Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass du erst registrierst, nachdem der Aufbau abgeschlossen ist. Die Renderlänge ist die Root data-duration, nicht die Timeline-Länge: eine Timeline, die darüber hinausläuft, wird abgeschnitten, und eine, die vorzeitig endet, hält ihren letzten Frame. Fehlt die Root data-duration, wird die Länge stattdessen inferiert (Timeline, Media-Fenster oder Adapter). Du brauchst kein window.__timelines = window.__timelines || {}: die Laufzeit erstellt das Register, bevor deine Inline-Skripte laufen, und lint verlangt es nicht mehr. Verschachtle keine Sub-Timelines manuell im Host; die Laufzeit verschachtelt registrierte Child-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
First-Pass-Lint-Fallen (garantierter erster Build-Fehler)
Regeln, die lint doch abfängt, aber erst im Nachhinein. Schreibe sie gleich richtig:
- Kombiniere niemals eine CSS-Initiale
transformmit einem GSAP-Tween auf derselben Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen undlintlehnt es ab mitgsap_css_transform_conflict. Setze den Anfangszustand innerhalb des Tweens mitgsap.fromTo(el, { x: -40 }, { x: 0 })anstelle einer CSStransform: translateX(-40px). - Setze
crossoriginniemals auf<video>/<audio>.lintlehnt es bedingungslos ab mitmedia_crossorigin_breaks_preview(Fehler), auch für Canvas/WebGL/WebAudio-Rücklesungen. Es gibt keine Unterdrückung. - Gib einem
<video data-start>niemals einen Vorfahren, der ebenfallsdata-startträgt.lintlehnt es ab mitvideo_nested_in_timed_element(Fehler). Zeite den Wrapper oder das Video, nicht beides. - Jedes
<audio>benötigt eineid.lintlehnt es ab mitmedia_missing_id, und ein<audio>ohne ID wird nie vom Mixer erfasst, der Render ist also stumm. - Tweene niemals einen
.clipmitautoAlphaodervisibility–lintlehnt es ab mitgsap_animates_clip_element. Animiere stattdessen ein Kind. - Ein benanntes CSS
font-familybenötigt ein@font-facein der Datei zu einer mitgelieferten lokalen Datei, sonst feuertlintfont_family_without_font_face. #rootder Sub-Komposition verwendetwidth/height: 100%(oderinset: 0), nicht hartcodierte1920px/1080px. Die Leinwandgröße istdata-width/data-height.
Ein lint-Fehler 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.
Unverhandelbare Regeln (stille Bugs, die automatisierte Gates übersehen können)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Laufzeit-Uhren / ungesäter
Math.random/ Netzwerk / Eingabezustand; keinrepeat: -1(endliche Anzahl verwenden). →determinism-rules.md - Tweene niemals
display,visibilityoderautoAlphaauf einem.clip-Element. Das Framework besitzt die Clip-Sichtbarkeit, undlintlehnt es ab (gsap_animates_clip_element). Animiere stattdessen ein Kind. →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>werden durch eine flache Dokumentabfrage gefunden, das Framework sucht und dekodiert sie in jeder Verschachtelungstiefe (auch innerhalb eines Sub-Komp-<template>oder Wrappers). Eine harte Grenze:lintmeldet einen Fehler, 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 auf den Wrapper oder auf das Video, niemals auf beide. Sub-Kompositions-Hosts sind ausgenommen: Medien innerhalb einer Sub-Komposition rendern korrekt. Die andere Einschränkung betrifft Timelines, nicht die Platzierung: eine Sub-Komp-Timeline kann keine Host-Root-Elemente animieren. →variables-and-media.md- Halte jede
idüber die assemblierte Seite hinweg eindeutig (präfixiere Sub-Komp-IDs mit der Kompositions-ID,#<id>-hero), damit deine eigenen#id-CSS- undgetElementById-Aufrufe funktionieren. Frame-Injektion hängt nicht mehr davon ab: der Compiler drückt 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 weiterhin wichtig. →composition-patterns.md - Eine Vollbild-Füllung auf der Kompositions-Root ist bei einem normalen Render in Ordnung. Sie wird nur auf dem Layered-Composite-Pfad (HDR-Inhalt oder eine Komposition mit Shader-Übergängen) fallengelassen, wo die Engine jede Kompositions-Root transparent macht, damit die darunterliegende Ebene durchscheint. Wenn deine Komposition Shader-Übergänge oder HDR-Medien verwendet, platziere die Füllung auf einem vollflächigen Child (
position:absolute; inset:0). →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lese zuerst die Dateien. Behalte nicht verwandtes Timing, Tracks, IDs, Variablen, Medienpfade bei.
- Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Tracks, Clips, Starts, Enden, was läuft), führe
npx hyperframes timeline [--json]aus, anstattindex.htmlund jede Sub-Kompositionsdatei zu lesen. - Stimme vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
- Hinzufügen eines Clips: setze sein
data-start/data-durationbewusst gegen die umliegenden Clips.data-track-indexist eine Studio-Anzeigespalte, keine Timing-Einschränkung, muss also nicht frei sein. data-hiddenauf jedem 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 im Studio umgeschaltet.- 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 checkbesteht (0 Befunde über Lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Frame begutachten -
npx hyperframes preview --backgroundfür die Überprüfung (der Benutzer kann alles in der Studio-Timeline bearbeiten, und der Server überlebt den aufrufenden Befehl) -
npx hyperframes rendererst nach Zustimmung des Benutzers