Imported from mdshoebkhanking/cutsteward (videos/framepilot-launch-demo/AGENTS.md). Install upstream with npx skills add mdshoebkhanking/cutsteward --skill framepilot-launch-demo. Copyright stays with the author.

HyperFrames Composition Project

Skills — USE THESE FIRST

Always invoke the relevant skill before writing or modifying compositions. Skills encode framework-specific patterns (e.g., window.__timelines registration, data-* attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.

Doing anything with HyperFrames? Start at /hyperframes — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), confirms your brief up front (the intent layer), and routes every "make me a…" request (a video, a deck, a composition port) to the right workflow. Read it first, especially when there's no project context to orient you. The workflows it routes to:

• /product-launch-video — any website URL or brief / script → a product launch / SaaS / promo video, or a site tour / showcase featuring the site's own captured visuals.
• /faceless-explainer — arbitrary text (topic / article / notes), no URL, no website capture → 60-90s faceless explainer.
• /embedded-captions — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched.
• /talking-head-recut — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed graphic overlays (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → /embedded-captions.)
• /pr-to-video — a GitHub PR (URL / owner/repo#N / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor).
• /motion-graphics — a short (typically under 10s) design-led motion graphic, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → /general-video.
• /music-to-video — a music track (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
• /slideshow — a presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
• /general-video — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of companion mode — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length.

Porting an existing composition? /remotion-to-hyperframes translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above.

The domain skills (/hyperframes-core, /hyperframes-animation, /hyperframes-keyframes, /hyperframes-creative, /hyperframes-cli, /media-use, /hyperframes-registry, /figma) and the full capability map live inside /hyperframes — it is the single source of truth for which skill handles which intent.

Changing how real footage or images look or reveal? Load /media-use and read its references/media-treatments.md before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays.

Tailwind v4 projects (hyperframes init --tailwind): see /hyperframes-core → references/tailwind.md.

Skill missing or stale? Run npx hyperframes skills update <name> to install/refresh the specific skill you need (the /hyperframes router does this automatically before entering a workflow), or bare npx hyperframes skills update to refresh the core set plus everything already installed — neither pulls the full set. Restart the agent session so newly installed skills load.

Commands

npm run dev          # start the preview server (long-running — keep it alive in background)
npm run check        # lint + runtime + layout + motion + contrast (one command)
npm run render       # render to MP4
npm run publish      # publish and get a shareable link
npx hyperframes lint --verbose  # include info-level findings
npx hyperframes lint --json     # machine-readable output for CI
npx hyperframes docs <topic> # reference docs in terminal

npm run dev is a long-running server, not a one-shot command. It blocks until stopped. In Claude Code, always run it with run_in_background: true. Never run it as a foreground command — it will time out and the server will die, breaking the browser preview.

Pinned CLI version. These scripts pin an exact hyperframes@X.Y.Z so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: npx hyperframes@latest upgrade --project . --check (shows the delta), then npx hyperframes@latest upgrade --project . to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself.

Documentation

For quick reference, use the local CLI docs command (no network required):

npx hyperframes docs <topic>

Topics: data-attributes, gsap, compositions, rendering, examples, troubleshooting

For full documentation, discover pages via the machine-readable index — do NOT guess URLs:

https://hyperframes.heygen.com/llms.txt

Project Structure

• index.html — main composition (root timeline)
• compositions/ — sub-compositions referenced via data-composition-src
• meta.json — project metadata (id, name)
• transcript.json — whisper word-level transcript (if generated)

Linting — ALWAYS RUN AFTER CHANGES

After creating or editing any .html composition, always run the full check before considering the task complete:

npm run check

Fix all errors before presenting the result. Warnings should be reviewed before rendering.

Key Rules

1. Every timed element needs data-start, data-duration, and data-track-index
2. Elements with timing MUST have class="clip" — the framework uses this for visibility control
3. Timelines must be paused and registered on window.__timelines:

   window.__timelines = window.__timelines || {};
   window.__timelines["composition-id"] = gsap.timeline({ paused: true });

4. Videos use muted with a separate <audio> element for the audio track
5. Sub-compositions use data-composition-src="compositions/file.html" to reference other HTML files
6. Only deterministic logic — no Date.now(), no Math.random(), no network fetches