Plugin-Installation: Führe vor Setup- oder Frische-Befehlen die Plugin-Installationsregeln aus, wenn dieses Skill innerhalb eines HyperFrames-Plugins verwendet wird. Eigenständige Installationen behalten die untenstehenden Aktualisierungsanweisungen bei.
HyperFrames Core
Agent-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 verbirgt bereits zeitgesteuerte Clips. Opazitäts-Überblendungen auf inneren Knoten (oderopacityauf.clip) sind ausreichend. Caption-Hard-Kills unterliegen einer anderen Regel. window.__timelines["id"]muss mit der rootdata-composition-idübereinstimmen.- Lies nach
renderdie zweite Zeile der Zusammenfassung:beginframevsscreenshot, GPU-Modus, Stage-Timings.screenshot+software gpuauf Linux ist der langsame Pfad.
HyperFrames rendert Videos aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM mit data-*-Attributen das Timing deklariert, deren Animations-Laufzeit suchbar ist und deren Medienwiedergabe vom Framework gesteuert wird.
Dieses Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist die Bauanleitung; Details zu jedem Thema finden sich in references/ (Index unten), bei Bedarf lesen. Prozessdokumente (Briefing, Storyboard, Review, Produktion, Dispatch, Frame-Worker) befinden sich in /hyperframes → references/. Andere Belange leben in den Geschwister-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes zeigt, was jedes Skill abdeckt.
Referenzen
| Datei | Lies sie, um… |
|---|---|
references/minimal-composition.md | mit dem kleinsten renderbaren Kompositions-Skelett zu beginnen |
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-* (root / clip / sub-comp host / legacy Aliase) 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 | wahrheitsgetreue Cut/Trim/Reorder/Retime/Freeze/Kamera/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 und Trim zu setzen |
references/determinism-rules.md | eine suchbare Timeline zu bauen; Determinismus-Verbote; Layout / Text-Fit |
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; der Laufzeitvertrag unterscheidet sich von Studio's v3) |
Für Details zur Animations-Laufzeit (GSAP API, Lottie, Three.js usw.) siehe hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Wurzelformen (nicht austauschbar)
- Standalone (Top-Level
index.html): root<div data-composition-id="…">liegt direkt in<body>, kein<template>-Wrapper. Das Umwickeln einer Standalone-Wurzel verbirgt alle Inhalte undlintlehnt es ab (standalone_composition_wrapped_in_template, Fehler). - Sub-Komposition (geladen via
data-composition-src): Die Wurzel in<template>einwickeln. 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 angenommen.
⚠ 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 gehoben. ⚠ 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 Wurzel in der Datei zurück), aber die Diskrepanz 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.
Wurzel muss dimensioniert sein (stiller Layout-Fehler)
Die Standalone-Wurzel setzt width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit stempelt diese Pixel auf den Kompositions-Root. Hardcodiere nicht 1920px/1080px auf #root. Skelett → references/minimal-composition.md.
Eine angehaltene Timeline
Jede Komposition registriert genau eine gsap.timeline({ paused: true }) bei window.__timelines["<id>"] (Schlüssel = root data-composition-id). Das Erstellen innerhalb eines asynchronen Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass du erst nach Abschluss des Baus registrierst. Die Renderlänge ist das 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. Lass das root data-duration weg, und die Länge wird stattdessen abgeleitet (Timeline, Medienfenster oder Adapter). Du brauchst kein window.__timelines = window.__timelines || {}: Die Laufzeit erstellt das Register, bevor deine Inline-Skripte ausgeführt werden, und lint verlangt es nicht mehr. Verschachtele Sub-Timelines nicht manuell im Host; die Laufzeit verschachtelt registrierte Kind-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.
Linting-Fallstricke beim ersten Durchlauf (garantierter erster Build-Fehler)
Regeln, die lint zwar erkennt, aber erst nachträglich. Schreibe sie gleich richtig:
- Kombiniere niemals ein initiales CSS
transformmit einem GSAP-Tween auf derselben 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 })anstelle eines CSStransform: translateX(-40px). - Setze niemals
crossoriginauf<video>/<audio>.lintlehnt es bedingungslos mitmedia_crossorigin_breaks_preview(Fehler) ab, 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 mitvideo_nested_in_timed_element(Fehler) ab. Timing auf den Wrapper oder das Video, nicht auf beide. - Jedes
<audio>benötigt eineid.lintlehnt es mitmedia_missing_idab, und ein<audio>ohne ID wird vom Mixer nie aufgegriffen, sodass der Render stumm ist. - Tweene niemals einen
.clipmitautoAlphaodervisibility–lintlehnt es mitgsap_animates_clip_elementab. Animierte stattdessen ein Kind-Element. - Eine benannte CSS
font-familybenötigt ein@font-facein der Datei, das auf eine ausgelieferte lokale Datei verweist, oderlintfeuertfont_family_without_font_face. - Sub-Komposition
#rootverwendetwidth/height: 100%(oderinset: 0), nicht hartcodiert1920px/1080px. Die Leinwandgröße istdata-width/data-height.
Ein Lint-Fehler deaktiviert auch die Layout- und Kontrastprüfungen: 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 Fehler, die automatisierte Tore übersehen können)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Renderzeit-Uhren / ungesäter
Math.random/ Netzwerk / Eingabezustand;repeat: -1nur unter einer endlichen rootdata-duration(exportiere Clips darauf – sonst 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). Animierte stattdessen ein Kind-Element. →determinism-rules.md - Kein
<br>im Fließ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 in jeder Verschachtelungstiefe (einschließlich innerhalb eines Sub-Komp<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), setze also 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-Wurzel-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. 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 Komposit-Pfad (HDR-Inhalt oder eine Komposition, die Shader-Übergänge verwendet) entfernt, wo die Engine jeden Kompositions-Root transparent macht, damit die darunterliegende 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, Tracks, IDs, Variablen, Medienpfade.
- Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Tracks, Clips, Start, Ende, was abgespielt wird), 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-durationabsichtlich in Bezug auf die umgebenden Clips.data-track-indexist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss es nicht frei sein. - Ein Clip, der über das root
data-durationhinaus endet, wird abgeschnitten: Erweitere das rootdata-durationbis zum Ende des Clips in derselben Bearbeitung (lintwarntclip_ends_past_root_duration). 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 ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkbestanden (0 Funde bei Lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild anschauen -
npx hyperframes preview --backgroundzur Überprüfung (der Benutzer kann alles in Studio's Timeline bearbeiten, und der Server überlebt den auslösenden Befehl) -
npx hyperframes rendererst nach Freigabe durch den Benutzer