HyperFrames Core – Kompositionsvertrag (saas-launch-video-kit)

Plugin-Installation: Führen Sie vor Setup- oder Freshness-Befehlen die Plugin-Ausführungsregeln aus, wenn dieser Skill innerhalb eines HyperFrames-Plugins installiert ist. Bei eigenständigen Installationen behalten Sie die Update-Anweisungen unten bei.

HyperFrames Kern

Agent-Fallstricke (zuerst lesen):

• Zentrieren Sie mit Flex/inset, nicht mit CSS transform: translate(-50%,-50%) auf einem Knoten, den Sie dann per GSAP x/y animieren. Lint: gsap_css_transform_conflict. Verwenden Sie fromTo oder xPercent/yPercent.
• Fügen Sie keinen Szenen-Exit tl.set(..., {visibility:"hidden"}) hinzu. Die Laufzeit blendet getaktete Clips bereits aus. Opazitäts-Übergänge auf inneren Knoten (oder opacity auf .clip) reichen aus. Caption-Hard-Kills folgen einer anderen Regel.
• window.__timelines["id"] muss mit der Wurzel-data-composition-id übereinstimmen.
• Lesen Sie nach dem render-Befehl die zweite Zeile der Zusammenfassung: beginframe vs screenshot, GPU-Modus, Phasen-Timings. screenshot + software gpu auf 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 vom Framework gesteuert wird.

Dieser Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der untenstehende Text ist die Bauanleitung; detaillierte Themen leben in references/ (Index folgt), bei Bedarf lesen. Prozessdokumentation (Brief, Storyboard, Review, Produktion, Dispatch, Frame-Worker) lebt in /hyperframes → references/. Andere Belange leben in den benachbarten Domänen-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes sagt, was jeder abdeckt.

Referenzen

Datei	Lesen Sie sie, um…
references/minimal-composition.md	mit dem kleinsten rendergerechten Kompositionsgerüst 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-* (Wurzel / Clip / Sub-Comp-Host / Legacy-Alias) nachzuschlagen; 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; 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-Bearbeitungsrezepte und deren 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 zu setzen, zu trimmen
references/determinism-rules.md	eine suchbare Timeline zu bauen; Determinismus-Verbote; Layout / Text Fit
references/full-screen-motion.md	Vollbild-Bewegung mit geteilten Hintergründen zu erstellen
references/tailwind.md	in einem Tailwind v4-Projekt zu arbeiten (init --tailwind; der Laufzeitvertrag unterscheidet sich von Studios v3)

Spezifische Animationslaufzeiten (GSAP-API, Lottie, Three.js, etc.) finden Sie unter hyperframes-animation → adapters/<runtime>.md.

Eine Komposition erstellen

Zwei Wurzelformen (nicht austauschbar)

• Standalone (Top-Level index.html): Wurzel <div data-composition-id="…"> sitzt direkt im <body>, kein <template>-Wrapper. Das Einwickeln einer Standalone-Wurzel verbirgt den gesamten Inhalt und lint lehnt es ab (standalone_composition_wrapped_in_template, Fehler).
• Sub-Komposition (geladen via data-composition-src): Wickeln Sie die Wurzel in <template>. Dies ist die zu schreibende Form: der Loader akzeptiert auch ein normales vollständiges Dokument und fällt auf dessen <body> zurück, aber die Template-Form wird von den Beispielen und Tools angenommen.

⚠ Transportregel: Bei einer getemplateten Sub-Komposition verwirft der Assembler die eigenen <head> <style>/<script> der Datei (packages/core/src/compiler/compositionAssembly.ts, das hasTemplate-Gate), also setzen Sie <style>/<script> innerhalb des Templates. <link> wird in beiden Fällen nach oben gezogen. ⚠ Host-ID-Konvention: Geben Sie dem Host-Slot, dem inneren Template und dem window.__timelines["<id>"]-Schlüssel die gleiche ID. Eine andere lokale ID wird unterstützt (der Assembler fällt auf die erste Wurzel in der Datei zurück), aber die Abweichung ist still, also gleichen Sie sie ab, es sei denn, Sie haben einen Grund dagegen.

Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.

