Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

Der HyperFrames-Kompositionsvertrag – erstelle ein renderbares Projekt. Verwende für Kompositionsstruktur, die `data-*`-Timing-Attribute, `class="clip"`, Tracks, Sub-Kompositionen, Variablen, framework-eigene Medienwiedergabe, deterministische Render-Regeln und Validierung. Vor dem Schreiben von Kompositions-HTML lesen.

Was ist hyperframes-instruct?

Das Skill `sandeshrajbhandari/hyperframes-instruct` definiert den technischen Vertrag für die Erstellung von HyperFrames-Kompositionen – renderbare Videoprojekte, die auf HTML basieren. Es beschreibt die grundlegende Architektur, wie Kompositionen mit `data-*`-Attributen Timing deklarieren, wie das Animations-Framework (GSAP) eingebunden wird und wie Medienwiedergabe gesteuert wird. Enthalten sind detaillierte Regeln für die Vermeidung von Fallstricken, wie z. B. Konflikte zwischen CSS-`transform` und GSAP-Tweening, sowie Linting-Regeln für erste Fehler. Das Skill behandelt sowohl Standalone- als auch Sub-Kompositionen, die Struktur von Tracks und Clips, die Verwendung von Variablen und Medien sowie die Determinismus-Regeln für seekbare, reproduzierbare Renderings. Es verweist auf umfangreiche Referenzdokumente für spezifische Themen und unterstützt die Tools der HyperFrames-CLI zur Validierung und zum Vorschaurendering.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sandeshrajbhandari/hyperframes-instruct/tree/HEAD/.agents/skills/hyperframes-core

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 CSS transform: translate(-50%,-50%) auf einem Knoten, den du dann per GSAP x/y animierst. Lint: gsap_css_transform_conflict. Verwende fromTo oder xPercent/yPercent.
  • Füge keinen Szenen-Exit tl.set(..., {visibility:"hidden"}) hinzu. Die Laufzeit verbirgt bereits zeitgesteuerte Clips. Opazitäts-Überblendungen auf inneren Knoten (oder opacity auf .clip) sind ausreichend. Caption-Hard-Kills unterliegen einer anderen Regel.
  • window.__timelines["id"] muss mit der root data-composition-id übereinstimmen.
  • Lies nach render die zweite Zeile der Zusammenfassung: beginframe vs screenshot, GPU-Modus, Stage-Timings. screenshot + software gpu auf 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

DateiLies sie, um…
references/minimal-composition.mdmit dem kleinsten renderbaren Kompositions-Skelett zu beginnen
references/composition-patterns.mdmonolithisch vs. modular zu wählen; ein modulares index.html zu strukturieren; einen Sub-Kompositions-Archetyp auszuwählen
references/data-attributes.mdjedes data-* (root / clip / sub-comp host / legacy Aliase) nachzuschlagen; class="clip" zu verwenden
references/tracks-and-clips.mdzu 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.mdwahrheitsgetreue Cut/Trim/Reorder/Retime/Freeze/Kamera/Mask/Crossfade/Audio-Bearbeitungsrezepte und deren Grenzen zu kopieren
references/sub-compositions.mdeine Sub-Komposition zu verdrahten (Host-Attribute, <template>, Instanz-Variablen) und darin zu animieren
references/variables-and-media.mdVariablen zu deklarieren; <video>/<audio> zu platzieren, Lautstärke und Trim zu setzen
references/determinism-rules.mdeine suchbare Timeline zu bauen; Determinismus-Verbote; Layout / Text-Fit
references/full-screen-motion.mdVollbild-Bewegung mit gemeinsamen Hintergründen zu erstellen
references/tailwind.mdin 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 und lint lehnt 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, das hasTemplate-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 dem window.__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 transform mit einem GSAP-Tween auf derselben Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen, und lint lehnt es mit gsap_css_transform_conflict ab. Setze den Anfangszustand innerhalb des Tweens mit gsap.fromTo(el, { x: -40 }, { x: 0 }) anstelle eines CSS transform: translateX(-40px).
  • Setze niemals crossorigin auf <video>/<audio>. lint lehnt es bedingungslos mit media_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 ebenfalls data-start trägt. lint lehnt es mit video_nested_in_timed_element (Fehler) ab. Timing auf den Wrapper oder das Video, nicht auf beide.
  • Jedes <audio> benötigt eine id. lint lehnt es mit media_missing_id ab, und ein <audio> ohne ID wird vom Mixer nie aufgegriffen, sodass der Render stumm ist.
  • Tweene niemals einen .clip mit autoAlpha oder visibility – lint lehnt es mit gsap_animates_clip_element ab. Animierte stattdessen ein Kind-Element.
  • Eine benannte CSS font-family benötigt ein @font-face in der Datei, das auf eine ausgelieferte lokale Datei verweist, oder lint feuert font_family_without_font_face.
  • 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 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: -1 nur unter einer endlichen root data-duration (exportiere Clips darauf – sonst verwende eine endliche Anzahl). → determinism-rules.md
  • Tweene niemals display, visibility oder autoAlpha auf einem .clip-Element. Das Framework besitzt die Clip-Sichtbarkeit, und lint lehnt 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: lint gibt einen Fehler aus, wenn ein <video data-start> innerhalb eines anderen einfachen Elements sitzt, das ebenfalls data-start hat, 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 und getElementById-Aufrufe funktionieren. Die Frame-Injektion hängt nicht mehr davon ab: Der Compiler stempelt eine dokument-eindeutige 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 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, anstatt index.html und jede Sub-Kompositionsdatei zu lesen.
  • Stimme vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
  • Hinzufügen eines Clips: Setze sein data-start/data-duration absichtlich in Bezug auf die umgebenden Clips. data-track-index ist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss es nicht frei sein.
  • Ein Clip, der über das root data-duration hinaus endet, wird abgeschnitten: Erweitere das root data-duration bis zum Ende des Clips in derselben Bearbeitung (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 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 check bestanden (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 --background zur Überprüfung (der Benutzer kann alles in Studio's Timeline bearbeiten, und der Server überlebt den auslösenden Befehl)
  • npx hyperframes render erst nach Freigabe durch den Benutzer

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

sandeshrajbhandari/hyperframes-instruct

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

sandeshrajbhandari/hyperframes-instruct

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

sandeshrajbhandari/hyperframes-instruct

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

sandeshrajbhandari/hyperframes-instruct

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

sandeshrajbhandari/hyperframes-instruct

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

sandeshrajbhandari/hyperframes-instruct

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

sandeshrajbhandari/hyperframes-instruct

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

sandeshrajbhandari/hyperframes-instruct

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

sandeshrajbhandari/hyperframes-instruct

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

Verwandte Skills