Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
docs(skills): fix wrong facts and broken paths from the doctrine audit (#5026)
miga-heygen0c3e244269aa
diff --git a/skills-manifest.json b/skills-manifest.jsonindex 2b47d8f140..56b6257f30 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -2,7 +2,7 @@"source": "heygen-com/hyperframes","skills": {"embedded-captions": {- "hash": "af4e51dc30d776f9",+ "hash": "643579aed5919847","files": 144},"faceless-explainer": {@@ -10,7 +10,7 @@"files": 27},"figma": {- "hash": "ade0258f3cb1f378",+ "hash": "f8cf9f2c78ea8374","files": 2},"general-video": {@@ -22,7 +22,7 @@"files": 29},"hyperframes-animation": {- "hash": "5ae559933ce71260",+ "hash": "5a771a306ac3b34e","files": 122},"hyperframes-audio": {@@ -38,7 +38,7 @@"files": 11},"hyperframes-creative": {- "hash": "7835cfaad29f1fcb",+ "hash": "8d0601ce26adc560","files": 79},"hyperframes-keyframes": {@@ -46,11 +46,11 @@"files": 3},"hyperframes-registry": {- "hash": "7e171ae1faac48a1",+ "hash": "d7c1885fb4cce2cf","files": 12},"hyperframes-studio": {- "hash": "401a7cb739f020f9",+ "hash": "f5e0b44d68152c12","files": 1},"media-use": {@@ -58,11 +58,11 @@"files": 107},"motion-graphics": {- "hash": "e7e955592f58ebbe",+ "hash": "6db77031ad839f6a","files": 23},"music-to-video": {- "hash": "76e688e8e705777f",+ "hash": "5b365022211eaf0c","files": 169},"pr-to-video": {@@ -74,15 +74,15 @@"files": 34},"remotion-to-hyperframes": {- "hash": "833bb7855cd99d4f",+ "hash": "d02be65b7f3f4a63","files": 77},"slideshow": {- "hash": "4665a8880652f6d5",+ "hash": "efc3c0be622fa9a1","files": 2},"talking-head-recut": {- "hash": "3ae0f58fc1acae25",+ "hash": "9aac076ceddd2499","files": 28}}diff --git a/skills/embedded-captions/SKILL.md b/skills/embedded-captions/SKILL.mdindex 8065b5e398..eadedc2234 100644--- a/skills/embedded-captions/SKILL.md+++ b/skills/embedded-captions/SKILL.md@@ -274,7 +274,7 @@ The full **embed-track** playbook lives in **[references/composition-craft.md](r## Dependencies- **HyperFrames CLI:** plugin installs use the bundled manifest-pinned launcher. Source contributors can use a built checkout (`packages/cli/dist/cli.js`) via `HYPERFRAMES_ROOT`, the skill’s source tree, or `~/Downloads/hyperframes`.-- **Node-first; two Python touchpoints via `uvx` (no manual installs):** transcription runs WhisperX through `uvx` (word-level timings; falls back per SKILL §transcription), and Theme's `drawon` setpiece shells `python3 scripts/gen-stroke-path.py` at compile time. Everything else runs on the toolchain hyperframes already ships: matting via the hyperframes CLI's **`remove-background`** (u2net_human_seg; weights auto-download once, ~168 MB, to `~/.cache/hyperframes/`), image/alpha math via **`sharp`**, layout/occlusion/overflow via **`puppeteer`**, plus **`ffmpeg`**. Install Sharp, Puppeteer, and GSAP in the caption project as described in **Runtime prerequisites** above. The helpers check that project first and retain checkout dependency lookup for source contributors.+- **Node-first; two Python touchpoints via `uvx` (no manual installs):** transcription runs WhisperX through `uvx` (word-level timings; falls back to an existing word-level `transcript.json`), and Theme's `drawon` setpiece shells `python3 scripts/gen-stroke-path.py` at compile time. Everything else runs on the toolchain hyperframes already ships: matting via the hyperframes CLI's **`remove-background`** (u2net_human_seg; weights auto-download once, ~168 MB, to `~/.cache/hyperframes/`), image/alpha math via **`sharp`**, layout/occlusion/overflow via **`puppeteer`**, plus **`ffmpeg`**. Install Sharp, Puppeteer, and GSAP in the caption project as described in **Runtime prerequisites** above. The helpers check that project first and retain checkout dependency lookup for source contributors.- **Transcription = WhisperX via `uvx`** (word-level timings + alignment; no manual install — `transcribe.cjs` drives `uvx whisperx`). Falls back to an existing word-level `transcript.json` if present.- **Source video** — `matte.cjs` / `transcribe.cjs` auto-resolve `source.mp4` (or glob the clip / read `hyperframes.json`), so `hyperframes init --video X.mp4` needs no manual rename.- **fps** — `matte.cjs` extracts at the source's native rate and records `matte.fps`; `render-and-composite.sh` uses that so the matte stays frame-aligned.diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.mdindex cda8aec4db..f19ec095b9 100644--- a/skills/figma/SKILL.md+++ b/skills/figma/SKILL.md@@ -94,7 +94,7 @@ No REST equivalent exists. When a compatible connector is available, use it and1. Retrieve motion context for the parent frame in one recursive request, not one request per element. Save the raw JSON next to the project (`.media/figma-cache/`) so retranslation is free.2. Normalize into `MotionDoc`s with `motionContextToDocs(rawResponse, { selectorFor, repeat })` from `@hyperframes/core/figma` — **never transcribe keyframe numbers by hand**. The helper encodes the field-tested decoding rules mechanically: it parses the motion.dev snippets (the reliable encoding — the CSS snippets stretch durations and can disagree; they are ignored), strips loop-wrap tail keyframes (sub-millisecond segments at times ≈0.9999→1 are the loop's instant reset, not authored motion — the wrap is realized by `repeat` restart), and preserves bezier eases verbatim. `selectorFor` must return the ids from the Phase-3 component import — don't derive selectors from node names.- 2b. **Validate against ground truth before calling it done — mandatory**: export the cohort's root frame through the available connector and run `node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold.+ 2b. **Validate against ground truth before calling it done — mandatory**: export the cohort's root frame through the available connector and run `node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold.3. `motionToGsap(doc)` → `emitTimelineScript(spec)` → inject as a `<script>` after the GSAP + CustomEase CDN tags. Paused, finite, registered on `window.__timelines` with a literal key.4. Untranslatable track (shader-driven, unsupported prop, complex masks) → export through the connector, freeze the MP4, then embed it as `<video class="clip">`. Exception: shader-driven tracks — Figma's export path flattens shaders to the base color (see Shaders below), so a bake there silently loses the shader; ask the user for a native Figma export instead. Always say which path you used and why. Named eases outside the mapped set fall back to linear — the mapping table lives in `motionEase.ts`; flag the fallback to the user when it fires.5. Run `npx hyperframes check` before calling it done.diff --git a/skills/hyperframes-animation/SKILL.md b/skills/hyperframes-animation/SKILL.mdindex e850457d50..e5299de70e 100644--- a/skills/hyperframes-animation/SKILL.md+++ b/skills/hyperframes-animation/SKILL.md@@ -73,7 +73,7 @@ Animation-craft additions on top of core's contract:## Scripts```bash-node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \+node <SKILL_DIR>/scripts/animation-map.mjs <composition-dir> \--out <composition-dir>/.hyperframes/anim-map```diff --git a/skills/hyperframes-creative/SKILL.md b/skills/hyperframes-creative/SKILL.mdindex abd8ef5705..8ecb3cd714 100644--- a/skills/hyperframes-creative/SKILL.md+++ b/skills/hyperframes-creative/SKILL.md@@ -57,10 +57,10 @@ For motion patterns, scene blueprints, transitions, and CSS marker effects, use`contrast-report.mjs` resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set `HYPERFRAMES_SKILL_PKG_VERSION=<version>` only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.-Run from the repo root with explicit paths, for example:+Run with explicit paths, for example:```bash-python skills/hyperframes-creative/scripts/extract-audio-data.py <audio-file>+python <SKILL_DIR>/scripts/extract-audio-data.py <audio-file>```Animation analysis (`animation-map.mjs`) lives in `hyperframes-animation/scripts/`.diff --git a/skills/hyperframes-registry/SKILL.md b/skills/hyperframes-registry/SKILL.mdindex 396d0497f0..fd6d552902 100644--- a/skills/hyperframes-registry/SKILL.md+++ b/skills/hyperframes-registry/SKILL.md@@ -119,7 +119,7 @@ The normal table and `--json` modes only list matches; install a selected name wWhen the search comes back and nothing in it does the job, say so before you hand-author the move:```bash-npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier on-device+npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>````catalog --query` prints this line for you, pre-filled, and `--json` carries it as `report_gap` — so it is already in hand at the moment you decide nothing fits.diff --git a/skills/hyperframes-studio/SKILL.md b/skills/hyperframes-studio/SKILL.mdindex 879bf1e666..07bb48bdfa 100644--- a/skills/hyperframes-studio/SKILL.md+++ b/skills/hyperframes-studio/SKILL.md@@ -59,7 +59,7 @@ asked you to change nothing at all, write nothing: put the plan in the reply andThe root composition holds only timed hosts, media and audio. Any scene with nestedstructure (a div containing children, a title with a subtitle, a chart) is its own-file loaded with `data-composition-src`, wiring in+file loaded with `data-composition-src`, wiring in `/hyperframes-core``references/sub-compositions.md`.Nested markup left inside the root does not become a row of its own. It hides insidediff --git a/skills/motion-graphics/SKILL.md b/skills/motion-graphics/SKILL.mdindex ba8fef0e36..3405c60009 100644--- a/skills/motion-graphics/SKILL.md+++ b/skills/motion-graphics/SKILL.md@@ -98,7 +98,7 @@ npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=moDispatch one subagent. prompt = full `agents/director.md` + `## Dispatch context` (`SKILL_DIR` / `PROJECT_DIR` / the user's request / `Schema: <SKILL_DIR>/references/shot-plan-ir.md`). It must:1. **Decide: does this need a search?** (the first fork)- - **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds); content is user-supplied; `asset_needs: []`.+ - **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds / maps); content is user-supplied; `asset_needs: []`.- **Yes** → emit a **search plan** into `asset_needs[]` (news / web / tweet / image; two-pole queries). The specific **search-driven category** (webpage / news / tweet / asset-fusion) is confirmed by the content type returned in Step 2, and finalized in Step 3.2. Write a draft `shot-plan.json` (envelope + chosen form category _or_ search intent + `asset_needs` + a one-paragraph shot brief). Schema: `references/shot-plan-ir.md`.@@ -108,11 +108,6 @@ Validation: `[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing`.If `shot-plan.json.asset_needs` is non-empty, resolve assets (search / generate / fetch → frozen project-local paths + ledger). See `phases/source/guide.md` (wraps `media-use resolve`; the search-driven categories use the news/web/tweet/image search). If `asset_needs` is empty, **skip to Step 3**.-```bash-# illustrative — see phases/source/guide.md-(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)-```-Degrade gracefully: if a search/provider is unavailable, the category falls back to asset-free (note it in `context.log`).### Step 3 — Design (subagent: Director Part 2)diff --git a/skills/music-to-video/SKILL.md b/skills/music-to-video/SKILL.mdindex c440030b0a..6acd406123 100644--- a/skills/music-to-video/SKILL.md+++ b/skills/music-to-video/SKILL.md@@ -30,7 +30,7 @@ Goal: Establish the music source, create the HyperFrames project, and note any u**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it confirms this route's must-haves (the music source, destination → aspect — `../hyperframes/references/routes/music-to-video.md`) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.-The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`references/bgm.md`). Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply one branch:+The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`audio/references/bgm.md`). Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply one branch:- **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider.- **Autonomous:** state the status and continue through the available local provider.diff --git a/skills/remotion-to-hyperframes/SKILL.md b/skills/remotion-to-hyperframes/SKILL.mdindex 03f220825e..2b121141d1 100644--- a/skills/remotion-to-hyperframes/SKILL.md+++ b/skills/remotion-to-hyperframes/SKILL.md@@ -39,7 +39,7 @@ The skill ships with a **tiered test corpus** (T1–T4, 4 fixtures total) that g- **The reverse direction.** Exporting a HyperFrames composition back out _to_ Remotion (or to any other framework) is not a workflow — the translation is Remotion → HyperFrames only. Say so plainly.- **Non-Remotion sources.** An After Effects project (`.aep`), a Framer Motion / plain-React / CSS animation, or any other tool's source is not a Remotion composition — there is no Remotion source to translate. Re-create it natively via `/general-video`, or decline if HyperFrames can't represent it.-When in doubt, default to authoring a native HyperFrames composition with `/general-video` (the general HyperFrames authoring flow) instead.+When in doubt, return to `/hyperframes`; its intent layer picks the route.## Workflowdiff --git a/skills/slideshow/SKILL.md b/skills/slideshow/SKILL.mdindex 4b2f89456a..42cd47c28a 100644--- a/skills/slideshow/SKILL.md+++ b/skills/slideshow/SKILL.md@@ -431,7 +431,7 @@ The slideshow automatically sets the `interactive` attribute on every inner `<hyPresenter-driven media playback has an autoplay-policy constraint: `BroadcastChannel` can sync intent, time, and state, but it cannot transfer the presenter's user activation to the audience tab. The shared slideshow player mirrors native media events and starts remote audience playback muted first; only fall back to the standalone harness's audience unlock behavior if muted `media.play()` is rejected or if the deck specifically requires audible audience playback. Do not keep applying remote `timeupdate` messages after a rejected play, or the audience will silently seek through the video without playback.-Presenter notes are editable in the presenter view. Edits are stored in `localStorage` per deck and slide, layered over the manifest notes without rewriting the composition file. Do not add one-off note-editing scripts to decks; rely on the shared slideshow player behavior. If a standalone/custom wrapper truly needs to implement this outside the shared player, use the deterministic storage snippet in `skills/slideshow/references/standalone-harness.md`.+Presenter notes are editable in the presenter view. Edits are stored in `localStorage` per deck and slide, layered over the manifest notes without rewriting the composition file. Do not add one-off note-editing scripts to decks; rely on the shared slideshow player behavior. If a standalone/custom wrapper truly needs to implement this outside the shared player, use the deterministic storage snippet in `references/standalone-harness.md`.### Media cleanup on slide exit@@ -472,7 +472,7 @@ The **durable answer** is engine-hosted: `hyperframes preview --slideshow` / stuUntil then, standalone demos (a composition opened via the bare player bundle in a browser, without the engine) require workarounds for three gaps: the composition must expose a seekable root timeline, the island must be duplicated into the wrapper, and wrapper-owned SFX/global audio should live in the parent frame. These patterns are documented in:```-skills/slideshow/references/standalone-harness.md+references/standalone-harness.md```Do not treat the patterns there as the blessed model — they exist only to bridge the gap until the engine-hosted path lands.diff --git a/skills/talking-head-recut/SKILL.md b/skills/talking-head-recut/SKILL.mdindex 4f3079c762..9af74497bd 100644--- a/skills/talking-head-recut/SKILL.md+++ b/skills/talking-head-recut/SKILL.md@@ -248,8 +248,8 @@ sub-compositions** (one .html per chapter, mounted with`data-composition-src`) so the GSAP timeline per file stays manageable— see the `timeline_track_too_dense` HyperFrames lint warning.-`content` can be a plain string ("Title: annualized 5.69%\nNotes: ...") or any JSON-shape that captures the data. The agent decides the shape per card.+`contentHints` is a free-form object; its keys and nesting can take whatever+shape captures the data. The agent decides the shape per card.**Optional outro.** This skill ships **no fixed brand outro**. If the user wants a closing card, design a neutral one yourself (wordmark + one-line tagline, ~1.5-2s, fade in -> short hold -> fade out), append it to `cards[]`, and extend `composition.durationSeconds` to its `endSec`. Otherwise end on the last content card.@@ -539,15 +539,12 @@ style / layout / frame, Read the corresponding file:the data-card-id to your card's id, swap the placeholder content for thereal takeaway, and you're done.- `references/layouts/<key>.html` — exact `videoBounds` + `cardBounds` for- both landscape and portrait, with a copy-paste JSON snippet for- `storyboard.json`'s per-card `layout` field.+ both landscape and portrait. The storyboard records only `card.zone`.- `references/frames/<key>.html` — decorative HTML to add as a sibling of`#video-wrap`, plus placement instructions for the composition CSS.-Pick `style × layout × frame` **per card** — you can change all three-between cards as long as the transitions read smoothly. A common rhythm:-open `editorial × overlay × clean`, switch to `audit × split × hairline`-for the data card, close on `whiteboard × pip × polaroid`.+Within the user's chosen style group you may vary the style per card, and+pick `layout × frame` per card, as long as the transitions read smoothly.The 10 styles are skill-side design tokens, **not composition-level themes** —they don't need to be declared in `storyboard.composition`; they live@@ -570,8 +567,7 @@ the source video:Schema does NOT store per-card video bounds. `videoTrack.bounds` is**one-time** at composition level (defaults to full canvas). Video"moving" between cards is purely a GSAP animation authored in-`index.html`. There is no `card.layout` field — earlier versions of this-doc invented one; the real schema only has `card.zone`.+`index.html`. There is no `card.layout` field; the schema only has `card.zone`.**4 composition layouts** (from `references/layouts/`) — each is arecipe pairing a `zone` with a `#video-wrap` tween target: