Plugin-Installationen: Bevor du Setup- oder Frische-Befehle ausführst, folge den Plugin-Ausführungsregeln, wenn sich dieser Skill innerhalb eines HyperFrames-Plugins befindet. Eigenständige Installationen behalten die unten stehenden Aktualisierungsanweisungen.
HyperFrames Core
Agenten-Fallstricke (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 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 sind eine andere Regel. window.__timelines["id"]muss mit der rootdata-composition-idübereinstimmen.- Nach
renderlies die 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 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 nachfolgende Text ist der Bauleitfaden; detaillierte Informationen zu den einzelnen Themen finden sich in references/ (Index siehe unten), lies sie bei Bedarf. Prozessdokumente (Briefing, Storyboard, Review, Produktion, Dispatch, Frame-Worker) befinden sich in /hyperframes → references/. Andere Belange werden in den verwandten Bereichs-Skills behandelt: hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes zeigt, was jeder einzelne abdeckt.
Referenzen
| Datei | Lies dies, 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-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, Zeitsteuerung eines Clips relativ zu einem anderen; alle Tracks und Clips mit npx hyperframes timeline aufzulisten |
references/creator-editing-recipes.md | wahre Schnitt-/Trim-/Neuzeit-/Einfrier-/Kamera-/Masken-/Überblendungs-/Audio-Bearbeitungsrezepte und deren Grenzen zu kopieren |
references/sub-compositions.md | eine Subkomposition 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 einzustellen, zu trimmen |
references/determinism-rules.md | eine suchbare Zeitleiste zu erstellen; 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 vom Studio v3) |
Für Details zur Animations-Laufzeit (GSAP API, Lottie, Three.js, etc.) siehe hyperframes-animation → adapters/<runtime>.md.
Erstellen einer Komposition
Zwei Wurzelformen (nicht austauschbar)
- Eigenständig (Top-Level
index.html): root<div data-composition-id="…">sitzt direkt in<body>, kein<template>-Wrapper. Das Einwickeln einer eigenständigen Wurzel verbirgt den gesamten Inhalt undlintlehnt es ab (standalone_composition_wrapped_in_template, Fehler). - Subkomposition (geladen über
data-composition-src): umwickle die Wurzel mit<template>. Dies ist die zu schreibende Form: Der Lader akzeptiert auch ein einfaches vollständiges Dokument und fällt auf dessen<body>zurück, aber die getemplatete Form ist das, was die Beispiele und Werkzeuge annehmen.
⚠ Transportregel: Bei einer getemplateten Subkomposition verwirft der Assembler die eigenen
<head><style>/<script>der Datei (packages/core/src/compiler/compositionAssembly.ts, dashasTemplate-Gate), also platziere<style>/<script>innerhalb des Templates.<link>wird auf jeden Fall 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 Nichtübereinstimmung ist still, also gleiche sie ab, es sei denn, du hast einen Grund dagegen.
Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.
Wurzel muss bemessen sein (stiller Layout-Bug)
Die eigenständige Wurzel setzt width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit drückt diese Pixel auf den Kompositionsstamm. Harte 1920px/1080px auf #root nicht fest codieren. 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). Der Aufbau innerhalb eines asynchronen Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass du erst nach Abschluss des Baus registrierst. Die Renderlänge ist die data-duration der Wurzel, nicht die Länge der Zeitleiste: Eine Zeitleiste, 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 abgeleitet (Zeitleiste, 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 keine Sub-Zeitleisten 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-Fallstricke beim ersten Durchlauf (ein garantierter erster Build-Fehler)
Regeln, die lint wohl abfängt, aber erst im Nachhinein. Schreibe sie gleich beim ersten Mal richtig:
- Kombiniere niemals eine anfängliche CSS
transformmit einem GSAP-Tween auf derselben Eigenschaft – der CSS-Wert und der Tween-Start bekämpfen sich, undlintlehnt es mitgsap_css_transform_conflictab. Setze den Anfangszustand innerhalb des Tweens mitgsap.fromTo(el, { x: -40 }, { x: 0 })anstelle einer CSStransform: translateX(-40px). - Setze niemals
crossoriginauf<video>/<audio>.lintlehnt es bedingungslos mitmedia_crossorigin_breaks_preview(Fehler) ab, auch für Canvas/WebGL/WebAudio-Rücklesevorgänge. 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 Mischer nie aufgenommen, sodass der Render stumm ist. - Tweene niemals einen
.clipmitautoAlphaodervisibility–lintlehnt es mitgsap_animates_clip_elementab. Animieren stattdessen ein Kindelement. - Eine benannte CSS
font-familybenötigt ein@font-facein der Datei zu einer ausgelieferten lokalen Datei, oderlintfeuertfont_family_without_font_face. - Die Subkomposition
#rootverwendetwidth/height: 100%(oderinset: 0), nicht hart codierte1920px/1080px. Die Leinwandgröße istdata-width/data-height.
Ein Lint-Fehler schaltet auch die Layout- und Kontrastprüfungen ab: check meldet dann 0 sample(s) und 0/0 text checks, was wie eine saubere Datei aussieht, aber bedeutet, dass nichts ausgeführt wurde. Behebe Lint-Fehler, bevor du diesen Zahlen vertraust.
Unverhandelbare Regeln (stille Bugs, die automatisierte Gates übersehen könnten)
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 – ansonsten verwende eine endliche Anzahl). →determinism-rules.md - Niemals
display,visibilityoderautoAlphaauf einem.clip-Element tweenen. Das Framework besitzt die Clip-Sichtbarkeit, undlintlehnt es ab (gsap_animates_clip_element). Animiere stattdessen ein Kindelement. →determinism-rules.md - Keine
<br>im Fließtext; transformierte Elemente müssen blockeben + bemessen sein; pulsierende absolute Dekorationselemente benötigen Spitzenfreiheit. →determinism-rules.md <video>/<audio>werden durch eine flache Dokumentenabfrage gefunden, daher sucht das Framework sie und dekodiert sie in jeder Verschachtelungstiefe (auch innerhalb eines Sub-Komp<template>oder Wrappers). Eine harte Grenze:lintgibt einen Fehler aus, wenn ein<video data-start>innerhalb eines anderen normalen 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 auf beide. Sub-Kompositions-Hosts sind ausgenommen: Medien innerhalb einer Subkomposition werden korrekt gerendert. Die andere Einschränkung betrifft Zeitleisten, nicht die Platzierung: Eine Sub-Komp-Zeitleiste 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. Frame-Injektion 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 Vollbild-Füllung auf dem Kompositions-stamm ist bei einem normalen Render in Ordnung. Sie wird nur beim geschichteten Komposit-Pfad (HDR-Inhalt oder eine Komposition mit Shader-Übergängen) entfernt, wo die Engine jede Kompositionswurzel 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
Bearbeiten vorhandener Kompositionen
- 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 Sub-Kompositionsdatei zu lesen. - Gleiche vorhandene Kompositions-IDs und Zeitleistenschlüssel ab.
- Hinzufügen eines Clips: Setze seine
data-start/data-durationabsichtlich in Bezug auf die umgebenden Clips.data-track-indexist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss sie nicht frei sein. - Ein Clip, der nach der root
data-durationendet, wird abgeschnitten: Verlängere die 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 Zeitleisten-Augen-Symbol von Studio umgeschaltet.- Hinzufügen einer Subkomposition: Überprüfe ihre interne
data-composition-id, bevor du den Host verdrahtest.
Validierung
Verwende hyperframes-cli für Befehlsdetails
-
npx hyperframes checkbestanden (0 Befunde bei Lint, Laufzeit, Layout, Bewegung und Kontrast) - Projekte mit Subkompositionen:
npx hyperframes snapshot --at <midpoints>und jeden Frame in Augenschein nehmen -
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 Zustimmung des Benutzers