Plugin-Installation: Vor Setup- oder Frische-Befehlen befolge die Plugin-Ausführungsregeln, wenn sich dieser Skill innerhalb eines HyperFrames-Plugins befindet. Standalone-Installationen behalten die Aktualisierungsanweisungen unten bei.
HyperFrames Core
Agent-Fallen (zuerst lesen):
- Zentriere mit flex/
inset, nicht mit CSStransform: translate(-50%,-50%)auf einem Knoten, den du dann mit 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-Fade auf inneren Knoten (oderopacityauf.clip) sind ausreichend. Caption-Hard-Kills unterliegen einer anderen Regel. window.__timelines["id"]muss mit dem Root-data-composition-idübereinstimmen.- Lies nach
renderdie zweite Zeile der Zusammenfassung:beginframevsscreenshot, GPU-Modus, Bühnen-Timings.screenshot+software gpuauf 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 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; Details zu jedem Thema leben in references/ (Index als nächstes), lies bei Bedarf. Prozessdokumente (Brief, Storyboard, Review, Produktion, Dispatch, Frame-Arbeiter) befinden sich in /hyperframes → references/. Andere Belange leben in den verwandten Bereichs-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes sagt, was jeder abdeckt.
Referenzen
| Datei | Lies es, um… |
|---|---|
references/minimal-composition.md | mit dem kleinstmöglichen renderbaren Kompositionsgerüst zu beginnen |
references/composition-patterns.md | monolithisch vs. modular zu wählen; eine modulare index.html zu strukturieren; einen Sub-Comp-Architekturtyp zu wählen |
references/data-attributes.md | jedes data-* nachzuschlagen (Root / Clip / Sub-Comp-Host / Legacy-Aliase); class="clip" zu verwenden |
references/tracks-and-clips.md | zu verstehen, was data-track-index steuert (und nicht steuert), z-index, einen Clip relativ zu einem anderen zu timen; alle Spuren und Clips mit npx hyperframes timeline aufzulisten |
references/creator-editing-recipes.md | wahrheitsgemäße Cut/Trim/Reorder/Retime/Freeze/Camera/Mask/Crossfade/Audio-Bearbeitungsrezepte und ihre Grenzen zu kopieren |
references/sub-compositions.md | eine Unterkomposition zu verdrahten (Host-Attribute, <template>, Instanzvariablen) 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 bauen; Determinismus-Verbote; Layout / Textanpassung |
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 Studys v3) |
Für Einzelheiten zur Animationslaufzeit (GSAP API, Lottie, Three.js, usw.) gehe zu hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Root-Formen (nicht austauschbar)
- Standalone (top-level
index.html): Root<div data-composition-id="…">sitzt direkt im<body>, kein<template>Wrapper. Das Umwickeln eines standalone-Roots versteckt alle Inhalte undlintlehnt es ab (standalone_composition_wrapped_in_template, Fehler). - Unterkomposition (geladen via
data-composition-src): Wickle den Root in<template>. Dies ist die zu schreibende Form: Der Loader akzeptiert auch ein einfaches vollständiges Dokument und fällt auf dessen<body>zurück, aber die Template-Form wird von den Beispielen und Werkzeugen vorausgesetzt.
⚠ Transportregel: Bei einer getemplateten Unterkomposition verwirft der Assembler die eigene
<head><style>/<script>der Datei (packages/core/src/compiler/compositionAssembly.ts, dashasTemplate-Gate), also setze<style>/<script>innerhalb des Templates.<link>wird in beiden Fällen nach oben gehoben. ⚠ Host-ID-Konvention: Gib dem Host-Slot, dem inneren Template und demwindow.__timelines["<id>"]-Schlüssel die gleiche ID. Eine andere lokale ID wird unterstützt (der Assembler fällt auf den ersten Root in der Datei zurück), aber die Nichtübereinstimmung ist still, also stimme sie ab, 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-Fehler)
Der standalone-Root setzt width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit stempelt diese Pixel auf den Kompositions-Root. Hartcodiere nicht 1920px/1080px auf #root. Skelett → 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). Das Erstellen innerhalb eines async-Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass du erst nach Abschluss der Erstellung registrierst. Die Renderlänge ist die data-duration des Roots, nicht die Länge der Zeitleiste: Eine Zeitleiste, die darüber hinausläuft, wird abgeschnitten, und eine, die früh endet, hält ihren letzten Frame. Fehlt die Root data-duration, wird die Länge stattdessen abgeleitet (Zeitleiste, Medienfenster oder Adapter). Du brauchst kein window.__timelines = window.__timelines || {}: Die Laufzeit erstellt das Register, bevor deine Inline-Skripte laufen, und lint fragt nicht mehr danach. Verschachtele keine Unterzeitleisten manuell im Host; die Laufzeit verschachtelt registrierte Kind-Zeitleisten 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 doch erkennt, aber erst im Nachhinein. Schreibe sie gleich richtig:
- Kombiniere niemals eine anfängliche CSS
transformmit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen undlintlehnt es mitgsap_css_transform_conflictab. Setze den Anfangszustand innerhalb des Tweens mitgsap.fromTo(el, { x: -40 }, { x: 0 })anstatt mit einer CSStransform: translateX(-40px). - Setze niemals
crossoriginauf<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 niemals einem
<video data-start>einen Vorfahren, der ebenfallsdata-startträgt.lintlehnt es mitvideo_nested_in_timed_element(Fehler) ab. Time den Wrapper oder das Video, niemals beide. - Jedes
<audio>benötigt eineid.lintlehnt es mitmedia_missing_idab, und einid-loses<audio>wird nie vom Mixer aufgenommen, daher ist der Render stumm. - Tweene niemals einen
.clipmitautoAlphaodervisibility–lintlehnt es mitgsap_animates_clip_elementab. Animiere stattdessen ein Kind. - Ein benanntes CSS
font-familybenötigt ein@font-facein der Datei für eine ausgelieferte lokale Datei, sonst feuertlintfont_family_without_font_face. - Unterkompositions-
#rootverwendetwidth/height: 100%(oderinset: 0), nicht fest codiertes1920px/1080px. Die Leinwandgröße istdata-width/data-height.
Ein Lint-Fehler schaltet auch die Layout- und Kontrastprüfungen aus: check meldet dann 0 sample(s) und 0/0 text checks, was wie eine saubere Datei aussieht, aber bedeutet, dass nichts gelaufen ist. Beseitige Lint-Fehler, bevor du diesen Zahlen vertraust.
Unverhandelbare Regeln (stille Fehler, die automatisierte Tore übersehen könnten)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Verstoße nicht:
- Keine Renderzeit-Uhren / ungesätes
Math.random/ Netzwerk / Eingabe-Zustand;repeat: -1nur unter einer endlichen Rootdata-duration(exportiere Clips darauf – ansonsten verwende eine endliche Anzahl). →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 - Keine
<br>im Text; transformierte Elemente müssen block-level + dimensioniert sein; pulsierende absolute Dekorationen benötigen Spitzenfreiheit. →determinism-rules.md <video>/<audio>werden durch eine flache Dokumentabfrage gefunden, daher sucht und dekodiert das Framework sie auf jeder Verschachtelungstiefe (auch innerhalb eines Sub-Comp<template>oder Wrappers). Eine harte Grenze:lintgibt einen Fehler aus, wenn ein<video data-start>innerhalb eines anderen einfachen Elements sitzt, das ebenfallsdata-starthat, und der Fehler ist real (falsche Quellframes, dann verschwindet der Clip mitten im Slot), also setze das Timing auf den Wrapper oder auf das Video, niemals beide. Sub-Comp-Hosts sind ausgenommen: Medien innerhalb einer Unterkomposition werden korrekt gerendert. Die andere Einschränkung betrifft Zeitleisten, nicht die Platzierung: Eine Sub-Comp-Zeitleiste kann keine Host-Root-Elemente animieren. →variables-and-media.md- Halte jede
idauf der assemblierten Seite eindeutig (präfixiere Sub-Comp-IDs mit der Kompositions-ID,#<id>-hero), damit deine eigenen#idCSS- undgetElementById-Aufrufe funktionieren. Die Frame-Injektion hängt nicht mehr davon ab: Der Compiler stempelt eine dokument-eindeutigedata-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 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) verworfen, wo die Engine jede Kompositions-Root transparent macht, damit die darunter liegende Schicht durchscheint. Wenn deine Komposition Shader-Übergänge oder HDR-Medien verwendet, setze die Füllung auf ein vollflächiges Kind (
position:absolute; inset:0). →composition-patterns.md
Vorhandene Kompositionen bearbeiten
- Lies zuerst die Dateien. Bewahre nicht zusammenhängendes Timing, Spuren, IDs, Variablen, Medienpfade.
- Um zu erfahren, was sich auf der Zeitleiste eines Projekts befindet (Spuren, Clips, Starts, Enden, was abgespielt wird), führe
npx hyperframes timeline [--json]aus, anstattindex.htmlund jede Unterkompositionsdatei zu lesen. - Stimme vorhandene Kompositions-IDs und Zeitleistenschlüssel ab.
- Hinzufügen eines Clips: Setze sein
data-start/data-durationabsichtlich gegen die umliegenden Clips.data-track-indexist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss es nicht frei sein. - Ein Clip, der nach der Root
data-durationendet, wird abgeschnitten: Erweitere die Rootdata-durationbis zum Ende des Clips in derselben Bearbeitung (lintwarntclip_ends_past_root_duration). data-hiddenauf jedem Kompositionselement blendet es sowohl in der Vorschau als auch im Render aus und überschreibt sein Zeitfenster; es ist nicht destruktiv/wiederherstellbar und wird durch das Zeitleisten-Augensymbol in Studio umgeschaltet.- Hinzufügen einer Unterkomposition: Überprüfe ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkbesteht (0 Funde bei Lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Unterkompositionen:
npx hyperframes snapshot --at <midpoints>und jeden Frame überprüfen -
npx hyperframes preview --backgroundzur Überprüfung (der Benutzer kann alles in der Studio-Zeitleiste bearbeiten, und der Server überlebt den aufrufenden Befehl) -
npx hyperframes rendererst nach Genehmigung durch den Benutzer