Imported from zhou-zhichao/typhoon-visualizations (projects/typhoon-name-evolution/AGENTS.md). Install upstream with npx skills add zhou-zhichao/typhoon-visualizations --skill typhoon-name-evolution. 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, or video to pull audio from) → 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.

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