Wurzel muss bemessen sein (stiller Layout-Fehler)

Die Standalone-Wurzel erhält width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit prägt diese Pixel auf die Kompositionswurzel. Hartcodieren Sie 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 = Wurzel-data-composition-id). Der Aufbau innerhalb eines asynchronen Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass Sie erst nach Abschluss des Aufbaus registrieren. Die Renderlänge ist die data-duration der Wurzel, nicht die Länge der Timeline: eine Timeline, die darüber hinausläuft, wird abgeschnitten, und eine, die vorzeitig endet, hält ihren letzten Frame. Lassen Sie die Wurzel-data-duration weg, wird die Länge stattdessen abgeleitet (Timeline, Medienfenster oder Adapter). Sie benötigen kein window.__timelines = window.__timelines || {}: die Laufzeit erstellt das Register, bevor Ihre Inline-Skripte ausgeführt werden, und lint fordert es nicht mehr an. Verschachteln Sie keine Sub-Timelines manuell im Host; die Laufzeit verschachtelt registrierte Kind-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.

Lint-Fallstricke beim ersten Durchlauf (garantiert erster Build-Fehler)

Regeln, die lint zwar erkennt, aber erst im Nachhinein. Schreiben Sie sie gleich richtig:

• Kombinieren Sie niemals eine CSS-Initial transform mit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen und lint lehnt es mit gsap_css_transform_conflict ab. Setzen Sie den Ausgangszustand innerhalb des Tweens mit gsap.fromTo(el, { x: -40 }, { x: 0 }) anstelle eines CSS transform: translateX(-40px).
• Setzen Sie niemals crossorigin auf <video>/<audio>. lint lehnt es bedingungslos mit media_crossorigin_breaks_preview (Fehler) ab, auch für Canvas/WebGL/WebAudio-Rücklesung. Es gibt keine Unterdrückung.
• Geben Sie einem <video data-start> niemals einen Vorfahren, der ebenfalls data-start trägt. lint lehnt es mit video_nested_in_timed_element (Fehler) ab. Timen Sie den Wrapper oder das Video, nicht beides.
• Jedes <audio> benötigt eine id. lint lehnt es mit media_missing_id ab, und ein id-loses <audio> wird niemals vom Mixer aufgenommen, sodass der Render stumm ist.
• Tweenen Sie niemals einen .clip mit autoAlpha oder visibility – lint lehnt es mit gsap_animates_clip_element ab. Animieren Sie stattdessen ein Kind.
• Eine benannte CSS font-family benötigt ein @font-face in der Datei zu einer ausgelieferten lokalen Datei, sonst feuert lint font_family_without_font_face.
• Die Sub-Komposition #root verwendet width/height: 100% (oder inset: 0), nicht hartcodiert 1920px/1080px. Die Leinwandgröße ist data-width/data-height.

Ein Lint-Fehler schaltet außerdem 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. Beseitigen Sie Lint-Fehler, bevor Sie diesen Zahlen vertrauen.

Nicht verhandelbare Regeln (stille Fehler, die automatisierte Tore übersehen könnten)

Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:

