{"owner":"heygen-com","repo":"hyperframes","hasSkills":true,"totalSkillsCount":17,"totalTokensCount":12830,"categories":["anthropic-skill","root-instruction","claude-rule","mcp-config","marketplace","plugin-manifest","copilot-instructions"],"hasMcp":true,"mcpConfig":{"mcpServers":{"hyperframes":{"command":"npx","args":["-y","@modelcontextprotocol/server-hyperframes"]}}},"found":["skills/hyperframes-cli/SKILL.md","skills/hyperframes/SKILL.md","skills/hyperframes-registry/SKILL.md","AGENTS.md","skills/media-use/SKILL.md","CLAUDE.md","mcp.json","marketplace.json","plugin.json",".github/copilot-instructions.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json","skills/hyperframes/README.md","skills/hyperframes-cli/README.md","skills/hyperframes-registry/README.md","skills/media-use/README.md"],"skills":{"skills/hyperframes-cli/SKILL.md":"---\nname: hyperframes-cli\ndescription: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames CLI\n\nRun `npx hyperframes <command>` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero.\n\n## Commands by job\n\n| Job | Commands |\n| --- | --- |\n| Start | `init <dir>` (blank; `--example <name>` only when asked), `capture <url>` |\n| Read a project | `info`, `compositions`, `timeline --json`, `docs <topic>` |\n| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) |\n| Look at it | `snapshot` (`--at <t,…>`, `--range START,END`, `--composition <id>`, `--zoom`, `--angle`, `--against <video>`), `keyframes`, `compare`, `audio` |\n| Edit the timeline | `timeline` with `move`, `trim`, `split`, `set`, `duplicate`, `delete`, `apply`, `undo`, `ids` |\n| Reuse | `catalog`, `add` (`/hyperframes-registry`) |\n| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |\n| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |\n| Desktop app | `open`, `catch-up` |\n| Upkeep | `doctor`, `browser`, `upgrade`, `skills`, `usage`, `clean`, `feedback` |\n\n`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.\n\n## The loop\n\n1. Write, then `npx hyperframes lint` after the first pass and after structural changes.\n2. `npx hyperframes check --json` and fix every error. While a lint error remains the layout and contrast audits don't run; \"0 samples\" means nothing was checked. Contrast failures carry a `suggestedColor`. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails `sweep_static`.\n3. `npx hyperframes snapshot` and read the PNGs (under `.hyperframes/artifacts/snapshots/`): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (`../hyperframes/references/format.md`).\n4. `npx hyperframes preview --background`, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.\n5. When it is time to render (step 4): `npx hyperframes render --quality looks --output out.mp4` (`draft` while iterating, `delivery` for the final). Confirm the file is non-empty and its `ffprobe` duration matches the root `data-duration`, then look at decoded frames.\n\n\"This element\" or the current selection: `npx hyperframes preview --context --json --context-fields selection`; `no-selection` means ask them to click it.\n\n## Edit the timeline\n\nThese are the edits Studio itself makes, so the result stays in Studio's shape.\n\n- `timeline --json` lists clips with absolute `absStart`/`absEnd`, owning `file` and the `#id` ref the edit commands take (`timeline ids` stamps missing ids).\n- `timeline move|trim|split|set|duplicate|delete <ref> … --plan --json` previews one edit; run it again without `--plan`. `--start`, `--end`, `--duration` set one edge or the length.\n- An edit is refused when the clip would overlap a neighbour (`--overwrite`, or move the neighbour first) or end past its composition: raise the root's `data-duration` first. No command changes `data-duration`.\n- Several edits at once: a JSON file such as `[{\"verb\": \"move\", \"ref\": \"#outro\", \"time\": \"9\"}]`, then `timeline apply plan.json --json`. Each run prints a `receipt`; save it and `timeline undo receipt.json` reverts it.\n\n<!-- history (trial): remove this block together with the command -->\n\n## Project history\n\nEvery write is kept and can be undone. At the start of a turn, `npx hyperframes history begin --who <you> --label \"<plan>\"`, then `history --since mine --who <you>` to see what the person changed; build on their edits. A check failed or they say it got worse: `history undo --who <you>`, never hand-edit back. End the turn with `history end`.\n\n<!-- /history (trial) -->\n\n## Render where\n\n| Need | Command |\n| --- | --- |\n| Local | `render --quality looks --output out.mp4` (`draft`, `delivery`) |\n| Reproducible container | `render --docker --strict --output out.mp4` |\n| Batch from variables | `render --batch rows.json --output \"renders/{name}.mp4\"` |\n| Hosted, no local Chrome or FFmpeg | `cloud render` (`references/cloud.md`) |\n| Your own AWS or GCP | `lambda render`, `cloudrun render` (`references/lambda.md`, `references/cloudrun.md`) |\n\nA 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (`HYPERFRAMES_RENDER_DETACHED=1`, its own group, output to a log) and wait with `until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done`, never `pgrep -f`, which matches its own loop and waits until the tool times out.\n\nAfter a verified render, send one `feedback --rating`, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: `references/feedback.md`.\n\n## When a command fails\n\n| Symptom | Fix |\n| --- | --- |\n| Chrome missing or won't start | `npx hyperframes browser ensure`; `doctor --json` always exits 0, gate on `.ok` |\n| A heavy page isn't ready in time | Raise `--timeout` on `check` or `snapshot` |\n| Unusual codec looks blank | Keep `--proxy` on (the default) |\n| Render slow on Linux | The summary's second line says `screenshot` + `software gpu`: the slow path |\n| `capture` fails or writes `BLOCKED.md` | Take nothing from its partial files; retry into a new `-o` folder |\n| Disk tight | `clean --dry-run`, then `clean`; never delete `.hyperframes` (it holds history) |\n\n## References\n\nRead the row before running its command.\n\n| Commands | Read |\n| --- | --- |\n| `init`, `capture`, `skills` | `references/init-and-scaffold.md` |\n| `lint`, `check`, motion sidecars, `snapshot` | `references/lint-validate-inspect.md` |\n| `compare`, `grade-compare`, `render --batch` | `references/compare-and-batch.md` |\n| `beats` | `references/beats.md` |\n| `preview`, `play`, `render`, `publish`, Studio context | `references/preview-render.md` |\n| `doctor`, `browser` | `references/doctor-browser.md` |\n| `auth`, `cloud`, template variables | `references/cloud.md` |\n| `lambda`, `cloudrun` | `references/lambda.md`, `references/cloudrun.md` |\n| `info`, `upgrade`, `compositions`, `timeline`, `docs`, `usage`, telemetry | `references/upgrade-info-misc.md` |\n| `--strict` flags, run ids, `clean`, shader lint, JSON paths | `references/conventions.md` |\n| `keyframes` | `../hyperframes/references/motion.md` (Seeing motion) |\n","skills/hyperframes/SKILL.md":"---\nname: hyperframes\ndescription: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames\n\nHyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes <command>` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say \"unknown\" when it is).\n\n`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init <dir>`. A website as the subject: `npx hyperframes capture <url> --json`.\n\nBuild what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none.\n\n## Contract\n\n`npx hyperframes check --json` reports most violations with a `Fix:` line.\n\n1. Every timed element has `class=\"clip\"`, `data-start` and `data-duration` in seconds, and shows over `[start, start + duration)`: land an end state just before its end. `data-track-index` is only a Studio lane; paint order is `z-index`.\n2. The video's length is the root's `data-duration`: overrun is cut, an early end holds the last frame.\n3. Each composition builds one paused timeline and registers it after its tweens: `window.__timelines[\"<data-composition-id>\"] = tl`.\n4. No `Date.now()`, unseeded `Math.random()`, network fetches, timers or `repeat: -1`. Everything visible is a function of timeline time.\n5. Never tween `display`, `visibility` or `autoAlpha` on a `.clip`; animate a child.\n6. No CSS `transform` on an element GSAP transforms; animate transforms, not `left`/`top`/`width`/`height`.\n7. Never `play()`, `pause()` or seek media. A `<video>` keeps its sound with `data-has-audio=\"true\"`, else it is `muted`; music, voice, replacement sound and J/L cuts are a separate `<audio>`.\n8. Every `<audio>` has an `id` or it is left out of the mix. No `crossorigin` on media. Time a `<video>` or its wrapper, never both.\n9. Only the bundled fonts (`references/format.md`) resolve by name; any other family needs `@font-face` to a file in `assets/fonts/`.\n10. Asset paths are root-relative (`assets/...`), in sub-compositions too.\n11. Grades, grain, blur and vignettes on footage go through `npx hyperframes media-treatment` (`/media-use`), never CSS filters.\n12. A scene file puts its styles, markup and scripts inside `<template>` and styles its root as `#root`. Intended overflow or overlap: `data-layout-allow-overflow`, `data-layout-allow-overlap`.\n\n## Keep it editable\n\nStudio edits the tags you write.\n\n- One scene per sub-composition, short readable ids; the root holds only scene hosts, media and audio.\n- Timed elements are written in the HTML, not made by script, each with a stable `id`.\n- Copy, brand colours and swappable media are variables (`data-var-text`, `data-var-src`, `var(--id)`).\n- One kind per track: `data-track-kind=\"graphics\"` on scene and overlay hosts, `captions` on the one host that holds every caption group.\n- Content stays inside the 90% action-safe box, captions and key text inside 80% title-safe; Studio draws the guides, never add them.\n\n## Work loop\n\n- An existing project: `npx hyperframes timeline --json` shows what plays when; before any change, `npx hyperframes history --since mine --who <you>` shows what the person changed since your last turn: build on it (`/hyperframes-cli`).\n- A new film over ~15 s that tells something: its type's file (below), then `references/story.md`: three storylines that are three different films, in words only; the person picks unless they asked for the file or no stops. Then `SPEC.md` (`references/spec.md`): every adjective as a number, the defaults banned by name, the shots by frame.\n- After your last edit: `npx hyperframes check --json`; fix every error, weigh every warning. A film: `npx hyperframes snapshot --review` and `references/review.md`, ending in `REVIEW.md`. A small edit: snapshot what you changed (`--at`, `--range`, `--composition`) and look before you reply.\n- Render when the person approves the Studio preview, asks for the file or asks for no stops, after your check and review pass; otherwise stop at the preview and wait.\n\n## The HyperFrames desktop app\n\nCall it \"the HyperFrames desktop app\", never \"Studio\"; offer it as the better way to keep editing, not the only one.\n\n- Before the delivery render of a new video, open the Studio preview, even in no-questions mode, and say they can edit there. If `preview` printed \"Keep editing by chatting with Framey\", add that the **Edit with Framey** button opens the app.\n- After the delivery render, pass on its Framey line in your own words: offer to run the `hyperframes open` it names or give its download link; else say nothing (autonomous: the delivery note).\n- When any command says to run `catch-up`, run `npx hyperframes catch-up [dir]` before your next change; what it lists is their work, not a new request.\n\n## What to read\n\n| The request | Read |\n| --- | --- |\n| Launch, promo, feature | `references/types/launch.md` |\n| Explainer, tutorial | `references/types/explainer.md` |\n| Music video | `references/types/music.md` |\n| Chart, numbers | `references/types/data.md` |\n| Vertical or social clip | `references/types/vertical.md` |\n| 3D, simulation, generative | `references/types/3d.md` |\n| Character, mascot, story short | `references/types/character.md` |\n| A real place or map; a website, PR or script; kinetic type | `references/film.md` |\n| Captions; cards over a talking head | `references/captions.md`; `references/overlays.md` |\n| Motion: eases, titles, cuts, punch-ins, speed, holds | `references/motion.md` |\n| Scenes, attributes, media, lint; GSAP, Lottie, 3D, canvas | `references/format.md`; `references/runtimes.md` |\n\nDecks: `/slideshow`. Remotion source: `/remotion-to-hyperframes`. Figma: `/figma`. Installing, refreshing or upgrading skills and the pinned CLI: `references/skill-lifecycle.md`.\n","skills/hyperframes-registry/SKILL.md":"---\nname: hyperframes-registry\ndescription: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames registry\n\nStarting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it.\n\n## Find and install\n\n```bash\nnpx hyperframes catalog --query \"<what the beat should do, in English>\" --json\nnpx hyperframes add <name> --json        # prints the written files and the mount snippet\n```\n\n- Query in English even when the video is not: the catalog is indexed in English, and another script returns `No searchable words in query`, which is not a gap.\n- Search is local and sends nothing. The default `words` tier only finds items that reuse your words; `--on-device` ranks by meaning after a one-time ~33 MB download. Offer that download and let the person decide; never enable it silently. The `--json` envelope names the tier that answered.\n- Narrow with `--type block|component` and `--tag <tag>`. `add <tag>` installs every block with that tag; dependencies install first. `add` needs the network even for an item installed before; search works offline from the cached manifest.\n- Nothing fits: report it before you hand-build, on either tier. `catalog --query` prints the line pre-filled (`report_gap` in `--json`): `npx hyperframes feedback --search-miss \"<query>\" --wanted \"<the move you needed>\" --tier <tier>`. Describe the effect, not an item name you imagined.\n\nTiers, `dropped` and `unindexed`, stale indexes, offline behaviour: `references/search.md`.\n\n## What's in it\n\n| Blocks: a scene with its own timeline | Examples |\n| --- | --- |\n| Transitions | `beat-freeze-cut`, `chromatic-radial-split`, `cinematic-zoom` |\n| Overlays and lower thirds | `camcorder-hud`, `editorial-flash-overlay`, `lt-clean-bar` |\n| Title cards and kinetic type | `canopy-part-title`, `code-slice-hero` |\n| Social, chat and UI cards | `ai-chat-reveal`, `chatgpt-exchange` |\n| Code, charts, data and maps | `code-diff`, `bar-chart-race`, `data-chart` |\n| 3D, shader and backgrounds | `app-showcase`, `aurora`, `blob` |\n\n| Components: a snippet merged into your scene | Examples |\n| --- | --- |\n| Motion primitives and text effects | `agent-cursor`, `blur-in`, `bottom-up-letters` |\n| Caption styles | `caption-clip-wipe`, `caption-editorial-emphasis` |\n| Camera moves | `camera-shake`, `camera-scan-gate` |\n| Product demo and UI props | `before-after-wipe`, `browser-device-stage` |\n| Textures, particles and effects | `ascii-render-pass`, `grain-overlay` |\n\n## Wiring\n\n- **Block**: installs to `compositions/<name>.html`. Mount it with `data-composition-src`, `data-composition-id` matching the block's own id, `data-start` and the `data-duration` you need; the snippet `add` prints is the starting point. `references/wiring-blocks.md`.\n- **Component**: installs to `compositions/components/<name>.html`. Copy its markup, `<style>` and script into your scene, and follow its comment block if it hooks into your timeline. `references/wiring-components.md`.\n- Take the largest unit that fits, then edit it. Keep an installed item's ids prefixed as they are, so two items can't collide.\n- An item keeps its own variables; set them for one mount with `data-variable-values` on its host (`add --vars '{\"title\":\"…\"}'` writes that), and point its colour and font variables at your brand's.\n- Beat-synced blocks take hit times from `npx hyperframes beats --json`: the beat times minus the mount's `data-start`.\n- Install paths come from `hyperframes.json` (`references/install-locations.md`).\n\n## Contributing\n\nAuthoring a new block or component for an upstream PR: `references/contributing.md`, starter templates in `references/templates.md`, quality bar in `references/component-quality-bar.md`.\n","AGENTS.md":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); install everything only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update           # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                  # all 7 published skills at once\nnpx skills add heygen-com/hyperframes   # interactive picker (terminal only; repo-internal skills are excluded by default)\n```\n\nMake any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first.\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, voiceover, avatar and generated video, transcripts, cutouts, colour grades) with HeyGen or free local tools, and mix placed audio.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion.\n- `/slideshow` — a presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Issue and PR triage\n\nRead [TRIAGE.md](TRIAGE.md) before classifying issues, advertising contribution work, or triaging PRs. Check current source and overlapping PRs; keep difficulty, readiness, and ownership separate. Apply changes only within the task's authorization and verify the resulting GitHub state.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\nPackages load each other through their `exports`. Under Node, core, parsers,\nlint and studio-server resolve to `dist/`, and player always loads its built\nbundle. Run `bun run build` once in a fresh worktree, before any package's\ntests or typecheck. After editing a package that another package imports, run\nthat package's `build` again before the dependent package's tests. Core's\n`src/generated/` is git-ignored build output: if you see\n`Cannot find module '../generated/runtime-inline'`, run\n`bun run build:hyperframes-runtime`.\n\nOne file: `bun run --cwd packages/<pkg> test <path>`. Each package's `test`\nscript picks its runner (vitest in most, `bun test` in aws-lambda and\ngcp-cloud-run). Producer is the exception: a file that imports `bun:test` runs\nwith `bun test <file>`, any other with `bunx vitest run <file>`. Root `scripts/*.test.mjs` run through `bun run test:scripts`,\nwhich is an explicit list in `package.json`. CI's test-reachability check fails\nany test file that no runner reaches.\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","skills/media-use/SKILL.md":"---\nname: media-use\ndescription: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# Media in HyperFrames\n\nMedia lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it:\n\n```bash\nnpx hyperframes media-use resolve --type <type> --intent \"<what you need>\" --project <dir>\n```\n\nIt prints one line, `resolved <id> → <path> (<type>, <metadata>)`. List reusable assets first with `--candidates` and judge the fit yourself; reuse, ingest (`--from`) and adopt are in `references/resolve.md`.\n\n## Two ways to get it\n\n| Need | HeyGen (best quality) | Free, no account |\n| --- | --- | --- |\n| Music (`bgm`) | Catalog of 10k+ tracks | Local MusicGen (`audio/references/bgm.md`) |\n| Sound effects (`sfx`) | | Openverse; 21 bundled offline |\n| Images, icons | Asset search, 75k+ | Local FLUX (mflux), if installed |\n| Logos (`logo`) | | theSVG, GitHub avatar, favicon; never redrawn |\n| Voiceover (`voice`) | HeyGen voices, voice cloning | `npx hyperframes tts` (Kokoro on device; Python 3.10+ with `pip install kokoro-onnx soundfile`) |\n| A presenter speaking | Avatar video (`--type video`) | Local LTX for generic clips, if installed |\n| Transcripts | | `npx hyperframes transcribe` (Parakeet or whisper) |\n| Cutouts | `heygen background-removal` | `npx hyperframes remove-background` |\n| Grades, LUTs, looks | | `npx hyperframes media-treatment` |\n\n**Host apps.** Inside an app that gives you its own media tools, use those first. When `HEYGEN_API_BASE` is set, the host pays for HeyGen: don't ask for the `heygen` CLI or a sign-in, and when a call is refused, relay the host's message as written and stop.\n\n**HeyGen.** Install the [`heygen` CLI](https://developers.heygen.com/cli) and sign in with `heygen auth login --oauth`: the OAuth session carries a free allowance on subscription credits; an API key (`--api-key`) bills API credits. Check setup with `npx hyperframes media-use resolve --doctor`. When a request needs HeyGen (a presenter or avatar, a HeyGen voice, catalog music) and `heygen` is missing or signed out, tell the person how to get it: the install link, `heygen auth login --oauth` for the free allowance, or an API key for credits. Then offer the free path or wait. Beyond `resolve`, the same CLI makes text-to-video (`heygen video-agent create`), avatar videos with a recorded track (`heygen video create`), cloned voices (`heygen voice clone create`), dubbing (`heygen lipsync`), translated videos (`heygen video-translate`) and short clips from a long video (`heygen ai-clipping`): recipes in `references/operations.md`.\n\n**Free.** Every tool in the free column needs no account; local models are opt-in installs (`references/setup-providers.md`). Without `heygen`, `resolve` for music, images and icons fails and says so; credit CC BY sounds (`audio/references/sfx.md`). `--local-only` skips every network provider.\n\n**Cost.** Confirm before a paid call you chose to make (an avatar video counts); one the person asked for just runs. `--provider <name>` pins one generator when the person names it.\n\n## Looks on real footage\n\nFeedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent: read `references/media-treatments.md`. Inspect the real `<img>`/`<video>`, pick one intent, start from `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>`; never `--all`. Persist the final treatment with `npx hyperframes media-treatment`; no CSS or SVG stand-ins for supported effects, and no generated `.cube` just to encode exposure or warmth.\n\n## Offer once, never add silently\n\nWhen you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect \"leave it\".\n\n## Where to look\n\n| Task | Read |\n| --- | --- |\n| Resolve, reuse, adopt, ingest, flags | `references/resolve.md` |\n| Grading, LUTs, `grade-compare` | `references/grading.md` |\n| Voiceover, music, sound effects, captions, transcription | `references/audio.md` |\n| Cut, reframe or transform media; HeyGen recipes | `references/operations.md` |\n| Treatments, realtime effects, overlays, reveals | `references/media-treatments.md` |\n| Install, sign-in, providers, RAM ladders | `references/setup-providers.md` |\n| Fades, gain, ducking, automation, effects, buses on placed tracks | `references/mixing.md` |\n| Local commands: grade, cutout, loudness, beats | `references/local.md` |\n| Remembered preferences | `references/memory.md` |\n","CLAUDE.md":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships 7 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Install all 7 only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update                         # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                                # all 7 published skills at once — only on explicit request\nnpx skills add heygen-com/hyperframes                 # interactive picker; internal skills require INSTALL_INTERNAL_SKILLS=1 for discovery\nnpx skills add heygen-com/hyperframes --all           # excludes internal skills unless INSTALL_INTERNAL_SKILLS=1\nnpx skills add heygen-com/hyperframes --skill <name>  # a named match installs regardless of metadata.internal (bare name, no leading slash)\n```\n\n> **Warning:** Never run `npx skills add ... --all` from inside a HyperFrames checkout: it selects the OpenClaw target, whose `skills/` directory is the repo's own `skills/`, and removes each existing `skills/<name>` destination before linking. A fresh clone restores tracked source, but uncommitted work under `skills/` does not recover. Run it from an empty directory or from your own project root. This happens regardless of `metadata.internal`.\n\n`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters.\n\nMake any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see \"Skill catalog maintenance\" below).\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks) with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.\n- `/slideshow` — a presentation, pitch deck or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation and presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Skill catalog maintenance\n\nWhen adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:\n\n1. The skill list above (CLAUDE.md) AND the skill list in the root `AGENTS.md` AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup pages that compress the same descriptions — `docs/prompting/overview.mdx` (\"One-time setup\") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill.\n2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical.\n3. The routing surface for \"make a video\" requests is the References table and closing line of `skills/hyperframes/SKILL.md`. A new reference or skill that a request should reach gets a row or a mention there.\n4. Keep the same grouping on every surface: the core set (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`) first, then the on-demand skills (`/figma`, `/slideshow`, `/remotion-to-hyperframes`).\n5. Skill count appears in the README and CLAUDE.md intro lines (\"7 AI agent skills…\") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.\n\nThe skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line \"use when\" blurb; copy from there into the catalog rather than paraphrasing.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/mcp.json)","marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/marketplace.json)","plugin.json":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/plugin.json)",".github/copilot-instructions.md":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.github/copilot-instructions.md)",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/plugin.json)","skills/hyperframes/README.md":"# Hyperframes Skill\n\nPath: `skills/hyperframes/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/README.md)","skills/hyperframes-cli/README.md":"# Hyperframes-cli Skill\n\nPath: `skills/hyperframes-cli/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/README.md)","skills/hyperframes-registry/README.md":"# Hyperframes-registry Skill\n\nPath: `skills/hyperframes-registry/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/README.md)","skills/media-use/README.md":"# Media-use Skill\n\nPath: `skills/media-use/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/README.md)"},"files":{"skills/hyperframes-cli/SKILL.md":"---\nname: hyperframes-cli\ndescription: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames CLI\n\nRun `npx hyperframes <command>` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero.\n\n## Commands by job\n\n| Job | Commands |\n| --- | --- |\n| Start | `init <dir>` (blank; `--example <name>` only when asked), `capture <url>` |\n| Read a project | `info`, `compositions`, `timeline --json`, `docs <topic>` |\n| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) |\n| Look at it | `snapshot` (`--at <t,…>`, `--range START,END`, `--composition <id>`, `--zoom`, `--angle`, `--against <video>`), `keyframes`, `compare`, `audio` |\n| Edit the timeline | `timeline` with `move`, `trim`, `split`, `set`, `duplicate`, `delete`, `apply`, `undo`, `ids` |\n| Reuse | `catalog`, `add` (`/hyperframes-registry`) |\n| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |\n| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |\n| Desktop app | `open`, `catch-up` |\n| Upkeep | `doctor`, `browser`, `upgrade`, `skills`, `usage`, `clean`, `feedback` |\n\n`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.\n\n## The loop\n\n1. Write, then `npx hyperframes lint` after the first pass and after structural changes.\n2. `npx hyperframes check --json` and fix every error. While a lint error remains the layout and contrast audits don't run; \"0 samples\" means nothing was checked. Contrast failures carry a `suggestedColor`. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails `sweep_static`.\n3. `npx hyperframes snapshot` and read the PNGs (under `.hyperframes/artifacts/snapshots/`): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (`../hyperframes/references/format.md`).\n4. `npx hyperframes preview --background`, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.\n5. When it is time to render (step 4): `npx hyperframes render --quality looks --output out.mp4` (`draft` while iterating, `delivery` for the final). Confirm the file is non-empty and its `ffprobe` duration matches the root `data-duration`, then look at decoded frames.\n\n\"This element\" or the current selection: `npx hyperframes preview --context --json --context-fields selection`; `no-selection` means ask them to click it.\n\n## Edit the timeline\n\nThese are the edits Studio itself makes, so the result stays in Studio's shape.\n\n- `timeline --json` lists clips with absolute `absStart`/`absEnd`, owning `file` and the `#id` ref the edit commands take (`timeline ids` stamps missing ids).\n- `timeline move|trim|split|set|duplicate|delete <ref> … --plan --json` previews one edit; run it again without `--plan`. `--start`, `--end`, `--duration` set one edge or the length.\n- An edit is refused when the clip would overlap a neighbour (`--overwrite`, or move the neighbour first) or end past its composition: raise the root's `data-duration` first. No command changes `data-duration`.\n- Several edits at once: a JSON file such as `[{\"verb\": \"move\", \"ref\": \"#outro\", \"time\": \"9\"}]`, then `timeline apply plan.json --json`. Each run prints a `receipt`; save it and `timeline undo receipt.json` reverts it.\n\n<!-- history (trial): remove this block together with the command -->\n\n## Project history\n\nEvery write is kept and can be undone. At the start of a turn, `npx hyperframes history begin --who <you> --label \"<plan>\"`, then `history --since mine --who <you>` to see what the person changed; build on their edits. A check failed or they say it got worse: `history undo --who <you>`, never hand-edit back. End the turn with `history end`.\n\n<!-- /history (trial) -->\n\n## Render where\n\n| Need | Command |\n| --- | --- |\n| Local | `render --quality looks --output out.mp4` (`draft`, `delivery`) |\n| Reproducible container | `render --docker --strict --output out.mp4` |\n| Batch from variables | `render --batch rows.json --output \"renders/{name}.mp4\"` |\n| Hosted, no local Chrome or FFmpeg | `cloud render` (`references/cloud.md`) |\n| Your own AWS or GCP | `lambda render`, `cloudrun render` (`references/lambda.md`, `references/cloudrun.md`) |\n\nA 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (`HYPERFRAMES_RENDER_DETACHED=1`, its own group, output to a log) and wait with `until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done`, never `pgrep -f`, which matches its own loop and waits until the tool times out.\n\nAfter a verified render, send one `feedback --rating`, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: `references/feedback.md`.\n\n## When a command fails\n\n| Symptom | Fix |\n| --- | --- |\n| Chrome missing or won't start | `npx hyperframes browser ensure`; `doctor --json` always exits 0, gate on `.ok` |\n| A heavy page isn't ready in time | Raise `--timeout` on `check` or `snapshot` |\n| Unusual codec looks blank | Keep `--proxy` on (the default) |\n| Render slow on Linux | The summary's second line says `screenshot` + `software gpu`: the slow path |\n| `capture` fails or writes `BLOCKED.md` | Take nothing from its partial files; retry into a new `-o` folder |\n| Disk tight | `clean --dry-run`, then `clean`; never delete `.hyperframes` (it holds history) |\n\n## References\n\nRead the row before running its command.\n\n| Commands | Read |\n| --- | --- |\n| `init`, `capture`, `skills` | `references/init-and-scaffold.md` |\n| `lint`, `check`, motion sidecars, `snapshot` | `references/lint-validate-inspect.md` |\n| `compare`, `grade-compare`, `render --batch` | `references/compare-and-batch.md` |\n| `beats` | `references/beats.md` |\n| `preview`, `play`, `render`, `publish`, Studio context | `references/preview-render.md` |\n| `doctor`, `browser` | `references/doctor-browser.md` |\n| `auth`, `cloud`, template variables | `references/cloud.md` |\n| `lambda`, `cloudrun` | `references/lambda.md`, `references/cloudrun.md` |\n| `info`, `upgrade`, `compositions`, `timeline`, `docs`, `usage`, telemetry | `references/upgrade-info-misc.md` |\n| `--strict` flags, run ids, `clean`, shader lint, JSON paths | `references/conventions.md` |\n| `keyframes` | `../hyperframes/references/motion.md` (Seeing motion) |\n","skills/hyperframes/SKILL.md":"---\nname: hyperframes\ndescription: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames\n\nHyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes <command>` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say \"unknown\" when it is).\n\n`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init <dir>`. A website as the subject: `npx hyperframes capture <url> --json`.\n\nBuild what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none.\n\n## Contract\n\n`npx hyperframes check --json` reports most violations with a `Fix:` line.\n\n1. Every timed element has `class=\"clip\"`, `data-start` and `data-duration` in seconds, and shows over `[start, start + duration)`: land an end state just before its end. `data-track-index` is only a Studio lane; paint order is `z-index`.\n2. The video's length is the root's `data-duration`: overrun is cut, an early end holds the last frame.\n3. Each composition builds one paused timeline and registers it after its tweens: `window.__timelines[\"<data-composition-id>\"] = tl`.\n4. No `Date.now()`, unseeded `Math.random()`, network fetches, timers or `repeat: -1`. Everything visible is a function of timeline time.\n5. Never tween `display`, `visibility` or `autoAlpha` on a `.clip`; animate a child.\n6. No CSS `transform` on an element GSAP transforms; animate transforms, not `left`/`top`/`width`/`height`.\n7. Never `play()`, `pause()` or seek media. A `<video>` keeps its sound with `data-has-audio=\"true\"`, else it is `muted`; music, voice, replacement sound and J/L cuts are a separate `<audio>`.\n8. Every `<audio>` has an `id` or it is left out of the mix. No `crossorigin` on media. Time a `<video>` or its wrapper, never both.\n9. Only the bundled fonts (`references/format.md`) resolve by name; any other family needs `@font-face` to a file in `assets/fonts/`.\n10. Asset paths are root-relative (`assets/...`), in sub-compositions too.\n11. Grades, grain, blur and vignettes on footage go through `npx hyperframes media-treatment` (`/media-use`), never CSS filters.\n12. A scene file puts its styles, markup and scripts inside `<template>` and styles its root as `#root`. Intended overflow or overlap: `data-layout-allow-overflow`, `data-layout-allow-overlap`.\n\n## Keep it editable\n\nStudio edits the tags you write.\n\n- One scene per sub-composition, short readable ids; the root holds only scene hosts, media and audio.\n- Timed elements are written in the HTML, not made by script, each with a stable `id`.\n- Copy, brand colours and swappable media are variables (`data-var-text`, `data-var-src`, `var(--id)`).\n- One kind per track: `data-track-kind=\"graphics\"` on scene and overlay hosts, `captions` on the one host that holds every caption group.\n- Content stays inside the 90% action-safe box, captions and key text inside 80% title-safe; Studio draws the guides, never add them.\n\n## Work loop\n\n- An existing project: `npx hyperframes timeline --json` shows what plays when; before any change, `npx hyperframes history --since mine --who <you>` shows what the person changed since your last turn: build on it (`/hyperframes-cli`).\n- A new film over ~15 s that tells something: its type's file (below), then `references/story.md`: three storylines that are three different films, in words only; the person picks unless they asked for the file or no stops. Then `SPEC.md` (`references/spec.md`): every adjective as a number, the defaults banned by name, the shots by frame.\n- After your last edit: `npx hyperframes check --json`; fix every error, weigh every warning. A film: `npx hyperframes snapshot --review` and `references/review.md`, ending in `REVIEW.md`. A small edit: snapshot what you changed (`--at`, `--range`, `--composition`) and look before you reply.\n- Render when the person approves the Studio preview, asks for the file or asks for no stops, after your check and review pass; otherwise stop at the preview and wait.\n\n## The HyperFrames desktop app\n\nCall it \"the HyperFrames desktop app\", never \"Studio\"; offer it as the better way to keep editing, not the only one.\n\n- Before the delivery render of a new video, open the Studio preview, even in no-questions mode, and say they can edit there. If `preview` printed \"Keep editing by chatting with Framey\", add that the **Edit with Framey** button opens the app.\n- After the delivery render, pass on its Framey line in your own words: offer to run the `hyperframes open` it names or give its download link; else say nothing (autonomous: the delivery note).\n- When any command says to run `catch-up`, run `npx hyperframes catch-up [dir]` before your next change; what it lists is their work, not a new request.\n\n## What to read\n\n| The request | Read |\n| --- | --- |\n| Launch, promo, feature | `references/types/launch.md` |\n| Explainer, tutorial | `references/types/explainer.md` |\n| Music video | `references/types/music.md` |\n| Chart, numbers | `references/types/data.md` |\n| Vertical or social clip | `references/types/vertical.md` |\n| 3D, simulation, generative | `references/types/3d.md` |\n| Character, mascot, story short | `references/types/character.md` |\n| A real place or map; a website, PR or script; kinetic type | `references/film.md` |\n| Captions; cards over a talking head | `references/captions.md`; `references/overlays.md` |\n| Motion: eases, titles, cuts, punch-ins, speed, holds | `references/motion.md` |\n| Scenes, attributes, media, lint; GSAP, Lottie, 3D, canvas | `references/format.md`; `references/runtimes.md` |\n\nDecks: `/slideshow`. Remotion source: `/remotion-to-hyperframes`. Figma: `/figma`. Installing, refreshing or upgrading skills and the pinned CLI: `references/skill-lifecycle.md`.\n","skills/hyperframes-registry/SKILL.md":"---\nname: hyperframes-registry\ndescription: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames registry\n\nStarting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it.\n\n## Find and install\n\n```bash\nnpx hyperframes catalog --query \"<what the beat should do, in English>\" --json\nnpx hyperframes add <name> --json        # prints the written files and the mount snippet\n```\n\n- Query in English even when the video is not: the catalog is indexed in English, and another script returns `No searchable words in query`, which is not a gap.\n- Search is local and sends nothing. The default `words` tier only finds items that reuse your words; `--on-device` ranks by meaning after a one-time ~33 MB download. Offer that download and let the person decide; never enable it silently. The `--json` envelope names the tier that answered.\n- Narrow with `--type block|component` and `--tag <tag>`. `add <tag>` installs every block with that tag; dependencies install first. `add` needs the network even for an item installed before; search works offline from the cached manifest.\n- Nothing fits: report it before you hand-build, on either tier. `catalog --query` prints the line pre-filled (`report_gap` in `--json`): `npx hyperframes feedback --search-miss \"<query>\" --wanted \"<the move you needed>\" --tier <tier>`. Describe the effect, not an item name you imagined.\n\nTiers, `dropped` and `unindexed`, stale indexes, offline behaviour: `references/search.md`.\n\n## What's in it\n\n| Blocks: a scene with its own timeline | Examples |\n| --- | --- |\n| Transitions | `beat-freeze-cut`, `chromatic-radial-split`, `cinematic-zoom` |\n| Overlays and lower thirds | `camcorder-hud`, `editorial-flash-overlay`, `lt-clean-bar` |\n| Title cards and kinetic type | `canopy-part-title`, `code-slice-hero` |\n| Social, chat and UI cards | `ai-chat-reveal`, `chatgpt-exchange` |\n| Code, charts, data and maps | `code-diff`, `bar-chart-race`, `data-chart` |\n| 3D, shader and backgrounds | `app-showcase`, `aurora`, `blob` |\n\n| Components: a snippet merged into your scene | Examples |\n| --- | --- |\n| Motion primitives and text effects | `agent-cursor`, `blur-in`, `bottom-up-letters` |\n| Caption styles | `caption-clip-wipe`, `caption-editorial-emphasis` |\n| Camera moves | `camera-shake`, `camera-scan-gate` |\n| Product demo and UI props | `before-after-wipe`, `browser-device-stage` |\n| Textures, particles and effects | `ascii-render-pass`, `grain-overlay` |\n\n## Wiring\n\n- **Block**: installs to `compositions/<name>.html`. Mount it with `data-composition-src`, `data-composition-id` matching the block's own id, `data-start` and the `data-duration` you need; the snippet `add` prints is the starting point. `references/wiring-blocks.md`.\n- **Component**: installs to `compositions/components/<name>.html`. Copy its markup, `<style>` and script into your scene, and follow its comment block if it hooks into your timeline. `references/wiring-components.md`.\n- Take the largest unit that fits, then edit it. Keep an installed item's ids prefixed as they are, so two items can't collide.\n- An item keeps its own variables; set them for one mount with `data-variable-values` on its host (`add --vars '{\"title\":\"…\"}'` writes that), and point its colour and font variables at your brand's.\n- Beat-synced blocks take hit times from `npx hyperframes beats --json`: the beat times minus the mount's `data-start`.\n- Install paths come from `hyperframes.json` (`references/install-locations.md`).\n\n## Contributing\n\nAuthoring a new block or component for an upstream PR: `references/contributing.md`, starter templates in `references/templates.md`, quality bar in `references/component-quality-bar.md`.\n","AGENTS.md":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); install everything only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update           # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                  # all 7 published skills at once\nnpx skills add heygen-com/hyperframes   # interactive picker (terminal only; repo-internal skills are excluded by default)\n```\n\nMake any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first.\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, voiceover, avatar and generated video, transcripts, cutouts, colour grades) with HeyGen or free local tools, and mix placed audio.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion.\n- `/slideshow` — a presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Issue and PR triage\n\nRead [TRIAGE.md](TRIAGE.md) before classifying issues, advertising contribution work, or triaging PRs. Check current source and overlapping PRs; keep difficulty, readiness, and ownership separate. Apply changes only within the task's authorization and verify the resulting GitHub state.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\nPackages load each other through their `exports`. Under Node, core, parsers,\nlint and studio-server resolve to `dist/`, and player always loads its built\nbundle. Run `bun run build` once in a fresh worktree, before any package's\ntests or typecheck. After editing a package that another package imports, run\nthat package's `build` again before the dependent package's tests. Core's\n`src/generated/` is git-ignored build output: if you see\n`Cannot find module '../generated/runtime-inline'`, run\n`bun run build:hyperframes-runtime`.\n\nOne file: `bun run --cwd packages/<pkg> test <path>`. Each package's `test`\nscript picks its runner (vitest in most, `bun test` in aws-lambda and\ngcp-cloud-run). Producer is the exception: a file that imports `bun:test` runs\nwith `bun test <file>`, any other with `bunx vitest run <file>`. Root `scripts/*.test.mjs` run through `bun run test:scripts`,\nwhich is an explicit list in `package.json`. CI's test-reachability check fails\nany test file that no runner reaches.\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","skills/media-use/SKILL.md":"---\nname: media-use\ndescription: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# Media in HyperFrames\n\nMedia lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it:\n\n```bash\nnpx hyperframes media-use resolve --type <type> --intent \"<what you need>\" --project <dir>\n```\n\nIt prints one line, `resolved <id> → <path> (<type>, <metadata>)`. List reusable assets first with `--candidates` and judge the fit yourself; reuse, ingest (`--from`) and adopt are in `references/resolve.md`.\n\n## Two ways to get it\n\n| Need | HeyGen (best quality) | Free, no account |\n| --- | --- | --- |\n| Music (`bgm`) | Catalog of 10k+ tracks | Local MusicGen (`audio/references/bgm.md`) |\n| Sound effects (`sfx`) | | Openverse; 21 bundled offline |\n| Images, icons | Asset search, 75k+ | Local FLUX (mflux), if installed |\n| Logos (`logo`) | | theSVG, GitHub avatar, favicon; never redrawn |\n| Voiceover (`voice`) | HeyGen voices, voice cloning | `npx hyperframes tts` (Kokoro on device; Python 3.10+ with `pip install kokoro-onnx soundfile`) |\n| A presenter speaking | Avatar video (`--type video`) | Local LTX for generic clips, if installed |\n| Transcripts | | `npx hyperframes transcribe` (Parakeet or whisper) |\n| Cutouts | `heygen background-removal` | `npx hyperframes remove-background` |\n| Grades, LUTs, looks | | `npx hyperframes media-treatment` |\n\n**Host apps.** Inside an app that gives you its own media tools, use those first. When `HEYGEN_API_BASE` is set, the host pays for HeyGen: don't ask for the `heygen` CLI or a sign-in, and when a call is refused, relay the host's message as written and stop.\n\n**HeyGen.** Install the [`heygen` CLI](https://developers.heygen.com/cli) and sign in with `heygen auth login --oauth`: the OAuth session carries a free allowance on subscription credits; an API key (`--api-key`) bills API credits. Check setup with `npx hyperframes media-use resolve --doctor`. When a request needs HeyGen (a presenter or avatar, a HeyGen voice, catalog music) and `heygen` is missing or signed out, tell the person how to get it: the install link, `heygen auth login --oauth` for the free allowance, or an API key for credits. Then offer the free path or wait. Beyond `resolve`, the same CLI makes text-to-video (`heygen video-agent create`), avatar videos with a recorded track (`heygen video create`), cloned voices (`heygen voice clone create`), dubbing (`heygen lipsync`), translated videos (`heygen video-translate`) and short clips from a long video (`heygen ai-clipping`): recipes in `references/operations.md`.\n\n**Free.** Every tool in the free column needs no account; local models are opt-in installs (`references/setup-providers.md`). Without `heygen`, `resolve` for music, images and icons fails and says so; credit CC BY sounds (`audio/references/sfx.md`). `--local-only` skips every network provider.\n\n**Cost.** Confirm before a paid call you chose to make (an avatar video counts); one the person asked for just runs. `--provider <name>` pins one generator when the person names it.\n\n## Looks on real footage\n\nFeedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent: read `references/media-treatments.md`. Inspect the real `<img>`/`<video>`, pick one intent, start from `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>`; never `--all`. Persist the final treatment with `npx hyperframes media-treatment`; no CSS or SVG stand-ins for supported effects, and no generated `.cube` just to encode exposure or warmth.\n\n## Offer once, never add silently\n\nWhen you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect \"leave it\".\n\n## Where to look\n\n| Task | Read |\n| --- | --- |\n| Resolve, reuse, adopt, ingest, flags | `references/resolve.md` |\n| Grading, LUTs, `grade-compare` | `references/grading.md` |\n| Voiceover, music, sound effects, captions, transcription | `references/audio.md` |\n| Cut, reframe or transform media; HeyGen recipes | `references/operations.md` |\n| Treatments, realtime effects, overlays, reveals | `references/media-treatments.md` |\n| Install, sign-in, providers, RAM ladders | `references/setup-providers.md` |\n| Fades, gain, ducking, automation, effects, buses on placed tracks | `references/mixing.md` |\n| Local commands: grade, cutout, loudness, beats | `references/local.md` |\n| Remembered preferences | `references/memory.md` |\n","CLAUDE.md":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships 7 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Install all 7 only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update                         # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                                # all 7 published skills at once — only on explicit request\nnpx skills add heygen-com/hyperframes                 # interactive picker; internal skills require INSTALL_INTERNAL_SKILLS=1 for discovery\nnpx skills add heygen-com/hyperframes --all           # excludes internal skills unless INSTALL_INTERNAL_SKILLS=1\nnpx skills add heygen-com/hyperframes --skill <name>  # a named match installs regardless of metadata.internal (bare name, no leading slash)\n```\n\n> **Warning:** Never run `npx skills add ... --all` from inside a HyperFrames checkout: it selects the OpenClaw target, whose `skills/` directory is the repo's own `skills/`, and removes each existing `skills/<name>` destination before linking. A fresh clone restores tracked source, but uncommitted work under `skills/` does not recover. Run it from an empty directory or from your own project root. This happens regardless of `metadata.internal`.\n\n`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters.\n\nMake any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see \"Skill catalog maintenance\" below).\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks) with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.\n- `/slideshow` — a presentation, pitch deck or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation and presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Skill catalog maintenance\n\nWhen adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:\n\n1. The skill list above (CLAUDE.md) AND the skill list in the root `AGENTS.md` AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup pages that compress the same descriptions — `docs/prompting/overview.mdx` (\"One-time setup\") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill.\n2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical.\n3. The routing surface for \"make a video\" requests is the References table and closing line of `skills/hyperframes/SKILL.md`. A new reference or skill that a request should reach gets a row or a mention there.\n4. Keep the same grouping on every surface: the core set (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`) first, then the on-demand skills (`/figma`, `/slideshow`, `/remotion-to-hyperframes`).\n5. Skill count appears in the README and CLAUDE.md intro lines (\"7 AI agent skills…\") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.\n\nThe skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line \"use when\" blurb; copy from there into the catalog rather than paraphrasing.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/mcp.json)","marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/marketplace.json)","plugin.json":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/plugin.json)",".github/copilot-instructions.md":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.github/copilot-instructions.md)",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/plugin.json)","skills/hyperframes/README.md":"# Hyperframes Skill\n\nPath: `skills/hyperframes/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/README.md)","skills/hyperframes-cli/README.md":"# Hyperframes-cli Skill\n\nPath: `skills/hyperframes-cli/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/README.md)","skills/hyperframes-registry/README.md":"# Hyperframes-registry Skill\n\nPath: `skills/hyperframes-registry/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/README.md)","skills/media-use/README.md":"# Media-use Skill\n\nPath: `skills/media-use/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/README.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); install everything only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update           # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                  # all 7 published skills at once\nnpx skills add heygen-com/hyperframes   # interactive picker (terminal only; repo-internal skills are excluded by default)\n```\n\nMake any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first.\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, voiceover, avatar and generated video, transcripts, cutouts, colour grades) with HeyGen or free local tools, and mix placed audio.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion.\n- `/slideshow` — a presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Issue and PR triage\n\nRead [TRIAGE.md](TRIAGE.md) before classifying issues, advertising contribution work, or triaging PRs. Check current source and overlapping PRs; keep difficulty, readiness, and ownership separate. Apply changes only within the task's authorization and verify the resulting GitHub state.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\nPackages load each other through their `exports`. Under Node, core, parsers,\nlint and studio-server resolve to `dist/`, and player always loads its built\nbundle. Run `bun run build` once in a fresh worktree, before any package's\ntests or typecheck. After editing a package that another package imports, run\nthat package's `build` again before the dependent package's tests. Core's\n`src/generated/` is git-ignored build output: if you see\n`Cannot find module '../generated/runtime-inline'`, run\n`bun run build:hyperframes-runtime`.\n\nOne file: `bun run --cwd packages/<pkg> test <path>`. Each package's `test`\nscript picks its runner (vitest in most, `bun test` in aws-lambda and\ngcp-cloud-run). Producer is the exception: a file that imports `bun:test` runs\nwith `bun test <file>`, any other with `bunx vitest run <file>`. Root `scripts/*.test.mjs` run through `bun run test:scripts`,\nwhich is an explicit list in `package.json`. CI's test-reachability check fails\nany test file that no runner reaches.\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","isInternal":false,"tokens":1549,"sizeBytes":6707},{"name":"README.md","path":"skills/hyperframes-cli/README.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/README.md","title":"Hyperframes-cli Skill","category":"anthropic-skill","format":"markdown","content":"# Hyperframes-cli Skill\n\nPath: `skills/hyperframes-cli/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/README.md)","tokens":300,"sizeBytes":191},{"name":"SKILL.md","path":"skills/hyperframes-cli/SKILL.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/SKILL.md","title":"hyperframes-cli","category":"anthropic-skill","format":"markdown","content":"---\nname: hyperframes-cli\ndescription: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames CLI\n\nRun `npx hyperframes <command>` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero.\n\n## Commands by job\n\n| Job | Commands |\n| --- | --- |\n| Start | `init <dir>` (blank; `--example <name>` only when asked), `capture <url>` |\n| Read a project | `info`, `compositions`, `timeline --json`, `docs <topic>` |\n| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) |\n| Look at it | `snapshot` (`--at <t,…>`, `--range START,END`, `--composition <id>`, `--zoom`, `--angle`, `--against <video>`), `keyframes`, `compare`, `audio` |\n| Edit the timeline | `timeline` with `move`, `trim`, `split`, `set`, `duplicate`, `delete`, `apply`, `undo`, `ids` |\n| Reuse | `catalog`, `add` (`/hyperframes-registry`) |\n| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |\n| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |\n| Desktop app | `open`, `catch-up` |\n| Upkeep | `doctor`, `browser`, `upgrade`, `skills`, `usage`, `clean`, `feedback` |\n\n`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.\n\n## The loop\n\n1. Write, then `npx hyperframes lint` after the first pass and after structural changes.\n2. `npx hyperframes check --json` and fix every error. While a lint error remains the layout and contrast audits don't run; \"0 samples\" means nothing was checked. Contrast failures carry a `suggestedColor`. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails `sweep_static`.\n3. `npx hyperframes snapshot` and read the PNGs (under `.hyperframes/artifacts/snapshots/`): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (`../hyperframes/references/format.md`).\n4. `npx hyperframes preview --background`, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.\n5. When it is time to render (step 4): `npx hyperframes render --quality looks --output out.mp4` (`draft` while iterating, `delivery` for the final). Confirm the file is non-empty and its `ffprobe` duration matches the root `data-duration`, then look at decoded frames.\n\n\"This element\" or the current selection: `npx hyperframes preview --context --json --context-fields selection`; `no-selection` means ask them to click it.\n\n## Edit the timeline\n\nThese are the edits Studio itself makes, so the result stays in Studio's shape.\n\n- `timeline --json` lists clips with absolute `absStart`/`absEnd`, owning `file` and the `#id` ref the edit commands take (`timeline ids` stamps missing ids).\n- `timeline move|trim|split|set|duplicate|delete <ref> … --plan --json` previews one edit; run it again without `--plan`. `--start`, `--end`, `--duration` set one edge or the length.\n- An edit is refused when the clip would overlap a neighbour (`--overwrite`, or move the neighbour first) or end past its composition: raise the root's `data-duration` first. No command changes `data-duration`.\n- Several edits at once: a JSON file such as `[{\"verb\": \"move\", \"ref\": \"#outro\", \"time\": \"9\"}]`, then `timeline apply plan.json --json`. Each run prints a `receipt`; save it and `timeline undo receipt.json` reverts it.\n\n<!-- history (trial): remove this block together with the command -->\n\n## Project history\n\nEvery write is kept and can be undone. At the start of a turn, `npx hyperframes history begin --who <you> --label \"<plan>\"`, then `history --since mine --who <you>` to see what the person changed; build on their edits. A check failed or they say it got worse: `history undo --who <you>`, never hand-edit back. End the turn with `history end`.\n\n<!-- /history (trial) -->\n\n## Render where\n\n| Need | Command |\n| --- | --- |\n| Local | `render --quality looks --output out.mp4` (`draft`, `delivery`) |\n| Reproducible container | `render --docker --strict --output out.mp4` |\n| Batch from variables | `render --batch rows.json --output \"renders/{name}.mp4\"` |\n| Hosted, no local Chrome or FFmpeg | `cloud render` (`references/cloud.md`) |\n| Your own AWS or GCP | `lambda render`, `cloudrun render` (`references/lambda.md`, `references/cloudrun.md`) |\n\nA 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (`HYPERFRAMES_RENDER_DETACHED=1`, its own group, output to a log) and wait with `until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done`, never `pgrep -f`, which matches its own loop and waits until the tool times out.\n\nAfter a verified render, send one `feedback --rating`, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: `references/feedback.md`.\n\n## When a command fails\n\n| Symptom | Fix |\n| --- | --- |\n| Chrome missing or won't start | `npx hyperframes browser ensure`; `doctor --json` always exits 0, gate on `.ok` |\n| A heavy page isn't ready in time | Raise `--timeout` on `check` or `snapshot` |\n| Unusual codec looks blank | Keep `--proxy` on (the default) |\n| Render slow on Linux | The summary's second line says `screenshot` + `software gpu`: the slow path |\n| `capture` fails or writes `BLOCKED.md` | Take nothing from its partial files; retry into a new `-o` folder |\n| Disk tight | `clean --dry-run`, then `clean`; never delete `.hyperframes` (it holds history) |\n\n## References\n\nRead the row before running its command.\n\n| Commands | Read |\n| --- | --- |\n| `init`, `capture`, `skills` | `references/init-and-scaffold.md` |\n| `lint`, `check`, motion sidecars, `snapshot` | `references/lint-validate-inspect.md` |\n| `compare`, `grade-compare`, `render --batch` | `references/compare-and-batch.md` |\n| `beats` | `references/beats.md` |\n| `preview`, `play`, `render`, `publish`, Studio context | `references/preview-render.md` |\n| `doctor`, `browser` | `references/doctor-browser.md` |\n| `auth`, `cloud`, template variables | `references/cloud.md` |\n| `lambda`, `cloudrun` | `references/lambda.md`, `references/cloudrun.md` |\n| `info`, `upgrade`, `compositions`, `timeline`, `docs`, `usage`, telemetry | `references/upgrade-info-misc.md` |\n| `--strict` flags, run ids, `clean`, shader lint, JSON paths | `references/conventions.md` |\n| `keyframes` | `../hyperframes/references/motion.md` (Seeing motion) |\n","frontmatter":{"name":"hyperframes-cli","description":"The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures."},"isInternal":false,"tokens":1865,"sizeBytes":7131},{"name":"README.md","path":"skills/hyperframes-registry/README.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/README.md","title":"Hyperframes-registry Skill","category":"anthropic-skill","format":"markdown","content":"# Hyperframes-registry Skill\n\nPath: `skills/hyperframes-registry/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/README.md)","tokens":300,"sizeBytes":206},{"name":"SKILL.md","path":"skills/hyperframes-registry/SKILL.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/SKILL.md","title":"hyperframes-registry","category":"anthropic-skill","format":"markdown","content":"---\nname: hyperframes-registry\ndescription: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames registry\n\nStarting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it.\n\n## Find and install\n\n```bash\nnpx hyperframes catalog --query \"<what the beat should do, in English>\" --json\nnpx hyperframes add <name> --json        # prints the written files and the mount snippet\n```\n\n- Query in English even when the video is not: the catalog is indexed in English, and another script returns `No searchable words in query`, which is not a gap.\n- Search is local and sends nothing. The default `words` tier only finds items that reuse your words; `--on-device` ranks by meaning after a one-time ~33 MB download. Offer that download and let the person decide; never enable it silently. The `--json` envelope names the tier that answered.\n- Narrow with `--type block|component` and `--tag <tag>`. `add <tag>` installs every block with that tag; dependencies install first. `add` needs the network even for an item installed before; search works offline from the cached manifest.\n- Nothing fits: report it before you hand-build, on either tier. `catalog --query` prints the line pre-filled (`report_gap` in `--json`): `npx hyperframes feedback --search-miss \"<query>\" --wanted \"<the move you needed>\" --tier <tier>`. Describe the effect, not an item name you imagined.\n\nTiers, `dropped` and `unindexed`, stale indexes, offline behaviour: `references/search.md`.\n\n## What's in it\n\n| Blocks: a scene with its own timeline | Examples |\n| --- | --- |\n| Transitions | `beat-freeze-cut`, `chromatic-radial-split`, `cinematic-zoom` |\n| Overlays and lower thirds | `camcorder-hud`, `editorial-flash-overlay`, `lt-clean-bar` |\n| Title cards and kinetic type | `canopy-part-title`, `code-slice-hero` |\n| Social, chat and UI cards | `ai-chat-reveal`, `chatgpt-exchange` |\n| Code, charts, data and maps | `code-diff`, `bar-chart-race`, `data-chart` |\n| 3D, shader and backgrounds | `app-showcase`, `aurora`, `blob` |\n\n| Components: a snippet merged into your scene | Examples |\n| --- | --- |\n| Motion primitives and text effects | `agent-cursor`, `blur-in`, `bottom-up-letters` |\n| Caption styles | `caption-clip-wipe`, `caption-editorial-emphasis` |\n| Camera moves | `camera-shake`, `camera-scan-gate` |\n| Product demo and UI props | `before-after-wipe`, `browser-device-stage` |\n| Textures, particles and effects | `ascii-render-pass`, `grain-overlay` |\n\n## Wiring\n\n- **Block**: installs to `compositions/<name>.html`. Mount it with `data-composition-src`, `data-composition-id` matching the block's own id, `data-start` and the `data-duration` you need; the snippet `add` prints is the starting point. `references/wiring-blocks.md`.\n- **Component**: installs to `compositions/components/<name>.html`. Copy its markup, `<style>` and script into your scene, and follow its comment block if it hooks into your timeline. `references/wiring-components.md`.\n- Take the largest unit that fits, then edit it. Keep an installed item's ids prefixed as they are, so two items can't collide.\n- An item keeps its own variables; set them for one mount with `data-variable-values` on its host (`add --vars '{\"title\":\"…\"}'` writes that), and point its colour and font variables at your brand's.\n- Beat-synced blocks take hit times from `npx hyperframes beats --json`: the beat times minus the mount's `data-start`.\n- Install paths come from `hyperframes.json` (`references/install-locations.md`).\n\n## Contributing\n\nAuthoring a new block or component for an upstream PR: `references/contributing.md`, starter templates in `references/templates.md`, quality bar in `references/component-quality-bar.md`.\n","frontmatter":{"name":"hyperframes-registry","description":"About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog."},"isInternal":false,"tokens":1018,"sizeBytes":4246},{"name":"README.md","path":"skills/hyperframes/README.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/README.md","title":"Hyperframes Skill","category":"anthropic-skill","format":"markdown","content":"# Hyperframes Skill\n\nPath: `skills/hyperframes/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/README.md)","tokens":300,"sizeBytes":179},{"name":"SKILL.md","path":"skills/hyperframes/SKILL.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/SKILL.md","title":"hyperframes","category":"anthropic-skill","format":"markdown","content":"---\nname: hyperframes\ndescription: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames\n\nHyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes <command>` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say \"unknown\" when it is).\n\n`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init <dir>`. A website as the subject: `npx hyperframes capture <url> --json`.\n\nBuild what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none.\n\n## Contract\n\n`npx hyperframes check --json` reports most violations with a `Fix:` line.\n\n1. Every timed element has `class=\"clip\"`, `data-start` and `data-duration` in seconds, and shows over `[start, start + duration)`: land an end state just before its end. `data-track-index` is only a Studio lane; paint order is `z-index`.\n2. The video's length is the root's `data-duration`: overrun is cut, an early end holds the last frame.\n3. Each composition builds one paused timeline and registers it after its tweens: `window.__timelines[\"<data-composition-id>\"] = tl`.\n4. No `Date.now()`, unseeded `Math.random()`, network fetches, timers or `repeat: -1`. Everything visible is a function of timeline time.\n5. Never tween `display`, `visibility` or `autoAlpha` on a `.clip`; animate a child.\n6. No CSS `transform` on an element GSAP transforms; animate transforms, not `left`/`top`/`width`/`height`.\n7. Never `play()`, `pause()` or seek media. A `<video>` keeps its sound with `data-has-audio=\"true\"`, else it is `muted`; music, voice, replacement sound and J/L cuts are a separate `<audio>`.\n8. Every `<audio>` has an `id` or it is left out of the mix. No `crossorigin` on media. Time a `<video>` or its wrapper, never both.\n9. Only the bundled fonts (`references/format.md`) resolve by name; any other family needs `@font-face` to a file in `assets/fonts/`.\n10. Asset paths are root-relative (`assets/...`), in sub-compositions too.\n11. Grades, grain, blur and vignettes on footage go through `npx hyperframes media-treatment` (`/media-use`), never CSS filters.\n12. A scene file puts its styles, markup and scripts inside `<template>` and styles its root as `#root`. Intended overflow or overlap: `data-layout-allow-overflow`, `data-layout-allow-overlap`.\n\n## Keep it editable\n\nStudio edits the tags you write.\n\n- One scene per sub-composition, short readable ids; the root holds only scene hosts, media and audio.\n- Timed elements are written in the HTML, not made by script, each with a stable `id`.\n- Copy, brand colours and swappable media are variables (`data-var-text`, `data-var-src`, `var(--id)`).\n- One kind per track: `data-track-kind=\"graphics\"` on scene and overlay hosts, `captions` on the one host that holds every caption group.\n- Content stays inside the 90% action-safe box, captions and key text inside 80% title-safe; Studio draws the guides, never add them.\n\n## Work loop\n\n- An existing project: `npx hyperframes timeline --json` shows what plays when; before any change, `npx hyperframes history --since mine --who <you>` shows what the person changed since your last turn: build on it (`/hyperframes-cli`).\n- A new film over ~15 s that tells something: its type's file (below), then `references/story.md`: three storylines that are three different films, in words only; the person picks unless they asked for the file or no stops. Then `SPEC.md` (`references/spec.md`): every adjective as a number, the defaults banned by name, the shots by frame.\n- After your last edit: `npx hyperframes check --json`; fix every error, weigh every warning. A film: `npx hyperframes snapshot --review` and `references/review.md`, ending in `REVIEW.md`. A small edit: snapshot what you changed (`--at`, `--range`, `--composition`) and look before you reply.\n- Render when the person approves the Studio preview, asks for the file or asks for no stops, after your check and review pass; otherwise stop at the preview and wait.\n\n## The HyperFrames desktop app\n\nCall it \"the HyperFrames desktop app\", never \"Studio\"; offer it as the better way to keep editing, not the only one.\n\n- Before the delivery render of a new video, open the Studio preview, even in no-questions mode, and say they can edit there. If `preview` printed \"Keep editing by chatting with Framey\", add that the **Edit with Framey** button opens the app.\n- After the delivery render, pass on its Framey line in your own words: offer to run the `hyperframes open` it names or give its download link; else say nothing (autonomous: the delivery note).\n- When any command says to run `catch-up`, run `npx hyperframes catch-up [dir]` before your next change; what it lists is their work, not a new request.\n\n## What to read\n\n| The request | Read |\n| --- | --- |\n| Launch, promo, feature | `references/types/launch.md` |\n| Explainer, tutorial | `references/types/explainer.md` |\n| Music video | `references/types/music.md` |\n| Chart, numbers | `references/types/data.md` |\n| Vertical or social clip | `references/types/vertical.md` |\n| 3D, simulation, generative | `references/types/3d.md` |\n| Character, mascot, story short | `references/types/character.md` |\n| A real place or map; a website, PR or script; kinetic type | `references/film.md` |\n| Captions; cards over a talking head | `references/captions.md`; `references/overlays.md` |\n| Motion: eases, titles, cuts, punch-ins, speed, holds | `references/motion.md` |\n| Scenes, attributes, media, lint; GSAP, Lottie, 3D, canvas | `references/format.md`; `references/runtimes.md` |\n\nDecks: `/slideshow`. Remotion source: `/remotion-to-hyperframes`. Figma: `/figma`. Installing, refreshing or upgrading skills and the pinned CLI: `references/skill-lifecycle.md`.\n","frontmatter":{"name":"hyperframes","description":"Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs."},"isInternal":false,"tokens":1757,"sizeBytes":7167},{"name":"README.md","path":"skills/media-use/README.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/README.md","title":"Media-use Skill","category":"anthropic-skill","format":"markdown","content":"# Media-use Skill\n\nPath: `skills/media-use/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/README.md)","tokens":300,"sizeBytes":173},{"name":"SKILL.md","path":"skills/media-use/SKILL.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/SKILL.md","title":"media-use","category":"anthropic-skill","format":"markdown","content":"---\nname: media-use\ndescription: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# Media in HyperFrames\n\nMedia lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it:\n\n```bash\nnpx hyperframes media-use resolve --type <type> --intent \"<what you need>\" --project <dir>\n```\n\nIt prints one line, `resolved <id> → <path> (<type>, <metadata>)`. List reusable assets first with `--candidates` and judge the fit yourself; reuse, ingest (`--from`) and adopt are in `references/resolve.md`.\n\n## Two ways to get it\n\n| Need | HeyGen (best quality) | Free, no account |\n| --- | --- | --- |\n| Music (`bgm`) | Catalog of 10k+ tracks | Local MusicGen (`audio/references/bgm.md`) |\n| Sound effects (`sfx`) | | Openverse; 21 bundled offline |\n| Images, icons | Asset search, 75k+ | Local FLUX (mflux), if installed |\n| Logos (`logo`) | | theSVG, GitHub avatar, favicon; never redrawn |\n| Voiceover (`voice`) | HeyGen voices, voice cloning | `npx hyperframes tts` (Kokoro on device; Python 3.10+ with `pip install kokoro-onnx soundfile`) |\n| A presenter speaking | Avatar video (`--type video`) | Local LTX for generic clips, if installed |\n| Transcripts | | `npx hyperframes transcribe` (Parakeet or whisper) |\n| Cutouts | `heygen background-removal` | `npx hyperframes remove-background` |\n| Grades, LUTs, looks | | `npx hyperframes media-treatment` |\n\n**Host apps.** Inside an app that gives you its own media tools, use those first. When `HEYGEN_API_BASE` is set, the host pays for HeyGen: don't ask for the `heygen` CLI or a sign-in, and when a call is refused, relay the host's message as written and stop.\n\n**HeyGen.** Install the [`heygen` CLI](https://developers.heygen.com/cli) and sign in with `heygen auth login --oauth`: the OAuth session carries a free allowance on subscription credits; an API key (`--api-key`) bills API credits. Check setup with `npx hyperframes media-use resolve --doctor`. When a request needs HeyGen (a presenter or avatar, a HeyGen voice, catalog music) and `heygen` is missing or signed out, tell the person how to get it: the install link, `heygen auth login --oauth` for the free allowance, or an API key for credits. Then offer the free path or wait. Beyond `resolve`, the same CLI makes text-to-video (`heygen video-agent create`), avatar videos with a recorded track (`heygen video create`), cloned voices (`heygen voice clone create`), dubbing (`heygen lipsync`), translated videos (`heygen video-translate`) and short clips from a long video (`heygen ai-clipping`): recipes in `references/operations.md`.\n\n**Free.** Every tool in the free column needs no account; local models are opt-in installs (`references/setup-providers.md`). Without `heygen`, `resolve` for music, images and icons fails and says so; credit CC BY sounds (`audio/references/sfx.md`). `--local-only` skips every network provider.\n\n**Cost.** Confirm before a paid call you chose to make (an avatar video counts); one the person asked for just runs. `--provider <name>` pins one generator when the person names it.\n\n## Looks on real footage\n\nFeedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent: read `references/media-treatments.md`. Inspect the real `<img>`/`<video>`, pick one intent, start from `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>`; never `--all`. Persist the final treatment with `npx hyperframes media-treatment`; no CSS or SVG stand-ins for supported effects, and no generated `.cube` just to encode exposure or warmth.\n\n## Offer once, never add silently\n\nWhen you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect \"leave it\".\n\n## Where to look\n\n| Task | Read |\n| --- | --- |\n| Resolve, reuse, adopt, ingest, flags | `references/resolve.md` |\n| Grading, LUTs, `grade-compare` | `references/grading.md` |\n| Voiceover, music, sound effects, captions, transcription | `references/audio.md` |\n| Cut, reframe or transform media; HeyGen recipes | `references/operations.md` |\n| Treatments, realtime effects, overlays, reveals | `references/media-treatments.md` |\n| Install, sign-in, providers, RAM ladders | `references/setup-providers.md` |\n| Fades, gain, ducking, automation, effects, buses on placed tracks | `references/mixing.md` |\n| Local commands: grade, cutout, loudness, beats | `references/local.md` |\n| Remembered preferences | `references/memory.md` |\n","frontmatter":{"name":"media-use","description":"Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden."},"isInternal":false,"tokens":1276,"sizeBytes":5120},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships 7 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Install all 7 only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update                         # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                                # all 7 published skills at once — only on explicit request\nnpx skills add heygen-com/hyperframes                 # interactive picker; internal skills require INSTALL_INTERNAL_SKILLS=1 for discovery\nnpx skills add heygen-com/hyperframes --all           # excludes internal skills unless INSTALL_INTERNAL_SKILLS=1\nnpx skills add heygen-com/hyperframes --skill <name>  # a named match installs regardless of metadata.internal (bare name, no leading slash)\n```\n\n> **Warning:** Never run `npx skills add ... --all` from inside a HyperFrames checkout: it selects the OpenClaw target, whose `skills/` directory is the repo's own `skills/`, and removes each existing `skills/<name>` destination before linking. A fresh clone restores tracked source, but uncommitted work under `skills/` does not recover. Run it from an empty directory or from your own project root. This happens regardless of `metadata.internal`.\n\n`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters.\n\nMake any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see \"Skill catalog maintenance\" below).\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks) with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.\n- `/slideshow` — a presentation, pitch deck or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation and presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Skill catalog maintenance\n\nWhen adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:\n\n1. The skill list above (CLAUDE.md) AND the skill list in the root `AGENTS.md` AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup pages that compress the same descriptions — `docs/prompting/overview.mdx` (\"One-time setup\") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill.\n2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical.\n3. The routing surface for \"make a video\" requests is the References table and closing line of `skills/hyperframes/SKILL.md`. A new reference or skill that a request should reach gets a row or a mention there.\n4. Keep the same grouping on every surface: the core set (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`) first, then the on-demand skills (`/figma`, `/slideshow`, `/remotion-to-hyperframes`).\n5. Skill count appears in the README and CLAUDE.md intro lines (\"7 AI agent skills…\") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.\n\nThe skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line \"use when\" blurb; copy from there into the catalog rather than paraphrasing.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n","isInternal":false,"tokens":2065,"sizeBytes":9026},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.github/copilot-instructions.md)","tokens":300,"sizeBytes":195},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":201},{"name":"marketplace.json","path":"marketplace.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/marketplace.json)","tokens":300,"sizeBytes":171},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":187},{"name":"plugin.json","path":"plugin.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/plugin.json","title":"Plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/plugin.json)","tokens":300,"sizeBytes":150},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":180},{"name":"mcp.json","path":"mcp.json","rawUrl":"https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/mcp.json)","tokens":300,"sizeBytes":164}],"systemPromptSnippet":"<yakaai_skills repo=\"heygen-com/hyperframes\">\n<!-- File: AGENTS.md (Tokens: ~1549 | Category: root-instruction) -->\n# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); install everything only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update           # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                  # all 7 published skills at once\nnpx skills add heygen-com/hyperframes   # interactive picker (terminal only; repo-internal skills are excluded by default)\n```\n\nMake any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first.\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, voiceover, avatar and generated video, transcripts, cutouts, colour grades) with HeyGen or free local tools, and mix placed audio.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion.\n- `/slideshow` — a presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Issue and PR triage\n\nRead [TRIAGE.md](TRIAGE.md) before classifying issues, advertising contribution work, or triaging PRs. Check current source and overlapping PRs; keep difficulty, readiness, and ownership separate. Apply changes only within the task's authorization and verify the resulting GitHub state.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\nPackages load each other through their `exports`. Under Node, core, parsers,\nlint and studio-server resolve to `dist/`, and player always loads its built\nbundle. Run `bun run build` once in a fresh worktree, before any package's\ntests or typecheck. After editing a package that another package imports, run\nthat package's `build` again before the dependent package's tests. Core's\n`src/generated/` is git-ignored build output: if you see\n`Cannot find module '../generated/runtime-inline'`, run\n`bun run build:hyperframes-runtime`.\n\nOne file: `bun run --cwd packages/<pkg> test <path>`. Each package's `test`\nscript picks its runner (vitest in most, `bun test` in aws-lambda and\ngcp-cloud-run). Producer is the exception: a file that imports `bun:test` runs\nwith `bun test <file>`, any other with `bunx vitest run <file>`. Root `scripts/*.test.mjs` run through `bun run test:scripts`,\nwhich is an explicit list in `package.json`. CI's test-reachability check fails\nany test file that no runner reaches.\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n\n<!-- File: skills/hyperframes-cli/README.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Hyperframes-cli Skill\n\nPath: `skills/hyperframes-cli/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-cli/README.md)\n\n<!-- File: skills/hyperframes-cli/SKILL.md (Tokens: ~1865 | Category: anthropic-skill) -->\n---\nname: hyperframes-cli\ndescription: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames CLI\n\nRun `npx hyperframes <command>` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero.\n\n## Commands by job\n\n| Job | Commands |\n| --- | --- |\n| Start | `init <dir>` (blank; `--example <name>` only when asked), `capture <url>` |\n| Read a project | `info`, `compositions`, `timeline --json`, `docs <topic>` |\n| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) |\n| Look at it | `snapshot` (`--at <t,…>`, `--range START,END`, `--composition <id>`, `--zoom`, `--angle`, `--against <video>`), `keyframes`, `compare`, `audio` |\n| Edit the timeline | `timeline` with `move`, `trim`, `split`, `set`, `duplicate`, `delete`, `apply`, `undo`, `ids` |\n| Reuse | `catalog`, `add` (`/hyperframes-registry`) |\n| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |\n| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |\n| Desktop app | `open`, `catch-up` |\n| Upkeep | `doctor`, `browser`, `upgrade`, `skills`, `usage`, `clean`, `feedback` |\n\n`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.\n\n## The loop\n\n1. Write, then `npx hyperframes lint` after the first pass and after structural changes.\n2. `npx hyperframes check --json` and fix every error. While a lint error remains the layout and contrast audits don't run; \"0 samples\" means nothing was checked. Contrast failures carry a `suggestedColor`. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails `sweep_static`.\n3. `npx hyperframes snapshot` and read the PNGs (under `.hyperframes/artifacts/snapshots/`): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (`../hyperframes/references/format.md`).\n4. `npx hyperframes preview --background`, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.\n5. When it is time to render (step 4): `npx hyperframes render --quality looks --output out.mp4` (`draft` while iterating, `delivery` for the final). Confirm the file is non-empty and its `ffprobe` duration matches the root `data-duration`, then look at decoded frames.\n\n\"This element\" or the current selection: `npx hyperframes preview --context --json --context-fields selection`; `no-selection` means ask them to click it.\n\n## Edit the timeline\n\nThese are the edits Studio itself makes, so the result stays in Studio's shape.\n\n- `timeline --json` lists clips with absolute `absStart`/`absEnd`, owning `file` and the `#id` ref the edit commands take (`timeline ids` stamps missing ids).\n- `timeline move|trim|split|set|duplicate|delete <ref> … --plan --json` previews one edit; run it again without `--plan`. `--start`, `--end`, `--duration` set one edge or the length.\n- An edit is refused when the clip would overlap a neighbour (`--overwrite`, or move the neighbour first) or end past its composition: raise the root's `data-duration` first. No command changes `data-duration`.\n- Several edits at once: a JSON file such as `[{\"verb\": \"move\", \"ref\": \"#outro\", \"time\": \"9\"}]`, then `timeline apply plan.json --json`. Each run prints a `receipt`; save it and `timeline undo receipt.json` reverts it.\n\n<!-- history (trial): remove this block together with the command -->\n\n## Project history\n\nEvery write is kept and can be undone. At the start of a turn, `npx hyperframes history begin --who <you> --label \"<plan>\"`, then `history --since mine --who <you>` to see what the person changed; build on their edits. A check failed or they say it got worse: `history undo --who <you>`, never hand-edit back. End the turn with `history end`.\n\n<!-- /history (trial) -->\n\n## Render where\n\n| Need | Command |\n| --- | --- |\n| Local | `render --quality looks --output out.mp4` (`draft`, `delivery`) |\n| Reproducible container | `render --docker --strict --output out.mp4` |\n| Batch from variables | `render --batch rows.json --output \"renders/{name}.mp4\"` |\n| Hosted, no local Chrome or FFmpeg | `cloud render` (`references/cloud.md`) |\n| Your own AWS or GCP | `lambda render`, `cloudrun render` (`references/lambda.md`, `references/cloudrun.md`) |\n\nA 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (`HYPERFRAMES_RENDER_DETACHED=1`, its own group, output to a log) and wait with `until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done`, never `pgrep -f`, which matches its own loop and waits until the tool times out.\n\nAfter a verified render, send one `feedback --rating`, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: `references/feedback.md`.\n\n## When a command fails\n\n| Symptom | Fix |\n| --- | --- |\n| Chrome missing or won't start | `npx hyperframes browser ensure`; `doctor --json` always exits 0, gate on `.ok` |\n| A heavy page isn't ready in time | Raise `--timeout` on `check` or `snapshot` |\n| Unusual codec looks blank | Keep `--proxy` on (the default) |\n| Render slow on Linux | The summary's second line says `screenshot` + `software gpu`: the slow path |\n| `capture` fails or writes `BLOCKED.md` | Take nothing from its partial files; retry into a new `-o` folder |\n| Disk tight | `clean --dry-run`, then `clean`; never delete `.hyperframes` (it holds history) |\n\n## References\n\nRead the row before running its command.\n\n| Commands | Read |\n| --- | --- |\n| `init`, `capture`, `skills` | `references/init-and-scaffold.md` |\n| `lint`, `check`, motion sidecars, `snapshot` | `references/lint-validate-inspect.md` |\n| `compare`, `grade-compare`, `render --batch` | `references/compare-and-batch.md` |\n| `beats` | `references/beats.md` |\n| `preview`, `play`, `render`, `publish`, Studio context | `references/preview-render.md` |\n| `doctor`, `browser` | `references/doctor-browser.md` |\n| `auth`, `cloud`, template variables | `references/cloud.md` |\n| `lambda`, `cloudrun` | `references/lambda.md`, `references/cloudrun.md` |\n| `info`, `upgrade`, `compositions`, `timeline`, `docs`, `usage`, telemetry | `references/upgrade-info-misc.md` |\n| `--strict` flags, run ids, `clean`, shader lint, JSON paths | `references/conventions.md` |\n| `keyframes` | `../hyperframes/references/motion.md` (Seeing motion) |\n\n<!-- File: skills/hyperframes-registry/README.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Hyperframes-registry Skill\n\nPath: `skills/hyperframes-registry/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes-registry/README.md)\n\n<!-- File: skills/hyperframes-registry/SKILL.md (Tokens: ~1018 | Category: anthropic-skill) -->\n---\nname: hyperframes-registry\ndescription: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames registry\n\nStarting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it.\n\n## Find and install\n\n```bash\nnpx hyperframes catalog --query \"<what the beat should do, in English>\" --json\nnpx hyperframes add <name> --json        # prints the written files and the mount snippet\n```\n\n- Query in English even when the video is not: the catalog is indexed in English, and another script returns `No searchable words in query`, which is not a gap.\n- Search is local and sends nothing. The default `words` tier only finds items that reuse your words; `--on-device` ranks by meaning after a one-time ~33 MB download. Offer that download and let the person decide; never enable it silently. The `--json` envelope names the tier that answered.\n- Narrow with `--type block|component` and `--tag <tag>`. `add <tag>` installs every block with that tag; dependencies install first. `add` needs the network even for an item installed before; search works offline from the cached manifest.\n- Nothing fits: report it before you hand-build, on either tier. `catalog --query` prints the line pre-filled (`report_gap` in `--json`): `npx hyperframes feedback --search-miss \"<query>\" --wanted \"<the move you needed>\" --tier <tier>`. Describe the effect, not an item name you imagined.\n\nTiers, `dropped` and `unindexed`, stale indexes, offline behaviour: `references/search.md`.\n\n## What's in it\n\n| Blocks: a scene with its own timeline | Examples |\n| --- | --- |\n| Transitions | `beat-freeze-cut`, `chromatic-radial-split`, `cinematic-zoom` |\n| Overlays and lower thirds | `camcorder-hud`, `editorial-flash-overlay`, `lt-clean-bar` |\n| Title cards and kinetic type | `canopy-part-title`, `code-slice-hero` |\n| Social, chat and UI cards | `ai-chat-reveal`, `chatgpt-exchange` |\n| Code, charts, data and maps | `code-diff`, `bar-chart-race`, `data-chart` |\n| 3D, shader and backgrounds | `app-showcase`, `aurora`, `blob` |\n\n| Components: a snippet merged into your scene | Examples |\n| --- | --- |\n| Motion primitives and text effects | `agent-cursor`, `blur-in`, `bottom-up-letters` |\n| Caption styles | `caption-clip-wipe`, `caption-editorial-emphasis` |\n| Camera moves | `camera-shake`, `camera-scan-gate` |\n| Product demo and UI props | `before-after-wipe`, `browser-device-stage` |\n| Textures, particles and effects | `ascii-render-pass`, `grain-overlay` |\n\n## Wiring\n\n- **Block**: installs to `compositions/<name>.html`. Mount it with `data-composition-src`, `data-composition-id` matching the block's own id, `data-start` and the `data-duration` you need; the snippet `add` prints is the starting point. `references/wiring-blocks.md`.\n- **Component**: installs to `compositions/components/<name>.html`. Copy its markup, `<style>` and script into your scene, and follow its comment block if it hooks into your timeline. `references/wiring-components.md`.\n- Take the largest unit that fits, then edit it. Keep an installed item's ids prefixed as they are, so two items can't collide.\n- An item keeps its own variables; set them for one mount with `data-variable-values` on its host (`add --vars '{\"title\":\"…\"}'` writes that), and point its colour and font variables at your brand's.\n- Beat-synced blocks take hit times from `npx hyperframes beats --json`: the beat times minus the mount's `data-start`.\n- Install paths come from `hyperframes.json` (`references/install-locations.md`).\n\n## Contributing\n\nAuthoring a new block or component for an upstream PR: `references/contributing.md`, starter templates in `references/templates.md`, quality bar in `references/component-quality-bar.md`.\n\n<!-- File: skills/hyperframes/README.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Hyperframes Skill\n\nPath: `skills/hyperframes/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/hyperframes/README.md)\n\n<!-- File: skills/hyperframes/SKILL.md (Tokens: ~1757 | Category: anthropic-skill) -->\n---\nname: hyperframes\ndescription: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# HyperFrames\n\nHyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes <command>` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say \"unknown\" when it is).\n\n`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init <dir>`. A website as the subject: `npx hyperframes capture <url> --json`.\n\nBuild what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none.\n\n## Contract\n\n`npx hyperframes check --json` reports most violations with a `Fix:` line.\n\n1. Every timed element has `class=\"clip\"`, `data-start` and `data-duration` in seconds, and shows over `[start, start + duration)`: land an end state just before its end. `data-track-index` is only a Studio lane; paint order is `z-index`.\n2. The video's length is the root's `data-duration`: overrun is cut, an early end holds the last frame.\n3. Each composition builds one paused timeline and registers it after its tweens: `window.__timelines[\"<data-composition-id>\"] = tl`.\n4. No `Date.now()`, unseeded `Math.random()`, network fetches, timers or `repeat: -1`. Everything visible is a function of timeline time.\n5. Never tween `display`, `visibility` or `autoAlpha` on a `.clip`; animate a child.\n6. No CSS `transform` on an element GSAP transforms; animate transforms, not `left`/`top`/`width`/`height`.\n7. Never `play()`, `pause()` or seek media. A `<video>` keeps its sound with `data-has-audio=\"true\"`, else it is `muted`; music, voice, replacement sound and J/L cuts are a separate `<audio>`.\n8. Every `<audio>` has an `id` or it is left out of the mix. No `crossorigin` on media. Time a `<video>` or its wrapper, never both.\n9. Only the bundled fonts (`references/format.md`) resolve by name; any other family needs `@font-face` to a file in `assets/fonts/`.\n10. Asset paths are root-relative (`assets/...`), in sub-compositions too.\n11. Grades, grain, blur and vignettes on footage go through `npx hyperframes media-treatment` (`/media-use`), never CSS filters.\n12. A scene file puts its styles, markup and scripts inside `<template>` and styles its root as `#root`. Intended overflow or overlap: `data-layout-allow-overflow`, `data-layout-allow-overlap`.\n\n## Keep it editable\n\nStudio edits the tags you write.\n\n- One scene per sub-composition, short readable ids; the root holds only scene hosts, media and audio.\n- Timed elements are written in the HTML, not made by script, each with a stable `id`.\n- Copy, brand colours and swappable media are variables (`data-var-text`, `data-var-src`, `var(--id)`).\n- One kind per track: `data-track-kind=\"graphics\"` on scene and overlay hosts, `captions` on the one host that holds every caption group.\n- Content stays inside the 90% action-safe box, captions and key text inside 80% title-safe; Studio draws the guides, never add them.\n\n## Work loop\n\n- An existing project: `npx hyperframes timeline --json` shows what plays when; before any change, `npx hyperframes history --since mine --who <you>` shows what the person changed since your last turn: build on it (`/hyperframes-cli`).\n- A new film over ~15 s that tells something: its type's file (below), then `references/story.md`: three storylines that are three different films, in words only; the person picks unless they asked for the file or no stops. Then `SPEC.md` (`references/spec.md`): every adjective as a number, the defaults banned by name, the shots by frame.\n- After your last edit: `npx hyperframes check --json`; fix every error, weigh every warning. A film: `npx hyperframes snapshot --review` and `references/review.md`, ending in `REVIEW.md`. A small edit: snapshot what you changed (`--at`, `--range`, `--composition`) and look before you reply.\n- Render when the person approves the Studio preview, asks for the file or asks for no stops, after your check and review pass; otherwise stop at the preview and wait.\n\n## The HyperFrames desktop app\n\nCall it \"the HyperFrames desktop app\", never \"Studio\"; offer it as the better way to keep editing, not the only one.\n\n- Before the delivery render of a new video, open the Studio preview, even in no-questions mode, and say they can edit there. If `preview` printed \"Keep editing by chatting with Framey\", add that the **Edit with Framey** button opens the app.\n- After the delivery render, pass on its Framey line in your own words: offer to run the `hyperframes open` it names or give its download link; else say nothing (autonomous: the delivery note).\n- When any command says to run `catch-up`, run `npx hyperframes catch-up [dir]` before your next change; what it lists is their work, not a new request.\n\n## What to read\n\n| The request | Read |\n| --- | --- |\n| Launch, promo, feature | `references/types/launch.md` |\n| Explainer, tutorial | `references/types/explainer.md` |\n| Music video | `references/types/music.md` |\n| Chart, numbers | `references/types/data.md` |\n| Vertical or social clip | `references/types/vertical.md` |\n| 3D, simulation, generative | `references/types/3d.md` |\n| Character, mascot, story short | `references/types/character.md` |\n| A real place or map; a website, PR or script; kinetic type | `references/film.md` |\n| Captions; cards over a talking head | `references/captions.md`; `references/overlays.md` |\n| Motion: eases, titles, cuts, punch-ins, speed, holds | `references/motion.md` |\n| Scenes, attributes, media, lint; GSAP, Lottie, 3D, canvas | `references/format.md`; `references/runtimes.md` |\n\nDecks: `/slideshow`. Remotion source: `/remotion-to-hyperframes`. Figma: `/figma`. Installing, refreshing or upgrading skills and the pinned CLI: `references/skill-lifecycle.md`.\n\n<!-- File: skills/media-use/README.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Media-use Skill\n\nPath: `skills/media-use/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/skills/media-use/README.md)\n\n<!-- File: skills/media-use/SKILL.md (Tokens: ~1276 | Category: anthropic-skill) -->\n---\nname: media-use\ndescription: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.\n\n# Media in HyperFrames\n\nMedia lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it:\n\n```bash\nnpx hyperframes media-use resolve --type <type> --intent \"<what you need>\" --project <dir>\n```\n\nIt prints one line, `resolved <id> → <path> (<type>, <metadata>)`. List reusable assets first with `--candidates` and judge the fit yourself; reuse, ingest (`--from`) and adopt are in `references/resolve.md`.\n\n## Two ways to get it\n\n| Need | HeyGen (best quality) | Free, no account |\n| --- | --- | --- |\n| Music (`bgm`) | Catalog of 10k+ tracks | Local MusicGen (`audio/references/bgm.md`) |\n| Sound effects (`sfx`) | | Openverse; 21 bundled offline |\n| Images, icons | Asset search, 75k+ | Local FLUX (mflux), if installed |\n| Logos (`logo`) | | theSVG, GitHub avatar, favicon; never redrawn |\n| Voiceover (`voice`) | HeyGen voices, voice cloning | `npx hyperframes tts` (Kokoro on device; Python 3.10+ with `pip install kokoro-onnx soundfile`) |\n| A presenter speaking | Avatar video (`--type video`) | Local LTX for generic clips, if installed |\n| Transcripts | | `npx hyperframes transcribe` (Parakeet or whisper) |\n| Cutouts | `heygen background-removal` | `npx hyperframes remove-background` |\n| Grades, LUTs, looks | | `npx hyperframes media-treatment` |\n\n**Host apps.** Inside an app that gives you its own media tools, use those first. When `HEYGEN_API_BASE` is set, the host pays for HeyGen: don't ask for the `heygen` CLI or a sign-in, and when a call is refused, relay the host's message as written and stop.\n\n**HeyGen.** Install the [`heygen` CLI](https://developers.heygen.com/cli) and sign in with `heygen auth login --oauth`: the OAuth session carries a free allowance on subscription credits; an API key (`--api-key`) bills API credits. Check setup with `npx hyperframes media-use resolve --doctor`. When a request needs HeyGen (a presenter or avatar, a HeyGen voice, catalog music) and `heygen` is missing or signed out, tell the person how to get it: the install link, `heygen auth login --oauth` for the free allowance, or an API key for credits. Then offer the free path or wait. Beyond `resolve`, the same CLI makes text-to-video (`heygen video-agent create`), avatar videos with a recorded track (`heygen video create`), cloned voices (`heygen voice clone create`), dubbing (`heygen lipsync`), translated videos (`heygen video-translate`) and short clips from a long video (`heygen ai-clipping`): recipes in `references/operations.md`.\n\n**Free.** Every tool in the free column needs no account; local models are opt-in installs (`references/setup-providers.md`). Without `heygen`, `resolve` for music, images and icons fails and says so; credit CC BY sounds (`audio/references/sfx.md`). `--local-only` skips every network provider.\n\n**Cost.** Confirm before a paid call you chose to make (an avatar video counts); one the person asked for just runs. `--provider <name>` pins one generator when the person names it.\n\n## Looks on real footage\n\nFeedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent: read `references/media-treatments.md`. Inspect the real `<img>`/`<video>`, pick one intent, start from `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>`; never `--all`. Persist the final treatment with `npx hyperframes media-treatment`; no CSS or SVG stand-ins for supported effects, and no generated `.cube` just to encode exposure or warmth.\n\n## Offer once, never add silently\n\nWhen you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect \"leave it\".\n\n## Where to look\n\n| Task | Read |\n| --- | --- |\n| Resolve, reuse, adopt, ingest, flags | `references/resolve.md` |\n| Grading, LUTs, `grade-compare` | `references/grading.md` |\n| Voiceover, music, sound effects, captions, transcription | `references/audio.md` |\n| Cut, reframe or transform media; HeyGen recipes | `references/operations.md` |\n| Treatments, realtime effects, overlays, reveals | `references/media-treatments.md` |\n| Install, sign-in, providers, RAM ladders | `references/setup-providers.md` |\n| Fades, gain, ducking, automation, effects, buses on placed tracks | `references/mixing.md` |\n| Local commands: grade, cutout, loudness, beats | `references/local.md` |\n| Remembered preferences | `references/memory.md` |\n\n<!-- File: CLAUDE.md (Tokens: ~2065 | Category: claude-rule) -->\n# Hyperframes\n\nOpen-source video rendering framework: write HTML, render video.\n\n## Skills\n\nThis repo ships 7 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. **Default to the core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`); `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Install all 7 only when the user explicitly asks for the full set.\n\n```bash\nnpx hyperframes skills update                         # default: installs/refreshes the core set plus anything already installed\nnpx hyperframes skills                                # all 7 published skills at once — only on explicit request\nnpx skills add heygen-com/hyperframes                 # interactive picker; internal skills require INSTALL_INTERNAL_SKILLS=1 for discovery\nnpx skills add heygen-com/hyperframes --all           # excludes internal skills unless INSTALL_INTERNAL_SKILLS=1\nnpx skills add heygen-com/hyperframes --skill <name>  # a named match installs regardless of metadata.internal (bare name, no leading slash)\n```\n\n> **Warning:** Never run `npx skills add ... --all` from inside a HyperFrames checkout: it selects the OpenClaw target, whose `skills/` directory is the repo's own `skills/`, and removes each existing `skills/<name>` destination before linking. A fresh clone restores tracked source, but uncommitted work under `skills/` does not recover. Run it from an empty directory or from your own project root. This happens regardless of `metadata.internal`.\n\n`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters.\n\nMake any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see \"Skill catalog maintenance\" below).\n\n- `/hyperframes` — read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards.\n- `/hyperframes-cli` — the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures.\n- `/hyperframes-registry` — about 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`.\n- `/media-use` — get or make any media for a video (music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks) with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.\n- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.\n- `/slideshow` — a presentation, pitch deck or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation and presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4.\n- `/remotion-to-hyperframes` — bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original.\n\n## Skill catalog maintenance\n\nWhen adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:\n\n1. The skill list above (CLAUDE.md) AND the skill list in the root `AGENTS.md` AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup pages that compress the same descriptions — `docs/prompting/overview.mdx` (\"One-time setup\") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill.\n2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical.\n3. The routing surface for \"make a video\" requests is the References table and closing line of `skills/hyperframes/SKILL.md`. A new reference or skill that a request should reach gets a row or a mention there.\n4. Keep the same grouping on every surface: the core set (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`) first, then the on-demand skills (`/figma`, `/slideshow`, `/remotion-to-hyperframes`).\n5. Skill count appears in the README and CLAUDE.md intro lines (\"7 AI agent skills…\") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.\n\nThe skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line \"use when\" blurb; copy from there into the catalog rather than paraphrasing.\n\n## Build & Test\n\n```bash\nbun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)\nbun run build   # Build all packages\nbun run test    # Run all tests\n```\n\n### Linting & Formatting\n\nUses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).\n\n```bash\nnode_modules/.bin/oxlint <files>        # Lint\nnode_modules/.bin/oxfmt <files>         # Format\nnode_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)\n```\n\nAlways lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.\n\n### Composition Validation\n\nAfter creating or editing any `.html` composition:\n\n```bash\nnpx hyperframes lint       # Static HTML structure check\nnpx hyperframes check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)\n```\n\nBoth must pass before previewing or considering work complete.\n\n## Project Structure\n\n```\npackages/\n  cli/                  → hyperframes CLI (create, preview, lint, render)\n  core/                 → Types, parsers, generators, linter, runtime, frame adapters\n  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)\n  player/               → Embeddable <hyperframes-player> web component\n  producer/             → Full rendering pipeline (capture + encode + audio mix)\n  shader-transitions/   → WebGL shader transitions for compositions\n  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)\nregistry/\n  blocks/               → Installable sub-composition scenes (50+)\n  components/           → Installable effects and snippets\n  examples/             → Starter project templates\ndocs/                   → Mintlify documentation site (hyperframes.heygen.com)\nskills/                 → AI agent skill definitions\n```\n\n## Key Conventions\n\n- **Package manager**: bun (not pnpm, not npm for workspace operations)\n- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)\n- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing.\n- **Compositions**: HTML files with `data-*` attributes. Clips need `class=\"clip\"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.\n- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.\n- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.\n- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in \"Find your command\" in `docs/packages/cli.mdx` (CI checks it).\n\n## Documentation\n\n- Docs: https://hyperframes.heygen.com/introduction\n- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~300 | Category: copilot-instructions) -->\n# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.github/copilot-instructions.md)\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/.cursor/mcp.json)\n\n<!-- File: mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/heygen-com/hyperframes/HEAD/mcp.json)\n</yakaai_skills>"}