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-read-first — 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), and routes every "make me a video" request to the right workflow. Read it first, especially when there's no project context to orient you. The video workflows it routes to:

/product-launch-video — a product URL or brief / script → 60-90s product launch / SaaS / promo video.
/website-to-video — a general website / URL → a video of the site (tour / showcase / social clip from captured visuals); a product launch / promo is /product-launch-video.
/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.
/graphic-overlays — 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.
/general-video — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition); 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-creative, /hyperframes-cli, /hyperframes-media, /hyperframes-registry) and the full capability map live inside /hyperframes-read-first — 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.

Skills not available? Ask the user to run npx hyperframes skills and restart their
agent session, or install manually: npx skills add heygen-com/hyperframes.

Commands

npm run dev          # start the preview server (long-running — keep it alive in background)
npm run check        # lint + validate + inspect
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.

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. Inspect warnings should be reviewed before rendering.

Key Rules

Every timed element needs data-start, data-duration, and data-track-index
Elements with timing MUST have class="clip" — the framework uses this for visibility control
Timelines must be paused and registered on window.__timelines:
js window.__timelines = window.__timelines || {}; window.__timelines["composition-id"] = gsap.timeline({ paused: true });
Videos use muted with a separate <audio> element for the audio track
Sub-compositions use data-composition-src="compositions/file.html" to reference other HTML files
Only deterministic logic — no Date.now(), no Math.random(), no network fetches