• Keine Renderzeit-Uhren / nicht gesätes Math.random / Netzwerk / Eingabezustand; kein repeat: -1 (eine endliche Anzahl verwenden). → determinism-rules.md
• Niemals display, visibility oder autoAlpha auf einem .clip-Element tweenen. Das Framework besitzt die Clip-Sichtbarkeit, und lint lehnt es ab (gsap_animates_clip_element). Animieren Sie stattdessen ein Kind. → determinism-rules.md
• Kein <br> im Fließtext; transformierte Elemente müssen block-level + bemessen sein; pulsierende absolute Dekorationen benötigen Spitzenabstand. → determinism-rules.md
• <video>/<audio> werden durch eine flache Dokumentabfrage gefunden, daher sucht und dekodiert das Framework sie in jeder Verschachtelungstiefe (auch innerhalb eines Sub-Komposition <template> oder Wrappers). Eine harte Grenze: lint gibt einen Fehler aus, wenn ein <video data-start> innerhalb eines anderen einfachen Elements mit ebenfalls data-start sitzt, und der Fehler ist echt (falsche Quellframes, dann verschwindet der Clip mitten im Slot). Setzen Sie das Timing also entweder auf den Wrapper oder auf das Video, niemals auf beide. Sub-Komposition-Hosts sind ausgenommen: Medien innerhalb einer Sub-Komposition werden korrekt gerendert. Die andere Einschränkung betrifft Timelines, nicht die Platzierung: eine Sub-Komp-Timeline kann keine Host-Wurzel-Elemente animieren. → variables-and-media.md
• Halten Sie jede id über die montierte Seite hinweg eindeutig (präfixieren Sie Sub-Komp-IDs mit der Kompositions-ID, #<id>-hero), damit Ihre eigenen #id-CSS und getElementById-Aufrufe funktionieren. Frame-Injektion hängt nicht mehr davon ab: der Compiler prägt einen dokumenteindeutigen data-hf-render-id auf jedes video[src]/audio[src]/img[src]. Medien, die <source>-Kinder anstelle eines src-Attributs verwenden, werden nicht gestempelt, daher sind eindeutige IDs dort weiterhin wichtig. → composition-patterns.md
• Eine Vollbild-Füllung auf der Kompositions-Wurzel 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 Kompositionswurzel transparent macht, damit die darunterliegende Schicht durchscheint. Wenn Ihre Komposition Shader-Übergänge oder HDR-Medien verwendet, setzen Sie die Füllung auf ein vollflächiges Kind (position:absolute; inset:0). → composition-patterns.md

Vorhandene Kompositionen bearbeiten

• Lesen Sie zuerst die Dateien. Bewahren Sie unabhängiges Timing, Tracks, IDs, Variablen und Medienpfade.
• Um zu erfahren, was in der Timeline eines Projekts ist (Tracks, Clips, Starts, Enden, was abgespielt wird), führen Sie npx hyperframes timeline [--json] aus, anstatt index.html und jede Sub-Kompositionsdatei zu lesen.
• Gleichen Sie vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
• Hinzufügen eines Clips: setzen Sie sein data-start/data-duration gezielt in Bezug auf die umgebenden Clips. data-track-index ist eine Studio-Anzeigespur, keine Timing-Einschränkung, muss also nicht frei sein.
• Ein Clip, der über die Wurzel-data-duration hinaus endet, wird abgeschnitten: verlängern Sie die Wurzel-data-duration bis zum Ende des Clips im selben Bearbeitungsschritt (lint warnt clip_ends_past_root_duration).
• data-hidden auf einem beliebigen Kompositionselement blendet es SOWOHL in der Vorschau ALS AUCH im Render aus und überschreibt dabei sein Zeitfenster; es ist nicht destruktiv/umkehrbar und wird durch das Timeline-Augen-Symbol von Studio umgeschaltet.
• Hinzufügen einer Sub-Komposition: überprüfen Sie ihre interne data-composition-id, bevor Sie den Host verdrahten.

Validierung

Verwenden Sie hyperframes-cli für Befehlsdetails

• npx hyperframes check besteht (0 Befunde in Lint, Laufzeit, Layout, Bewegung und Kontrast)
• Projekte mit Sub-Kompositionen: npx hyperframes snapshot --at <mitte> und jeden Frame in Augenschein nehmen
• npx hyperframes preview --background zur Überprüfung (der Benutzer kann alles in Studios Timeline bearbeiten, und der Server überlebt den aufrufenden Befehl)
• npx hyperframes render erst nach Zustimmung des Benutzers