Plugin-Installation: Bevor Setup- oder Aktualisierungsbefehle ausgeführt werden, befolge die Plugin-Installationsregeln, wenn sich diese Skill innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die untenstehenden Aktualisierungshinweise.
HyperFrames Core
Agent-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 Laufzeitumgebung blendet zeitgesteuerte Clips bereits aus. Deckkraft-Überblendungen auf inneren Knoten (oderopacityauf.clip) sind ausreichend. Caption-Hard-Kills unterliegen einer anderen Regel. window.__timelines["id"]muss mit der Wurzel-data-composition-idübereinstimmen.- Nach dem
renderlies die zweite Zeile der Zusammenfassung:beginframevsscreenshot, GPU-Modus, Stage-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 Animations-Laufzeitumgebung durchsuchbar ist und deren Medienwiedergabe dem Framework gehört.
Diese Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Bauleitfaden; detaillierte Informationen zu den einzelnen Themen befinden sich in references/ (siehe Index unten), bei Bedarf lesen. Prozessdokumente (Briefing, Storyboard, Review, Produktion, Dispatch, Frame-Worker) befinden sich in /hyperframes → references/. Andere Belange befinden sich in den benachbarten Domain-Skills – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitskarte in /hyperframes zeigt, was jeder Bereich abdeckt.
Referenzen
| Datei | Lies sie, um… |
|---|---|
references/minimal-composition.md | mit dem kleinstmöglichen renderbaren Kompositionsskelett 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 was nicht), 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 einzurichten (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 durchsuchbare Timeline zu erstellen; Determiniertheitsverbote; 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 Studio v3) |
Informationen zu den Besonderheiten der Animations-Laufzeitumgebungen (GSAP-API, Lottie, Three.js usw.) findest du unter hyperframes-animation → adapters/<runtime>.md.
Eine Komposition erstellen
Zwei Wurzelformen (nicht austauschbar)
- Eigenständig (top-level
index.html): Die Wurzel<div data-composition-id="…">befindet sich direkt im<body>, kein<template>-Wrapper. Wenn eine eigenständige Wurzel umschlossen wird, werden alle Inhalte ausgeblendet, undlintlehnt dies ab (standalone_composition_wrapped_in_template, error). - Sub-Komposition (geladen über
data-composition-src): Umschließe die Wurzel mit<template>. Dies ist die zu schreibende Form: Der Loader akzeptiert auch ein vollständiges Dokument und greibt auf seinen<body>zurück, aber die Vorlagenform wird in den Beispielen und Tools vorausgesetzt.
⚠ Transportregel: Bei einer vorlagenbasierten Sub-Komposition verwirft der Assembler die eigenen
<head><style>/<script>-Elemente der Datei (packages/core/src/compiler/compositionAssembly.ts, derhasTemplate-Gate), also platziere<style>/<script>innerhalb des Templates.<link>wird in beiden Fällen nach oben gezogen. ⚠ 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 greift auf die erste Wurzel in der Datei zurück), aber die Abweichung ist still, also verwende identische IDs, 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 eigenständige Wurzel verwendet width/height: 100%. Die Leinwandgröße wird durch data-width/data-height bestimmt. Die Laufzeitumgebung überträgt diese Pixel auf den Kompositionsstamm. Hardcodiere nicht 1920px/1080px auf #root. Gerüst → references/minimal-composition.md.
Eine pausierte 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 der Erstellung registrierst. Die Renderlänge ergibt sich aus der data-duration der Wurzel, nicht aus der Länge der Timeline: Eine Timeline, die darüber hinausläuft, wird abgeschnitten, und eine, die vorzeitig endet, behält ihren letzten Frame. Wenn die data-duration der Wurzel weggelassen wird, wird die Länge stattdessen abgeleitet (Timeline, Medienfenster oder Adapter). Du benötigst window.__timelines = window.__timelines || {} nicht: Die Laufzeitumgebung erstellt das Register, bevor deine Inline-Skripte ausgeführt werden, und lint verlangt es nicht mehr. Verschachtele Sub-Timelines nicht manuell in den Host; die Laufzeitumgebung verschachtelt registrierte Child-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeitumgebungen) → references/determinism-rules.md + hyperframes-animation/adapters/.
First-Pass-Lint-Fallen (garantierter erster Build-Fehler)
Regeln, die lint zwar abfängt, aber erst im Nachhinein. Schreibe sie gleich richtig:
- Kombiniere niemals einen initialen CSS-
transformmit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen gegeneinander, 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(error) ab, auch für Canvas/WebGL/WebAudio-Rücklese. Es gibt keine Unterdrückung. - Gib einem
<video data-start>niemals einen Vorfahren, der ebenfallsdata-startträgt.lintlehnt es mitvideo_nested_in_timed_element(error) ab. Time den Wrapper oder das Video, nicht beides. - Jedes
<audio>benötigt eineid.lintlehnt es mitmedia_missing_idab, und ein<audio>ohne ID wird vom Mischer nie erfasst, daher ist der Render stumm. - Tweene niemals einen
.clipmitautoAlphaodervisibility–lintlehnt es mitgsap_animates_clip_elementab. Animierte stattdessen ein Kindelement. - Ein benannter CSS-
font-familybenötigt einen@font-facein der Datei, der auf eine ausgelieferte lokale Datei verweist, sonst wirdfont_family_without_font_faceausgelöst. - Sub-Komposition
#rootverwendetwidth/height: 100%(oderinset: 0), nicht hartcodierte1920px/1080px. Die Leinwandgröße istdata-width/data-height.
Ein Lint-Error 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. Behebe Lint-Fehler, bevor du diesen Zahlen vertraust.
Unverhandelbare Regeln (stille Fehler, die automatisierte Gates übersehen können)
Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:
- Keine Laufzeituhren / ungesähtes
Math.random/ Netzwerk / Eingabezustand;repeat: -1nur unter einer endlichen Wurzel-data-duration(exportiere Clips darauf – andernfalls verwende eine endliche Anzahl). →determinism-rules.md - Tweene niemals
display,visibilityoderautoAlphaauf einem.clip-Element. Das Framework verwaltet die Clip-Sichtbarkeit, undlintlehnt es ab (gsap_animates_clip_element). Animierte stattdessen ein Kindelement. →determinism-rules.md - Keine
<br>im Fließtext; transformierte Elemente müssen blockartig + dimensioniert sein; pulsierende absolute Dekorationselemente benötigen Spitzenfreiheit. →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-Kompositions-<template>oder Wrappers). Eine harte Grenze:lintmeldet einen Fehler, wenn ein<video data-start>innerhalb eines anderen einfachen Elements mit ebenfallsdata-startsitzt, und der Fehler ist real (falsche Quellframes, dann verschwindet der Clip mitten im Slot), also platziere das Timing auf dem Wrapper oder auf dem Video, niemals auf beiden. Sub-Kompositions-Hosts sind ausgenommen: Medien in einer Sub-Komposition werden korrekt gerendert. Die andere Einschränkung betrifft Timelines, nicht die Platzierung: Eine Sub-Kompositions-Timeline kann keine Host-Wurzel-Elemente animieren. →variables-and-media.md- Halte jede
idüber die assemblierte Seite hinweg eindeutig (präfixiere Sub-Kompositions-IDs mit der Kompositions-ID,#<id>-hero), damit deine eigenen#id-CSS- undgetElementById-Aufrufe auflösen. Die 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 weiterhin wichtig. →composition-patterns.md - Eine Vollbildfüllung auf dem Kompositions-stamm ist bei einem normalen Render in Ordnung. Sie wird nur auf dem geschichteten Composite-Pfad (HDR-Inhalt oder eine Komposition mit Shader-Übergängen) entfernt, wo die Engine jeden Kompositionsstamm 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 die Dateien zuerst. Erhalte nicht verwandte Timings, 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. - Verwende bestehende Kompositions-IDs und Timeline-Schlüssel.
- Einen Clip hinzufügen: Setze sein
data-start/data-durationabsichtlich in Bezug auf die umliegenden Clips.data-track-indexist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss sie nicht frei sein. - Ein Clip, der nach der Wurzel-
data-durationendet, wird abgeschnitten: Erweitere die Wurzel-data-durationbis zum Ende des Clips in derselben Bearbeitung (lintwarntclip_ends_past_root_duration). data-hiddenauf einem 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.- Eine Sub-Komposition hinzufügen: Ü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 Sub-Kompositionen:
npx hyperframes snapshot --at <midpoints>und jedes Bild überprüfen -
npx hyperframes preview --backgroundzur Ü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