chore: import upstream snapshot with attribution

skills/faceless-explainer/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: faceless-explainer
+description: "Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a product promo (/product-launch-video) or a site tour (/website-to-video). Unclear → /hyperframes."
+---
+
+> **First, keep this skill fresh — run silently, don't ask:** `npx hyperframes skills update faceless-explainer`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.
+
+# Faceless Explainer to HyperFrames
+
+Use this skill to turn a body of text into an explainer video: pick a design system, plan a teaching story, and build it frame by frame in HyperFrames. **Faceless** means every visual is invented downstream — there is no capture step and no real asset inventory.
+
+> **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for **explaining a topic from text, with no product and no website to capture**. Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a tour of a real site → `/website-to-video`; a GitHub PR → `/pr-to-video`; captions on existing footage → `/embedded-captions`; a short unnarrated motion graphic → `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
+
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the two modes, the gate types, and the brief fields; the mode governs the Step 0/3/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+
+Workflow: Step 0 setup → `hyperframes.json`; Step 1 brief → `capture/extracted/`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
+
+---
+
+## Step 0: Setup and Brief
+
+Goal: Lock the core video brief and create the HyperFrames project if needed.
+
+Initialize only if `hyperframes.json` is missing. Name `<project>` from the topic in kebab-case, such as `compound-interest-explained`; never use workspace name or timestamp.
+
+`npx hyperframes init "videos/<project>" --non-interactive --example=blank` — `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
+
+**Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
+
+**Confirm the brief** in two rounds — through the question UI when the environment has one, conversationally otherwise. The intro text states **message** (the explainer's thesis, in one sentence) and **language**. Skip a question only when the user's request already answered it. (`VO_MODE` is asked in Step 1 only when a script was pasted.)
+
+**Round 1 — mode.** One question, asked first. Skip it when the request already carried a signal ("surprise me" / "just build it"):
+
+- **Collaborative (recommended)** — confirm the key choices together before building.
+- **Autonomous** — every decision is made for the user, each stated with its reason; the only remaining question is preview-before-render.
+
+Autonomous → ask nothing more. State the locked brief (all fields + receipts) as a heads-up and proceed straight through; the preview question waits at Step 6.
+
+**Round 2 — the brief (collaborative).** One round, these three questions, recommended option first with its receipt:
+
+- **Angle — how should the topic be taught?** concept / how-to / listicle / narrative; recommend the one the text's own shape suggests, with its basis.
+- **Length — how long?** Recommend inside the 30–90s sweet spot, scaled to how much the text actually teaches, with its basis.
+- **Destination — where will it play?** YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+
+A "go" accepts all recommended defaults.
+
+**Gate:** `hyperframes.json` exists, and the brief fields (angle, length, destination → aspect, message, language) are locked; sign-in status was shown (signed in, or continuing offline).
+
+---
+
+## Step 1: Brief (no capture)
+
+Goal: Fold the user's text into the project as the source of information. There is **no website capture and no real assets** — this is a faceless explainer.
+
+Save the user's full input verbatim, then create the synthetic capture package by hand:
+
+- `capture/extracted/visible-text.txt` — the full article / notes / topic / brief, verbatim. This is the source of **information**, not a story template (Step 3 reshapes it).
+- `capture/extracted/tokens.json` — `{ "title": "", "description": "", "colors": [], "fonts": [] }`. Fill `title`/`description` from the brief. Leave `colors`/`fonts` empty unless the user explicitly gave brand colors or fonts — then add them (the design preset supplies a complete palette regardless).
+
+If the user pasted a script or wants their wording kept, save it verbatim as `user_script.txt`, ask once "use it verbatim or restructure?", and store the answer as `VO_MODE` for Step 3.
+
+Do **not** run `npx hyperframes capture` (there is no URL). Do not create `asset-descriptions.md` or populate `capture/assets/` — faceless visuals are invented in Steps 4-5, not captured. The one exception: if the user supplied a real image, place it under `public/<basename>` and note it for Step 3.
+
+**Gate:** `capture/extracted/visible-text.txt` and `capture/extracted/tokens.json` exist; you can state the explainer's topic and audience in one clear sentence.
+
+---
+
+## Step 2: Design System
+
+Goal: Choose one shipped frame preset; a script turns it into this video's `frame.md` + caption skin.
+
+You make the one judgment call — **which preset**. Read `../hyperframes-creative/references/design-spec.md` and browse `../hyperframes-creative/frame-presets/`; pick the preset whose look best fits the topic, tone, and audience. Then run:
+
+```bash
+node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .
+```
+
+The script does the rest deterministically: copies the preset's `FRAME.md` → `frame.md` and **remixes** it onto any brand tokens in `capture/extracted/tokens.json` (brand colors mapped onto the preset's color keys by role; the preset's display + body fonts swapped for the brand's), copies the preset's caption skin to `.hyperframes/caption-skin.html`, and self-validates (exits 1 on a broken mapping). Proceed as soon as it exits 0 — no hand-editing of the spec.
+
+A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors/fonts empty) → the script keeps the preset's own palette, a complete shippable design. Only when the user named brand colors/fonts add them to `tokens.json` before running, and only adjust `frame.md` by hand afterward if a mapping truly needs it.
+
+**Gate:** `build-frame.mjs` exited 0 — `frame.md` exists from a named preset, and (when the preset ships one) `.hyperframes/caption-skin.html` exists as the caption skin source.
+
+---
+
+## Step 3: Storyboard and Script
+
+Goal: Turn the text into an approved frame-by-frame teaching plan.
+
+Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
+
+Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
+
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
+
+**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
+
+---
+
+## Step 3.1: Audio
+
+Goal: Generate narration, word timings, music, and audio metadata from the approved script.
+
+Start audio after Step 3 approval. Run it in the background, then continue to Step 4. (Sign-in status was already shown in Step 0; the engine falls back automatically.)
+
+**Choose the narration voice from the user's ask before invoking.** If the request named a voice, gender, or tone, pick a matching voice id and pass it with `--voice <id>`. The pipeline default is otherwise **Marcia (female)** on HeyGen / `am_michael` on Kokoro — so a request like "a male voice" is silently ignored unless you pass the flag. Voice ids are provider-specific; resolve against whichever provider Step 0's sign-in status selected: **HeyGen** (signed in) via `node ../media-use/audio/scripts/heygen-tts.mjs --list` (or `GET /v3/voices?engine=starfish`); **Kokoro** (offline) via the voice table in `../media-use/audio/references/tts.md` (prefixes `am_`/`bm_` male, `af_`/`bf_` female). Omit `--voice` only when the user expressed no preference.
+
+`node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json --voice <voice-id> &`
+
+The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field. This uses the HeyGen Audio API for retrieval, not generation, and the same `~/.heygen` credential as TTS. For provider details, read `../media-use/audio/references/tts.md`.
+
+If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood.
+
+**Gate:** audio job has started, or the project is marked silent.
+
+---
+
+## Step 4: Frame Visual Design
+
+Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.
+
+Edit `STORYBOARD.md` in place. Do not create another storyboard. Use `frame.md` as source of truth for color, type, layout feel, and style.
+
+Read `references/visual-design.md`, `../hyperframes-animation/blueprints-index.md`, `references/motion-language.md`, and `../hyperframes-animation/rules-index.md`. Use `visual-design.md` for the method (the time-coded shot sequence, the inline Layout vocabulary, and the invented-visual treatment), plus the required `## Video direction` block. Use `../hyperframes-animation/blueprints-index.md` to pick each frame's shot shape. Use `motion-language.md` (the motion vocabulary + the motion doctrine) and `../hyperframes-animation/rules-index.md` (valid rule names) for motion — do not invent motion names.
+
+For every frame, write a **time-coded shot sequence** into `STORYBOARD.md` per `visual-design.md`'s method: pick the frame's blueprint (or compose), instantiate it with THIS frame's **invented** content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. Because the explainer is faceless, `focal`/`roles` name the **invented visual elements** (a hero word, a diagram node, a data-viz series) — you are designing them, not selecting captured assets. State layout and motion **inline** per Scene (vocabularies in `visual-design.md` and `motion-language.md`). Add one video-wide `## Video direction` block.
+
+Do not change story, script, `transition_in`, or the source text. Do not write HTML in this step. There is **no asset-staging step** — faceless visuals are built by the workers in Step 5. If the user supplied a real `public/<basename>` image, reference it by path in the relevant frame's `focal`/`roles`; otherwise nothing to stage.
+
+**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists.
+
+---
+
+## Step 5: Build Frames
+
+Goal: Build every storyboard frame as an HTML composition and assemble the playable video.
+
+Wait for Step 3.1 audio to finish if audio was started. Then sync durations and fetch SFX; skip both if silent.
+
+`node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md`
+
+`node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .`
+
+Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
+
+Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame.
+
+Each worker context must include `PROJECT_DIR`, `frame_id`, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
+
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
+
+As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
+
+After audio timings exist, build captions in the background and assemble the index:
+
+`node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &`
+
+`node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .`
+
+`captions.mjs` uses the project's `.hyperframes/caption-skin.html` (copied in Step 2) as the caption look, injecting brand tokens from `frame.md`; with no skin present it renders the built-in default pill. `captions: skipped (<reason>)` is valid. Continue without captions when explicitly skipped.
+
+**Gate:** every frame is marked `animated`, `index.html` exists, and captions are built or explicitly skipped.
+
+---
+
+## Step 6: Finalize
+
+Goal: Verify the assembled video, get user approval, and render the final MP4.
+
+Inject transitions, run checks, pause for review, then render.
+
+`node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .`
+
+`node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html`
+
+`npx hyperframes lint`
+
+`npx hyperframes check`
+
+`npx hyperframes check`
+
+`npx hyperframes snapshot --at <frame-midpoints>`
+
+`snapshot` stitches the captured frames into one contact sheet (`snapshots/contact-sheet.jpg`). Glance at it; if nothing is obviously broken, move on — don't linger here.
+
+If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to `compositions/frames/NN-*.html`, then rerun the failed check.
+
+**Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
+
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode this is the one question the mode keeps: ask "preview first, or render?" — open the preview on yes, render on no — then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
+
+Preview: `npx hyperframes preview`
+
+Render only after user approval (autonomous mode: after the preview-or-render question):
+
+`npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4`
+
+Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless the user asks.
+
+**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states MP4 path and final duration.
+
+---
+
+## Quick Reference
+
+**Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.
+
+**Faceless deltas vs a captured-asset workflow:** no Step 1 capture (synthetic `tokens.json` + `visible-text.txt`); no `asset-descriptions.md` and no `capture/assets/`; no asset-staging in Step 4; `asset_candidates` empty by default; every visual is invented by the Step 5 workers (typography / abstract graphics / diagrams / data-viz). A user-supplied `public/<basename>` image is the only real asset path.
+
+**Background scripts:** the workflow ships only these under `scripts/`: `build-frame` for adopting + brand-remixing a frame preset into `frame.md` (+ caption skin); `audio` for TTS, transcription, BGM, SFX, and duration syncing; `captions`; `transitions` for inject and verify; and `assemble-index`. Everything else is the `hyperframes` CLI.
+
+The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`).
+
+| Read                                                                                                                                                        | When                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.                    |
+| `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape. |
+| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                                       |
+| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                                          |
+| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the explainer story.                                              |
+| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                      |
+| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                 |
+| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                     |
+| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.                       |
+| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                 |
+| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                           |
+| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                  |
+| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                        |
+| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                                            |
+| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                            |

skills/faceless-explainer/references/cut-catalog.md

@@ -0,0 +1,215 @@
+# Cut catalog — within-frame seams (worker-built)
+
+> **A worker build-recipe (Step 5) — the sibling of `../hyperframes-animation/rules/`, not a second motion doc.** These are within-frame cuts the **frame worker builds INSIDE its own composition** (Z-scale + blur + opacity tweens, or per-word x-staggers, all on the frame's own paused GSAP timeline). They are **not** the between-frame transition: story owns that via `transition_in`, which the harness's injector stamps from a **separate registry vocabulary** (`crossfade` / `blur-crossfade` / `push-slide` / `zoom-through` / `squeeze`) — the catalog names here (**cut-the-curve / inverse-zoom / waterfall**) are **not** valid `transition_in` values. Use this catalog when a frame's shot sequence has an internal seam — a within-scene text/element swap, a **Scene-to-Scene** cut (a `Scene` is a time window WITHIN one frame, **not** a frame-to-frame boundary), or a text-to-text line change — and you want it to read as one continuous move instead of a hard slideshow cut. (`zoom-through` lives in both worlds: a whole-frame wrapper transition in the registry, an element-level Z-cut here — same idea, different scope.)
+
+Four techniques that create depth and continuity:
+
+1. **Zoom-Through** — within-scene text swaps, Z-axis, moving TOWARD the viewer
+2. **Inverse Zoom-Through** — Z-axis swaps moving AWAY from the viewer
+3. **Cut the Curve** — between-scene transitions on x/y
+4. **Waterfall Cut** — word-by-word cut-the-curve with staggered exits and entries
+
+All four are the same underlying principle: **cut at peak velocity, match direction and
+speed on both sides of the cut.** The differences are axis, scope, and granularity.
+
+**Choosing which at a seam:** for an UNFINISHED phrase (building one larger idea across
+several visually distinct scenes that still approach the same point — multi-line text, a
+run of consecutive cards) use **cut-the-curve** / **waterfall**. For a STATE CHANGE (turning
+to a NEW part of the video — most often hook → context, between two distinct chapters) use
+**zoom-through**, and **inverse zoom-through** for an arrival / payoff beat. Chain these so
+the frame's internal seams feel like one camera moving through the content.
+
+---
+
+## Blur Logic (applies to all Z-axis variants)
+
+Blur sells the speed at the cut, but it must scale with the SUBJECT SIZE:
+
+| Subject                                                | Peak blur   | Why                                                                                                                                                                                      |
+| ------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Text-scale (headline, line, word group)                | **10px**    | At 20px text smears into illegibility — the eye loses the word it was tracking and the cut reads as a glitch, not speed. At 20px letterforms go mushy mid-cut; 10px keeps them readable. |
+| Full-frame surface (terminal window, card, screenshot) | **18–20px** | Big surfaces have edges and texture that survive heavy blur; lighter blur on a full-frame move reads as a rendering hiccup instead of motion.                                            |
+
+Both sides of a cut use the SAME peak blur — the value must match at the swap frame.
+Apply blur to the WRAPPER, never to individual children.
+
+---
+
+## 1. Zoom-Through (forward)
+
+### The Problem
+
+Text enters, holds, exits. Then next text enters, holds, exits. Each text block is
+independent — no depth, no continuity. The video feels like a slideshow.
+
+### The Principle
+
+A velocity-matched cut on the Z-axis. You **never see both texts at the same time.** The
+outgoing text scales toward the viewer (accelerating), blur and opacity peak at the cut
+point hiding a hard swap, and the incoming text continues scaling up from behind
+(decelerating into the focal plane). One continuous forward motion, two different texts.
+
+### The Three Phases
+
+**Phase 1: Exit** — text accelerates forward (toward viewer)
+
+- Scale: `1.0 -> 1.2`, Blur: `0px -> 10px` (text-scale; see Blur Logic), Opacity: `1.0 -> 0.15`
+- Scale/blur easing: `power3.in` (steep acceleration)
+- Opacity easing: `none` (linear — even dimming, separated from scale)
+- Duration: 0.2s
+
+**Phase 2: Hard cut** at peak velocity + peak blur
+
+- Outgoing: `opacity: 0` (instant via `tl.set`)
+- Incoming: `opacity: 0.15, scale: 0.75, blur: 10px` (instant via `tl.set`)
+- All properties match at the cut: blur, opacity, and scale DIRECTION (both scaling up)
+
+**Phase 3: Entry** — text continues forward (growing into focal plane)
+
+- Scale: `0.75 -> 1.0`, Blur: `10px -> 0px`, Opacity: `0.15 -> 1.0`
+- Easing: `expo.out` (steep initial burst matching exit velocity, long settle)
+- Duration: 0.5s
+
+### Why Opacity Must Be Separate on Exit
+
+Scale uses `power3.in` but that keeps opacity near 1.0 for most of the tween. Splitting
+opacity to its own tween with linear ease makes the dimming even. On entry, all properties
+can share `expo.out`.
+
+---
+
+## 2. Inverse Zoom-Through (backward)
+
+The mirror: the camera "pulls back" instead of pushing through. The outgoing element
+RECEDES away from the viewer; the incoming element arrives OVERSIZED (as if it had been
+just behind the camera) and retracts into the focal plane. Both move in the shrinking
+direction — same-direction rule preserved, just reversed.
+
+**When to use over the forward variant:** arrival beats. The incoming element lands with
+presence because it comes from larger-than-frame — right for a payoff line ("That changes
+today."), a giant reply, or a held end-state. Forward zoom-through reads as _progressing
+through_ content; inverse reads as _arriving at_ content.
+
+### The Three Phases
+
+**Phase 1: Exit** — element recedes (away from viewer)
+
+- Scale: `1.0 -> 0.8`, Blur: `0px -> 10px` (text-scale)
+- Scale/blur easing: `power3.in`; Opacity: `1.0 -> 0.15` on `none` (separate tween)
+- Duration: 0.2s
+
+**Phase 2: Hard cut**
+
+- Outgoing: `opacity: 0` via `tl.set`
+- Incoming: `opacity: 0.15, scale: 1.25, blur: 10px` via `tl.set`
+
+**Phase 3: Entry** — incoming retracts into place
+
+- Scale: `1.25 -> 1.0`, Blur: `10px -> 0px`, Opacity: `0.15 -> 1.0`
+- Easing: `expo.out`, Duration: 0.5s
+
+---
+
+## 3. Cut the Curve (Scene Transitions)
+
+### The Principle
+
+Use cut-the-curve for **all scene-to-scene transitions** on x and y axes. The outgoing
+scene's hero element accelerates in one direction, the cut lands mid-motion, and the
+incoming scene's hero element continues moving in the **same direction** and decelerates.
+Nothing exits fully off-screen and nothing enters from fully off-screen — **speed plus
+opacity fading trick the eye**; the partial moves are enough.
+
+### Same Path, Same Direction
+
+If Scene A's hero slides left, Scene B's hero enters from the right and continues sliding
+left. Both move leftward. One continuous motion.
+
+| Direction | Scene A exit   | Scene B entry start | Scene B entry end |
+| --------- | -------------- | ------------------- | ----------------- |
+| Leftward  | `x: 0 -> -230` | `x: +230`           | `x: 0`            |
+| Rightward | `x: 0 -> +230` | `x: -230`           | `x: 0`            |
+| Upward    | `y: 0 -> -230` | `y: +230`           | `y: 0`            |
+| Downward  | `y: 0 -> +230` | `y: -230`           | `y: 0`            |
+
+### Velocity matching via mirrored eases
+
+The cleanest match: exit `power4.in` and entry `power4.out` with the SAME distance and
+duration — mathematically the two halves of one `power4.inOut` composite, so the entering
+element picks up at exactly the 50% point of the notional path at identical velocity
+(e.g. 230px / 0.3s ≈ 3,070 px/s at the cut on both sides).
+
+The fade trick: the exit's opacity completes at ~25–30% of its travel (fade duration
+≈ 0.18–0.3s vs motion 0.3–0.34s) — the element vanishes while still visibly accelerating,
+and nothing has to reach the frame edge. Entry fades IN fast from ~0.35 under its
+deceleration. Time the LAST fading element to die right at the hard cut — gaps where
+nothing is moving read as awkward dead air.
+
+### Rules
+
+- Use cut-the-curve for all scene transitions — it's the default, not an accent
+- Same direction on both sides; mirrored `.in`/`.out` eases, same distance + duration
+- Exit duration short (0.2–0.4s), entry duration >= exit duration
+- Partial travel + fade, never full off-screen moves
+
+---
+
+## 4. Waterfall Cut (word-by-word cut-the-curve)
+
+Cut-the-curve at WORD granularity — the strongest version of the leftward cut for
+text-to-text seams. Each word of the outgoing line ramps out on its own pronounced curve;
+each word of the incoming line cascades in mid-flight. The stagger turns the cut into a
+wave the eye rides across the seam.
+
+### Exit (per word)
+
+- Motion: `x: 0 -> -230` over 0.34s on **power4.in** — a much more pronounced ramp than
+  the usual power2: the word barely creeps, then RIPS
+- Fade: `opacity -> 0` over 0.18s (separate tween, `power1.in`) — completes when the word
+  is only ~25–30% into its travel
+- Stagger: reading order, ~0.022s per word, timed so the LAST word finishes fading right
+  at the hard cut
+
+### Entry (per word)
+
+- `fromTo x: +230 -> 0, opacity: 0.35 -> 1` over 0.3s on **power4.out** — the mirrored
+  back half of the composite; every word ignites already moving at matched velocity
+- Waterfall stagger with SHRINKING gaps (start 0.05s, multiply by ~0.84 per word) so the
+  cascade accelerates across the line — the cascade should speed up word over word, not run
+  at a flat per-word delay
+- Pre-set all words to `x: +230, opacity: 0` at build time — `immediateRender: false`
+  alone leaves un-started words sitting visible at rest during the stagger window
+
+### Whole-line variant
+
+A single-line beat (e.g. a big intro line) exits as one group with the same pronounced
+ramp, but stretch its fade to ~0.3s ending ~0.02s before the cut — a lone element that
+fades early leaves dead air that a word cascade would have covered.
+
+---
+
+## Choosing a Variant
+
+|                | Zoom-Through                | Inverse Zoom                | Cut the Curve     | Waterfall Cut             |
+| -------------- | --------------------------- | --------------------------- | ----------------- | ------------------------- |
+| Scope          | Within-scene text swap      | Arrival/payoff beat         | Between scenes    | Text-to-text seam         |
+| Axis           | Z, toward viewer            | Z, away from viewer         | X / Y             | X, per-word               |
+| Peak blur      | 10px text / 20px full-frame | 10px text / 20px full-frame | none required     | none (fade does the work) |
+| Opacity at cut | 0.15                        | 0.15                        | exit faded by cut | last word dies at cut     |
+| Feel           | progressing through         | arriving at                 | carried sideways  | a wave across the seam    |
+
+---
+
+## Anti-Patterns
+
+| Don't                                    | Why                                         | Instead                                                |
+| ---------------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
+| Two texts visible during a zoom-through  | Overlapping text breaks the Z-axis illusion | Hard cut at blur peak, one text at a time              |
+| 20px blur on text-scale subjects         | Letterforms smear; reads as a glitch        | 10px for text, 18–20px only full-frame                 |
+| Elements on different paths across a cut | Eye tracks one direction, cut goes another  | Same property, same direction                          |
+| Mismatched blur/opacity at the swap      | Visible flash or brightness jump            | Identical values at the cut frame                      |
+| Gentle easing on entry (`power2.out`)    | Entry velocity feels slower than exit       | Mirror the exit: `power4.out` / `expo.out`             |
+| Full off-screen exits / entries          | Wastes time and breaks the speed illusion   | Partial travel + early fade                            |
+| Lone element fading long before its cut  | Dead air at the seam                        | Fade ends ~0.02s before the cut, or use a word cascade |
+| Zoom-through on body text                | Small text at 0.75 scale is unreadable      | Only headlines and short phrases                       |
+| Scene cuts without cut-the-curve         | Static cuts feel like a slideshow           | Cut-the-curve is the default                           |

skills/faceless-explainer/references/motion-language.md

@@ -0,0 +1,156 @@
+# Motion language — the move vocabulary + the motion doctrine + the seek-safe core
+
+> The motion layer for **Step 4 (Visual design)**. When you write a frame's **time-coded shot sequence**, you name each scene's move **inline from the vocabulary below** — a named palette of the moves the golden corpus actually uses. Each move carries the **backing rule id** in this skill's local `../hyperframes-animation/rules/`; cite that id so the move resolves to a real recipe when a **frame worker** implements it in Step 5 (the worker reads the rule body in `../hyperframes-animation/rules/<id>.md` — it reproduces the move, it does not guess from the name). You name motion by **role / move name**, never by raw GSAP curve, ms, or stagger formula — the worker maps the curve. Between-frame **transitions are not yours**: story names `transition_in`, the harness injects it; that injected transition **is** the frame's exit. For cuts a worker builds INSIDE a frame (within-scene swaps, scene-to-scene seams), see the catalog in `cut-catalog.md`.
+
+A good explainer feels like one continuous film — one camera, one motion feel, **smooth and timed to the voiceover** — not a pile of slides that animate once and freeze. In an explainer the development _is_ the teaching: the formula assembling, the diagram gaining a layer, the count-up landing. The doctrine in Part 2 is load-bearing: when in doubt, do what it says.
+
+---
+
+# Part 1 — the move vocabulary
+
+Reach into this palette when naming a scene's motion. Pick the move that matches the beat, name it in the shot sequence, and cite the rule id after `→`. The blueprints (`../hyperframes-animation/blueprints/`) name these same moves in their `rule mapping`; you're drawing from one shared palette. Compose 2–4 across a shot's scenes (entrance → sequential reveal → settle), not all at once.
+
+## Kinetic type
+
+- **hard-cut / flash word-swap** — a word or line replaces the previous one on an instant cut (no fade/roll); the swap itself is the beat. → `discrete-text-sequence`
+- **in-place token cycle** — a fixed line holds and only its variable slot changes, token → token → token. → `discrete-text-sequence`
+- **per-word staggered reveal** — a phrase assembles word-by-word (or chunk-by-chunk), each landing on its own beat. → `dynamic-content-sequencing`
+- **kinetic beat-slam** — short phrases slam in on a shared percussive beat array, each with a distinct entrance, resolving on a locked finale; the recipe for "punchy / rhythmic" taglines. → `kinetic-beat-slam`
+
+## Typewriter
+
+- **type-on with caret** — text types in character-by-character behind a blinking caret. → `discrete-text-sequence` (+ `context-sensitive-cursor` for the caret blink / color)
+- **backspace-and-retype** — the line types, deletes the last word(s), and retypes a new one (typo-correction, reframe). → `discrete-text-sequence` (+ `context-sensitive-cursor`)
+
+## Count-up / data
+
+- **value-scaled counter** — a number counts up and its font size grows with the value, so the climb itself escalates. → `counting-dynamic-scale`
+- **bars / progress / star wipe** — a number paired with a graphic that fills: bar-height stagger, a progress bar / ring filling, a fractional star-rating wipe. → `stat-bars-and-fills`
+
+## Reveal / decode
+
+- **3D char flip-decode** — characters flip in 3D and resolve from scrambled glyphs to the real text (decryption feel). → `hacker-flip-3d`
+- **SVG self-draw** — an outline / icon / ring draws itself stroke-by-stroke. → `svg-path-draw`
+
+## Camera
+
+- **push / focus / drift** — a sequential camera move on the frame root (pull-back → focus → push) plus continuous micro-drift; the cinematic baseline. → `multi-phase-camera`
+- **zoom-to-target** — zoom into a non-centered element (scale + counter-translate to keep it framed). → `coordinate-target-zoom`
+- **pan / focus-lock** — a virtual camera transforming one `.world` wrapper to pan / zoom / lock onto a region. → `viewport-change`
+- **camera-cursor-tracking** — the viewport locks to a moving focal point (a typing cursor), static framing then focal-locked tracking. → `camera-cursor-tracking`
+
+## Layout motion
+
+- **cluster→outward expansion** — elements start clustered at center and expand outward to their final positions in lockstep. → `center-outward-expansion`
+- **orbit** — elements flip in from 3D space and settle into a continuous elliptical orbit (entry flips in-place at the orbital position). → `orbit-3d-entry`
+- **split-tilt cards** — two cards side-by-side with opposing rotationY tilts, entering from their respective sides (comparison / before-after). → `split-tilt-cards`
+- **logo/avatar ring + connectors** — avatars or logos on an elliptical ring with SVG connection lines to a center point, staggered entry. → `avatar-cloud-network`
+
+## Surface / UI
+
+- **3D page-scroll reveal** — a full webpage as a tilted 3D card whose internal content scrolls to reveal specific sections. → `3d-page-scroll`
+- **cursor click + ripple** — a cursor moves to a target, depresses with it on click, and emits an expanding ripple. → `cursor-click-ripple`
+- **button press** — a tactile press: compression then spring recovery, optional release burst / glow. → `press-release-spring` (or `physics-press-reaction` for a click that compresses cursor + target together)
+- **keyword glow** — keywords light up with glow + scale + color on an attack-decay-rest envelope, synced to a word rail. → `asr-keyword-glow`
+
+## Morph / handoff
+
+- **scale-swap** — two elements at the same screen center hand off: the outgoing cluster shrinks + fades as the incoming one arrives. → `scale-swap-transition`
+- **card morph-anchor** — a container morphs apparent size + corner radius + surface between two shots, then fades to reveal the real target beneath (HyperFrames uses uniform `scale`, not `width`/`height`). → `card-morph-anchor`
+
+## Seam cuts (worker-built, inside a frame)
+
+The velocity-matched cuts a worker authors between a frame's own Scenes. Name the seam in the shot sequence; the recipe is in the catalog, not a single `../hyperframes-animation/rules/` id.
+
+- **zoom-through / inverse zoom-through** — a within-scene swap on the Z-axis; forward reads "progressing through", inverse reads "arriving at" (payoff). → `cut-catalog.md`
+- **cut-the-curve** — a scene-to-scene cut where both sides move the same direction at matched velocity. → `cut-catalog.md`
+- **waterfall cut** — cut-the-curve at word granularity, a wave across a text-to-text seam. → `cut-catalog.md`
+
+## Emphasis / marker
+
+- **highlight / circle / burst / scribble** — a marker-drawn emphasis on a word or element: yellow highlight sweep, hand-drawn circle, radiating burst, scribble, or rough sketch-outline. → `css-marker-patterns`
+
+## Aliveness during a hold (use sparingly — see Part 2)
+
+- **subtle jitter** — the sanctioned way to keep a settled frame alive: a small, low-amplitude positional/scale jitter on the held element. The motion-graphics trick that reads "alive" without reading "weak." → `sine-wave-loop` (low-amplitude register)
+- **live SVG internals** — internal SVG parts move so an icon feels alive (rotating hands, oscillating blades, pulsing dots, dash-flow); fine because it's the subject doing something, not a card breathing. → `svg-icon-enrichment`
+- **finite bounded ambient** — a single bounded breathe/drift on ONE held hero, only when genuinely needed; de-emphasized — prefer sequential reveal or jitter first. → `sine-wave-loop`
+
+## The added moves — now backed by local rules
+
+Five moves the golden corpus needs were added to this skill's `../hyperframes-animation/rules/`, rounding out the vocabulary above:
+
+- **depth-of-field / selective-blur** — blur the off-focus subset to spotlight the focal element → `depth-of-field-blur`
+- **motion-blur streak** — directional velocity blur on a fast fly-in / camera push-through → `motion-blur-streak`
+- **3D depth scatter-assemble** — glyphs/elements scatter into a tumbling 3D cloud, then reassemble → `depth-scatter-assemble`
+- **spring-pop entrance** — the canonical entrance pop; default to a smooth long-tail settle, overshoot only when explicitly playful → `spring-pop-entrance`
+- **ambient glow / bloom** — un-triggered soft glow blooming behind a static hero → `ambient-glow-bloom`
+
+---
+
+# Part 2 — the motion doctrine (load-bearing)
+
+These four rules are the difference between a clip that reads as a serious explainer and one that reads as an agent-made PowerPoint. Follow them as written.
+
+## 1. Smooth beats bouncy — `power3` is the default
+
+Elements should use **long-tail decel curves that let them settle smoothly. `power3` is enough in most cases.** No bouncy, no overshoot, no `back.out` / `bounce.out` / `elastic.out` as a default.
+
+Bouncy is the **#1 instant turn-off** in user-made Remotion / HyperFrames videos, and the agent almost never gets it right — it thinks bouncy adds emphasis, but it buys that emphasis at the cost of cleanliness. The serious motion-design shops feel the same. **Smooth always wins.** Overshoot is demoted to a **rare, explicitly-playful exception** (a consumer/fun logo slam, a deliberate bell-hit) — never the house style. Name the intent as a long-tail settle; the worker maps `power3` (or `expo.out` on a fast arrival). See `../hyperframes-animation/rules/spring-pop-entrance.md` — it now leads with the smooth settle. (The exact form of that settle is a critically-damped spring; the worker has a baked, seek-safe `springEase` — ζ=1 — in `../hyperframes-animation/adapters/gsap-easing-and-stagger.md` → Spring Eases for when the settle is the hero. Real physics, same doctrine — not a license for bounce.)
+
+## 2. Sequential reveal in the back ~50%, timed to the voiceover
+
+This is the anti-PowerPoint mechanism — sharper than "put development in the middle."
+
+- **Don't dump everything on screen in the first ~25%** of the scene. Rushing all content in up front is exactly what forces the slideshow feel.
+- **Reveal each piece — a line, a card, even an h1 — when the voiceover mentions it**, sequencing reveals across the **later ~50%** of the scene. Same amount of agent work, but the cut becomes coherent and gains rhythm.
+- **Less is more.** Fewer things on screen, each arriving on its VO beat, beats a full canvas that animated once and froze.
+
+Practically: a frame's shot sequence front-loads almost nothing — the entrance carries only what the VO is saying at t=0, and the rest of the elements wait in the timeline for their spoken cue. A reveal maps onto a development-class move from Part 1 (`per-word staggered reveal`, `cluster→outward expansion`, a `count-up`, an `asr-keyword-glow` synced to the word rail).
+
+## 3. No lazy breathing, no bad pan/push — "no motion over bad motion"
+
+The agent's two reflexive ways to fake "aliveness" both read cheap:
+
+- **No lazy breathing.** Scaling cards/text up and down in a circular loop to look "alive" is the cheap tell. Don't reach for it.
+- **No bad slow pan / push in the back half.** A slow pan or push on elements in the later ~50% of a scene **disrupts the viewer's sightline and causes eye discomfort** — it actively makes the frame worse, not better.
+
+The fix for both is the same: **stagger element reveals in time with the script** (rule 2). And the governing principle: **"I'd rather have NO motion than BAD motion."** A held, still frame is better than a frame kept "alive" by breathing or a drifting camera. The **only sanctioned aliveness** during a hold is **subtle jitter** — a small low-amplitude jitter that keeps a frame from feeling dead without looking weak (it's in Claude videos now). Everything else holds.
+
+## 4. Internal seams are velocity-matched cuts
+
+When a frame has an internal seam — a within-scene swap, a Scene-to-Scene cut, a text-to-text line change — make it a **velocity-matched cut**, not a hard slideshow cut: cut at peak velocity, match direction and speed on both sides. The catalog (the four techniques, the blur logic, and which to use when) is `cut-catalog.md`; the moves are listed under **Seam cuts** in Part 1.
+
+## One-line summary
+
+Smooth long-tail (`power3`) over bouncy; reveal sequentially in the back ~50% timed to the VO (not dumped in the first 25%); no lazy breathing and no bad slow pan/push — prefer stillness, with subtle jitter as the only aliveness; cut at peak velocity with matched direction/speed (→ `cut-catalog.md`).
+
+---
+
+# Part 3 — the seek-safe core (hard rules)
+
+The frame is a **paused GSAP timeline seeked frame-by-frame**, so some "continuous" intents from a real-time engine can't render — don't name them. These are non-negotiable regardless of doctrine.
+
+- **No infinite / forever motion** — "particles loop endlessly," "logo rotates forever," "marquee on repeat." Any aliveness (the subtle jitter, a live SVG internal, a needed bounded ambient) is a **finite tween over the hold**, never `repeat` / `yoyo`.
+- **No randomness or wall-clock** — no `Math.random` particle fields, no `Date.now` drift. Every render must be identical; name deterministic motion only (stagger and any variation derive from the element index).
+- **Entrances use `fromTo`** — state the from-state explicitly so a seek to `t=0` lands the element correctly; never rely on a CSS-hidden start (it renders visible before the tween claims it, and flickers under seek).
+- **No CSS `transition` / `@keyframes` for motion** — CSS animation runs on the browser clock, independent of the HF seek clock; it desyncs and flickers. Drive all motion inside the paused GSAP timeline.
+- **Entrance + sequential reveal only — no mid-video exit.** The frame unmounts via the harness transition; that injected `transition_in` **is** the exit. Exit motion belongs only to the final frame. (Worker-built seam cuts in `cut-catalog.md` are within-frame, not the frame's exit.)
+
+## Forbidden — the failure modes
+
+**Slideshow (the primary failure):** everything dumped on screen in the first ~25%; content enters then freezes; nothing revealed on its VO cue. Fix with rule 2 (sequential reveal timed to the VO).
+
+**Cheap aliveness:** circular breathing as "life"; a slow pan/push in the back half disrupting the eye; many elements floating independently as "motion." Fix with rule 3 (stillness + subtle jitter only).
+
+**Bouncy:** `back.out` / `bounce.out` / `elastic.out` as the default entrance; hand-keyed overshoot. Fix with rule 1 (`power3` long-tail; overshoot only when explicitly playful).
+
+**Always:** no `repeat` / `yoyo`; no `Math.random` / `Date.now`; no all-elements-entering-simultaneously (sequence or stagger).
+
+## Naming motion in a shot — example
+
+> Scene 1 (0.0–1.0s): solid field; hero headline enters via **per-word staggered reveal** (`dynamic-content-sequencing`) on a smooth long-tail settle (`power3`); slow **push** on the root (`multi-phase-camera`) holds steady — no back-half re-push.
+> Scene 2 (1.0–3.0s): as the VO names each step, five mechanism nodes reveal **sequentially** via **cluster→outward expansion** (`center-outward-expansion`), then a **value-scaled counter** (`counting-dynamic-scale`) ticks up beneath them — the back-half reveal, timed to the script, not dumped at t=0.
+> Scene 3 (3.0–4.2s): hold on the result; **keyword glow** (`asr-keyword-glow`) lands on the payoff word as the VO says it; settles and holds still — at most **subtle jitter** (`sine-wave-loop`, low amplitude) keeps it alive; no breathing, no drift.
+
+Name the move + its rule id (or `cut-catalog.md` for a seam cut) per scene; let the worker pick curves, ms, and stagger — defaulting to `power3`.

skills/faceless-explainer/references/story-design.md

@@ -0,0 +1,248 @@
+# Story design — faceless explainer video
+
+Use this reference in Step 3 to write `STORYBOARD.md` and `SCRIPT.md` for a faceless explainer — a topic, concept, how-to, listicle, or narrative explainer built from text, with **no product, no website, and no captured assets**.
+
+This file defines the story: what the video teaches, in what order, and why each frame exists. It does not define layout, visual effects, animation, or final markdown schemas. For exact file syntax, follow `../hyperframes-core/references/storyboard-format.md` and `../hyperframes-core/references/script-format.md`.
+
+## Read first
+
+Read these inputs before writing:
+
+1. `hyperframes.json` — locked brief: angle, length, aspect ratio, language.
+2. `frame.md` — tone, mood, design system, and register.
+3. `capture/extracted/visible-text.txt` — the article / notes / topic / brief (the source of **information**).
+4. `user_script.txt` and `VO_MODE`, when the user pasted a script.
+
+There is no `asset-descriptions.md` and no `capture/assets/` to inspect — this is faceless. Every visual is invented downstream (Steps 4-5); your job here is the **narrative**, not a visual asset list.
+
+## Output
+
+Create two files:
+
+- `STORYBOARD.md` — the teaching plan, one frame per beat.
+- `SCRIPT.md` — the locked narration, only for spoken frames.
+
+Every storyboard frame must include the required fields from the storyboard format reference, plus the narrative metadata below.
+
+## Core rule
+
+An article is an information dump. A video is a guided act of understanding.
+
+Do not follow paragraph order. Reorder, merge, omit, and compress the source text into a clear teaching sequence. Strip the asides; surface the spine. **The single most common failure is paraphrasing the article in order — do not do that.** The input text is the source of information, not a story template.
+
+## Step 3 method
+
+### 1. Extract the teaching truth
+
+From the brief and text, identify:
+
+- Audience — who the video is speaking to, and what they already (don't) know.
+- Gap or stakes — the confusion, question, or "why care" the explanation resolves.
+- Thesis — the one-line idea the viewer should walk away with.
+- Spine — the 3-6 ideas (mechanisms / steps / items / beats) that build to the thesis.
+- Evidence — the concrete numbers, examples, comparisons, or worked cases that ground it.
+- Landing — the takeaway or the call to think / try / act.
+
+Write the storyboard around the thesis, not around the article's sections.
+
+### 2. Match the register to `frame.md`
+
+Use `frame.md` as a soft guide — the visual system tunes the **voice**, not the structure:
+
+| `frame.md` signal              | Story effect                           |
+| ------------------------------ | -------------------------------------- |
+| warm, handmade, notes-like     | plain, considered, low-hype; humane    |
+| bold, poster-like, declarative | short punchy beats, confident claims   |
+| friendly, polished, modern     | approachable direct address, lighter   |
+| literary, technical-but-human  | thoughtful, precise; safe for code/dev |
+
+The teaching truth decides the arc. The visual system tunes the voice.
+
+### 3. Choose one explainer structure
+
+Pick **one** structure (or explicitly name a compound). Do not splice phases from different structures — each is a complete path through understanding.
+
+| Structure           | "It is…"                                         | Use when the payload is…                                    | Body shape                                                           |
+| ------------------- | ------------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `concept-explainer` | "what is X, and why does it matter"              | one idea/term/phenomenon the audience half-knows            | name concept → reveal mechanism layer by layer → land implication    |
+| `how-to-process`    | "here is how to do / how X works," ordered steps | a procedure or mechanism with a clear start→finish          | a 3-6 step sequence on a consistent visual stage, one move each      |
+| `listicle`          | "N things about X"                               | a set of parallel, co-equal items (tips, mistakes, reasons) | hook → N roughly co-equal items → wrap; rule-of-three is strongest   |
+| `story-explainer`   | teach through a narrative arc                    | case studies, histories, cautionary tales                   | setup → tension → turn → resolution → lesson; the lesson generalizes |
+
+**Choosing:** one idea to understand → concept; an ordered procedure → how-to; parallel co-equal items → listicle; a concrete narrative/case → story.
+
+**Compounds** layer an outer arc with an inner rhythm — e.g. `concept-explainer with process` (ordered steps inside the mechanism phase), `story-explainer with how-to`. Set `arc` in the frontmatter to the chosen structure (or `<outer> with <inner>`). The downstream visual phase reads it for pacing: a process inner rhythm means tighter seams on a consistent stage and shorter frames.
+
+### 4. Build the frame sequence
+
+Each frame needs one clear job. Avoid frames that only say "more detail" or "another point."
+
+For every frame, define (use the storyboard format's fields, with these narrative additions in the frame's metadata + prose):
+
+- `type` — one of `hook | pain_point | product_intro | feature_showcase | benefit_highlight | social_proof | branding | cta`. This enum is shared with the downstream visual layer for pacing; **repurpose** it for teaching per the mapping below.
+- `persuasion` — a **named** rhetorical / clarity technique (see catalog), not "explain the idea."
+- `beat` — the target feeling (see vocabulary).
+- `scene` — a one-line visual idea, not detailed composition.
+- `voiceover` — spoken guide text, or empty for silent frames.
+- `transition_in` — a registry transition name (see Transitions).
+- `blueprint` _(optional candidate)_ — consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`; when a proven shape fits this beat, tag its id (a tag, not a commitment — Step 4 confirms or overrides). Then **write the `voiceover` in the shape that blueprint implies**, so the line is reveal-ready before Step 4 ever runs. Teaching truth still decides which beats exist — never invent, drop, or bend a beat just to fit a shape; omit `blueprint` and write the line plainly when none fits.
+
+In the prose under each frame, state:
+
+- `narrativeRole` — the scene's **job** in the explanation (e.g. "Concretizes compound interest as a snowball," not "Shows a chart").
+- `keyMessage` — the one thing the viewer should understand after this frame (one sentence).
+
+### Type-enum repurposing (shared enum → explainer roles)
+
+The enum is shared with the downstream visual layer; map your explainer roles onto it so downstream pacing matches the frame's job:
+
+| Explainer role you want          | Use `type`          | Why this value                                                       |
+| -------------------------------- | ------------------- | -------------------------------------------------------------------- |
+| Hook / curiosity gap             | `hook`              | The high-leverage opening 3-5s.                                      |
+| Pain / problem / why-care        | `pain_point`        | The friction or gap the explanation resolves.                        |
+| Name the core concept            | `product_intro`     | "Introduce the protagonist" — here the protagonist is the **idea**.  |
+| Mechanism / step / item          | `feature_showcase`  | A unit of the body — one move of a process, one mechanism, one item. |
+| Implication / payoff / "so what" | `benefit_highlight` | The consequence or value of understanding.                           |
+| Evidence / example / data point  | `social_proof`      | A concrete grounding: a number, a worked example, a comparison.      |
+| Thesis / takeaway / principle    | `branding`          | The philosophical landing — the generalizable idea, the one line.    |
+| Call to think / try / act        | `cta`               | The closing ask — try it, watch for it, question it.                 |
+
+The body is usually a run of `feature_showcase` (steps/mechanisms/items), interleaved with `benefit_highlight` (implications) and `social_proof` (examples/data). At least one `feature_showcase` or `product_intro` should exist (every explainer has a body and a named idea).
+
+## Hook strategy
+
+Pick one opening strategy for the first 3-5 seconds. For explainers the hook opens a cognitive gap or stakes:
+
+| Strategy               | Use when                                           | Example                                                          |
+| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
+| Shocking statistic     | A credible number quantifies the stakes.           | "90% of plastic ever made has never been recycled."              |
+| Rhetorical question    | Create an immediate cognitive gap.                 | "Why does time seem to speed up as you get older?"               |
+| Counterintuitive claim | The truth contradicts common belief.               | "Adding more lanes to a highway makes traffic worse."            |
+| Pain validation        | The audience already feels the confusion.          | "Everyone says 'just diversify' — nobody says what that means."  |
+| Visceral metaphor      | The idea is abstract and needs to become concrete. | "Your attention is a spotlight, and apps fight over the switch." |
+| Concept announcement   | The term itself is the subject; make it memorable. | "There's a word for this: the bystander effect."                 |
+| Direct address         | The audience is clearly defined.                   | "If you've ever rage-quit a recipe halfway — this is for you."   |
+| Imagine / scenario     | A thought experiment frames the whole piece.       | "Imagine money that loses value if you don't spend it."          |
+| Stakes / consequence   | The "why care now" is a real cost or risk.         | "Get this one step wrong and the whole batch is ruined."         |
+
+The hook must create curiosity, tension, or stakes. Do not open with a generic definition. Per `../hyperframes-creative/references/story-spine.md`: the hook speaks the viewer's language (the payoff of understanding, never the source text's section headings), and the thesis (`message`) lands by beat 2 — the explanation after that is its evidence.
+
+## Clarity / rhetoric technique catalog
+
+`persuasion` is a **named technique** — how this frame makes the idea land or clear — not a vague intent. Combine when several are active (e.g. "Analogy + progressive disclosure").
+
+| Family               | Techniques                                                                                                                                   |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Make-concrete**    | Analogy / metaphor · Concretization (abstract → tangible object) · Worked example with real numbers · Anchoring on a familiar referent       |
+| **Reveal-in-order**  | Progressive disclosure (one term/layer at a time) · Build-up (simple → general case) · Signposting ("first… then… finally")                  |
+| **Contrast**         | Before/after · Common-belief vs reality · Comparison of two options · Counterexample (here is when it breaks)                                |
+| **Structure**        | Rule of three · Numbered enumeration · Question→answer pairing · Frame-then-fill (state the shape, then populate it)                         |
+| **Evidence**         | Statistical proof · Citation / source · Demonstration (show the mechanism running) · Causal chain (A → B → C)                                |
+| **Memory & landing** | Callback (return to the hook's image) · Distillation (compress to one line) · Coined term / mnemonic · Generalization (specific → principle) |
+
+When no catalog technique fits, name a new one inline and explain its mechanism (e.g. "Subtractive framing: define the concept by what it is _not_ first"). Never write generic "explain the idea."
+
+## Emotional beats
+
+`beat` is one word or a short compound phrase (e.g. "Curiosity and clarity"). Avoid generic "positive" / "interested." Explainers ride a comprehension arc:
+
+- **Negative valley** — _open the gap_ (hook / pain_point): curiosity · puzzlement · surprise · tension · concern · skepticism · recognition · intrigue
+- **Pivot** — _orient_ (product_intro / concept-naming): clarity · orientation · anticipation · focus
+- **Build** — _build understanding_ (feature_showcase / benefit_highlight / social_proof): comprehension · "aha" · confidence · fascination · foresight · momentum · conviction · delight · unease (for a caveat) · mastery
+- **Resolution** — _land_ (branding / cta / final): clarity · satisfaction · resolve · inspiration · inevitability · "now I get it"
+
+Compound beats are often strongest, e.g. "Surprise + recognition", "Comprehension + delight."
+
+## The body is a sequence, not a single frame
+
+An explainer's core is almost always **3-6 body frames on a consistent visual stage**, each advancing one mechanism / step / item / layer, building understanding cumulatively. A single isolated body frame rarely teaches anything.
+
+- **concept-explainer:** name the concept (`product_intro`) → reveal the mechanism layer by layer (a run of `feature_showcase`, interleaving `benefit_highlight` for "so what" and `social_proof` for a grounding example).
+- **how-to-process:** `feature_showcase` per step, ordered, on one stage. Carry the object being acted on across adjacent steps (see Continuity).
+- **listicle:** `feature_showcase` per item; items are parallel, so default to `cut` / `push-slide` between them.
+- **story-explainer:** frames follow the beats (setup / tension / turn / resolution / lesson); types map per the table (`pain_point` for tension, `branding` for the lesson).
+
+## Continuity across frames (no worker grouping)
+
+This framework builds **one frame per worker** — there is no "continue run" that hands several frames to one worker. A sequence of frames reads as one continuous shot through two storyboard-level levers, both yours:
+
+1. **A consistent stage** — consecutive body frames share the same composition idea (same diagram growing, same number line, same desk), stated in each frame's `scene` so Step 4 and the workers keep the stage stable.
+2. **A consistent transition** — pick one seam type for a sequence (usually `push-slide <DIR>` for ordered steps, `crossfade` for a soft layer reveal) and repeat it across the run, so the frames feel like one flow rather than separate slides.
+
+When a single element genuinely _transforms_ between two ideas (a diagram node becomes a chart bar, a formula becomes its result), keep it within **one frame** as a development beat (entrance → the transform → settle) rather than splitting it across a seam — the worker owns that motion. Note the intent in the frame's `scene` / narrative; Step 4 turns it into a time-coded shot sequence (instantiating the candidate `blueprint`).
+
+## Transitions
+
+Use only registry transition names in `transition_in`:
+
+`cut | crossfade | blur-crossfade | push-slide LEFT | push-slide RIGHT | push-slide UP | push-slide DOWN | zoom-through | squeeze`
+
+Pick 2-3 transition types for the whole video and repeat them. Frame 1 uses `cut` as a placeholder (there is no previous frame). Match the seam to the narrative: ordered steps → a consistent `push-slide`; a soft layer reveal or atmosphere shift → `crossfade` / `blur-crossfade`; zooming into a detail or pulling back → `zoom-through`; a clean topic switch or new list item → `cut`.
+
+## Faceless visuals — no asset inventory
+
+Every visual is invented downstream from each frame's `narrativeRole` / `keyMessage` / `scene` — typography, abstract graphics, diagrams, data-viz are all first-class. Therefore:
+
+- Do **not** write an `asset_candidates` line describing intended diagrams or typography as if they were files. Visual intent belongs in `scene` + `narrativeRole`; the visual phase reads those.
+- The **only** real asset is a user-supplied image already placed at `public/<basename>`. Then add one line `asset_candidates: public/<basename> — <≤25 words: what it is>`. Never invent paths or reference `capture/`.
+
+## Script rules
+
+### If there is no pasted script
+
+Write tight per-frame narration:
+
+- 1-2 sentences per spoken frame; usually 6-20 words.
+- Concrete and human; teach, don't read the article aloud.
+- **Write each line as discrete cues, not one run-on breath.** Step 5 reveals each on-screen piece _when the voiceover names it_ (the anti-PowerPoint mechanism). A line with clear phrase boundaries — "First the snowball — then the hill — then the speed" — hands the shot its reveal cadence for free; a single long clause leaves the frame nothing to pace to.
+- **Strong** (concretization): "Compound interest isn't addition, it's a snowball — every turn picks up the snow from the last, then more."
+- **Weak** (article-paraphrase): "The study, published in 2019, examined three cohorts and found that…" — that is reading, not explaining.
+
+Avoid: "Unlock the power of…", "Seamless experience", long noun-phrase lists, a frame that is only a filler bridge ("Or…").
+
+**Silent frames are allowed and common in explainers** — a diagram assembling itself, a worked example animating, a beat of held tension before a turn. Set `voiceover` empty and leave the frame out of `SCRIPT.md`; then `narrativeRole` + `persuasion` must carry what the script doesn't say.
+
+### If `VO_MODE = restructure`
+
+Treat `user_script.txt` as source material. Rewrite, reorder, merge, or omit to fit the chosen structure and target length.
+
+### If `VO_MODE = verbatim`
+
+Do not rewrite the user's words. Segment the script into frame-sized chunks at sentence or paragraph boundaries (you may split a long sentence at a natural clause boundary, but do not change words). Final duration follows the provided script.
+
+## Frame template
+
+Use the exact fields required by the core storyboard format. This is the narrative shape each frame should satisfy:
+
+```md
+## Frame N — Short name
+
+- scene: one clear visual idea
+- voiceover: "spoken guide text, or empty"
+- duration: rough estimate in seconds
+- transition_in: crossfade
+- status: outline
+- src: compositions/frames/NN-short-name.html
+- type: feature_showcase
+- persuasion: Progressive disclosure
+- beat: comprehension
+- blueprint: messaging-multi-phase — candidate shape from the role→blueprint menu; omit when none fits
+
+narrativeRole: What this frame does in the viewer's understanding.
+keyMessage: The one idea the viewer should remember.
+```
+
+## Final checklist
+
+Before asking for user approval, verify:
+
+- One explainer structure is named (compound only when explicitly named); the sequence is narrative-driven, not paragraph-order-driven.
+- The opening uses a named hook strategy.
+- Each frame has one job; the body builds cumulatively (a run of `feature_showcase` / `benefit_highlight` / `product_intro`), not a single isolated body frame.
+- Every frame has `type`, `persuasion` (a named technique from the catalog), and `beat` (specific, not generic).
+- Each `voiceover` is phrase-segmented into cues (each a piece Step 5 can reveal on), not one run-on clause; a candidate `blueprint:` is tagged wherever a proven shape fits, and omitted where none does.
+- The emotional arc has meaningful variation matching the structure.
+- Transitions use only registry names and repeat 2-3 types; frame 1 is `cut`.
+- A consistent stage + consistent transition carry any multi-frame sequence; a genuine element transform stays inside one frame.
+- `asset_candidates` is absent (faceless) except a real user-supplied `public/<basename>`.
+- `SCRIPT.md` contains only locked spoken narration; silent frames are intentional and omitted from it.

skills/faceless-explainer/references/visual-design.md

@@ -0,0 +1,146 @@
+# Visual design — faceless-explainer per-frame shot method
+
+> The method behind **Step 4 (Frame visual design)**. You (the orchestrator) read it to **enrich `STORYBOARD.md` frames in place** — story-design wrote the skeleton (each frame's `scene`, `voiceover`, `transition_in`, the narrative fields, and optionally a candidate blueprint id); you add how each frame **looks and moves**. The unit you write per frame is a **time-coded shot sequence** — a shot directed across its whole duration, not a static slide. You write **no HTML** (that's the frame workers). Because the explainer is **faceless, every visual is invented** — typography, abstract graphics, diagrams, data-viz — so you **design** the visual elements rather than select captured assets (there is no `capture/` to read). `frame.md` is your palette/type truth by role. Layout is a compact vocabulary in this file (the **Layout** section below), stated inline per Scene; motion vocabulary + the motion doctrine + the seek-safe core → `motion-language.md`; the proven shapes → `../hyperframes-animation/blueprints-index.md` + `blueprints/<id>.md`; concrete rules resolve in Step 5 from this skill's local `../hyperframes-animation/rules/`. Adding palette theory or a generic font rule here? Wrong home — `frame.md` + `hyperframes-creative`.
+
+## The unit is a time-coded shot sequence
+
+A frame's visual layer is **a sequence of time windows paced to the voiceover**, not a bag of effect tags. The failure that reads as PowerPoint is **front-loading**: the agent rushes the whole canvas on screen in the first ~25%, and then it just sits. A time-coded shot sequence written **against the VO** makes that impossible: each window states what is on screen and what is moving, and **nothing appears before the voiceover reaches it.** In an explainer the development _is_ the teaching — the formula assembling term by term, the diagram gaining a layer, the count-up landing the statistic. Let the build _be_ the message.
+
+Write each frame as a handful of windows cued by the spoken line:
+
+```
+Scene 1 (0.0–Xs):  only what the VO is saying at t=0 enters — never the whole canvas
+Scene 2 (Xs–Ys):   the next piece reveals as the VO names it (a line / layer / node / stat)
+  …                one window per spoken cue — as many or as few as the line calls for
+Scene N (…–end):   content has resolved; hold the read (stillness; subtle jitter at most)
+```
+
+- Each `Scene` line names **what's on screen**, **what moves in this window**, and **where it sits** (layout, inline). Times are real seconds across the frame's `duration`.
+- **Pace reveals to the voiceover; never front-load.** This is the core anti-PowerPoint mechanism (→ `motion-language.md` Part 2 Rule 2). At t=0 show only what the VO is saying then; reveal each further piece — a line, a layer, even an h1 — **when the VO names it**, spreading reveals across the shot and especially the **back ~50%**. **The window count = the number of spoken cues the line calls for** — a two-beat line is two windows, a five-item enumeration is five or six. There is **no fixed count and no mandatory "middle" act**; the only sin is dumping everything up front. (A **silent** frame — a diagram assembling itself, a worked example animating — paces its reveals to the beat instead of the VO; same discipline, no spoken cue.)
+- **End on a held read.** Once the content has resolved it holds and reads — **prefer stillness to bad motion**: no forced camera drift, no lazy breathing, no back-half pan/push; at most a subtle jitter keeps it alive (→ `motion-language.md`). On a short shot the final reveal and the hold are the **same window** — the hold is not a separate mandatory act. Only the final frame has a real exit; every other frame's exit is the harness transition (story's `transition_in`).
+- A **deliberately held** frame — content already revealed, now reading still — is legitimate and often right (a climax, a breather, a beat of held tension before a turn). The failure is never "too still"; it is **front-loaded-then-frozen** (everything dumped by ~25%, nothing cued to the VO). Place held beats deliberately for rhythm so the video isn't uniformly busy (allocate them in `## Video direction`). Reveal pacing + holds + the idle budget → `motion-language.md`.
+
+## Pick the shape — instantiate a blueprint
+
+Don't invent each shot from scratch. The frame's **role** (its `type` / `beat`) points to a proven shape:
+
+1. **Match the role to a blueprint.** Open `../hyperframes-animation/blueprints-index.md`, find the frame's role in the **role→blueprint menu**, and pick the blueprint whose intent fits this beat (story may already have named a candidate id — confirm or override it). Read that `blueprints/<id>.md`: it is a short, domain-agnostic, **time-coded shot template with `[slots]`** and a named **signature move** (the thing that makes the shape itself — the SVG ring, the push-THROUGH, the in-place token swap).
+
+2. **Instantiate its `[slots]` with THIS frame's invented content** — three postures:
+   - **Reproduce** — the blueprint fits the beat and your content maps onto its slots cleanly. Fill every `[slot]` with this frame's word / shape / stat and follow its Scene timing. Write the resulting Scene lines.
+   - **Adapt** — the _structure_ fits but the content / element-count / surface doesn't (or you want a fresher surface to avoid templating). State **what you keep / what you change** in one line, then write the adapted Scene lines. You may extend or vary; you may **never** drop the **signature move** (drop it and you picked the wrong blueprint), and you keep the reveals **paced to the VO** — never collapse the shape to a single front-loaded dump.
+   - **Compose** — no blueprint fits the beat. Build the shot from the **motion vocabulary** in `motion-language.md`: still pace the reveals to the VO across the shot, never fire everything at t=0. Mark it `blueprint: compose`.
+
+3. **Keep the signature move.** Whichever posture, the blueprint's signature move (named in its file) is the spine of the shot — it usually lands on the shot's key reveal. Carry it through.
+
+The blueprint's own Scene lines, motion vocabulary, and `rule mapping` are your raw material; you are choosing a shape and casting this frame's invented content into it, not copying an engineering spec.
+
+## What you add to each frame
+
+Story-design's `## Frame N` block already carries the narrative. You append the shot. Story's `scene` / `voiceover` / `transition_in` / role fields stay untouched.
+
+```
+## Frame 3 — How interest compounds
+- scene: a snowball rolls downhill, gaining a labeled ring each turn   ← refine only if it could read sharper
+- voiceover: "…"            ← story's; leave it
+- transition_in: crossfade  ← story's; leave it
+- type: feature_showcase    ← story's
+- persuasion: Concretization + progressive disclosure
+- beat: comprehension
+- blueprint: dataviz-countup (Adapt)   ← you add: the id you instantiated (or "compose")
+- focal: the snowball                  ← you add: the INVENTED hero element of this beat
+- roles: snowball = foreground subject · hill = background gradient (dim ~40%) · ring labels = supporting   ← you add: role per invented element
+- sfx: whoosh-soft, tick               ← you add: the sound the beat wants (fetched + mounted at root; never yours to embed)
+
+Adapt: keep the count-up-ring signature; the trend chart becomes the snowball's labeled rings climbing.
+Scene 1 (0.0–1.2s): solid hill gradient (dim ~40%); the snowball seats upper-left, a circular progress ring + bold center number anchor it — Centered template, ~50% of frame. Slow push-in runs underneath.
+Scene 2 (1.2–3.4s): as the VO names each turn, the snowball rolls down and gains one labeled ring per turn (layer-reveal); a small total ticks up beside it (the count-up reveals on its spoken cue, not at t=0). Asymmetric 60/40, 3 depth layers.
+Scene 3 (3.4–5.0s): land the final ring emphasis dead-center, accent glow blooms behind it and holds; the total reads clean and STILL — no continuing push, no breathing (a held beat beats bad motion). The stillness reads against the prior motion.
+```
+
+The lightweight tags:
+
+- **`blueprint:`** — the id you instantiated (with `(Reproduce)` / `(Adapt)`), or `compose`. One id per frame.
+- **`focal:`** — which **invented** element is the hero of this beat (a hero word, a diagram node, a chart series, a coined-term card).
+- **`roles:`** — each invented element's role: `foreground subject` (the thing the eye lands on, text laid around it) · `background` (full-bleed field / gradient / grid, dim 30–50%) · `supporting` (labels, secondary shapes, ambient layers). Since there are no captured assets, you are **designing** these elements, not selecting them — keep them **few and load-bearing**. A user-supplied `public/<basename>` image, if any (named in story's `asset_candidates`), is treated as the `focal` cutout or a `background`.
+- **`sfx:`** — name the sound the beat wants (an impact for a slam, a whoosh for a push, a tick for a count). The audio script's `fetch-sfx` pass retrieves it and the assembler mounts it at the root — you only **name** it, never embed an `<audio>` element.
+
+**Layout is stated INLINE in each Scene line** — name the template, density, depth, and hierarchy as part of "where it sits" (`Centered, ~50% of frame`, `asymmetric 60/40, 3 depth layers`), drawing on the **Layout** vocabulary below; never write px / scale / shadow recipes (the worker writes those).
+
+**Motion is named INLINE in each Scene line** — name the move from `motion-language.md`'s vocabulary (`per-word reveal`, `layer-reveal`, `count-up`, `glow blooms`) and let it settle on a long-tail curve (`power3` default — smooth beats bouncy; see `motion-language.md`). Never write ease curves / ms / stagger (those resolve in Step 5 from this skill's local `../hyperframes-animation/rules/`).
+
+## Inventing the visual — diagrams, type, data-viz
+
+This is a **faceless** explainer: the frame's hero is something you **design**, not a screenshot. Three first-class treatments, each invented from the frame's `narrativeRole` / `keyMessage` / `scene`:
+
+- **Typographic / kinetic type** — the hero word, the coined term, a number, a short enumeration. Treat type as the subject: full-bleed scale, weight contrast, one emphasized term. Strongest for hooks, concept names, takeaways. In a faceless explainer **type is often the primary visual** — lean on the type ramp hard.
+- **Abstract graphics** — shapes, fields, paths, geometry that _embody_ the idea (the snowball, the spotlight, the staircase-not-cliff). Build the metaphor the script names; don't decorate with generic bokeh.
+- **Diagram / data-viz** — nodes + edges, a chart, a number line, a formula, a process flow. The build (each part appearing on beat) is the teaching — design it to assemble across the Scenes, not appear whole.
+
+Make the invented hero **fill 40–60% of the frame** — a diagram big enough to read its labels, a hero word near full-bleed. Don't shrink the one designed element into decoration around empty space.
+
+## Layout — named inline per Scene
+
+State each Scene's layout as part of "where it sits." **If the blueprint already implies a composition** (a ring around a center, stations on a wide canvas, two cards from opposite wings), that wins — describe it directly; the vocabulary below is for **composing freely** or a generic beat, not a menu you must pick from. Never write px / scale / shadow (the worker does). One frame's layout can EVOLVE across its Scenes (Scene 1 centered hero → Scene 2 rearranges to a grid). Use **≥3 different framings per video** so it doesn't read as one repeated template; never the same framing twice in a row.
+
+- **Framing vocabulary** — centered (hero / climax) · rule-of-thirds · split-screen (comparison) · layered-depth (immersive opening / atmosphere) · asymmetric 60/40 or 70/30 (editorial — a dense diagram + a caption rail) · triptych (three items / the rule-of-three landing) · full-width strip (a number line / timeline / enumeration). Vary the framing across the video so it doesn't read as one repeated template — let the beat decide, not a quota.
+- **Density** — primary visual ≥ 40% of canvas; ≥ 3 depth layers (background + midground + foreground); never a lone small cluster floating in empty space. Openings and closings are prone to emptiness — add environmental layers (dual-radial swell, low-opacity scanlines, a hairline grid, brand-color ambient). Squint test: after blur you can still pick out the #1 element.
+- **Hierarchy** — combine ≥ 2 of size (3:1) / weight (800 vs 400) / contrast / position (upper-third is golden) / motion, so one element clearly dominates. A title that is only _larger_ (sharing weight/color/spacing with body) reads weak.
+- **Depth** — layer 2–3 of: size, blur, opacity gradient, overlap, shadow-stack, counter-scale on a push.
+- **Don't show**: nav bars, footers, scrollbars, real cursors / browser chrome, generic decorative shapes standing in for a designed metaphor, floating bokeh / purple-blue "AI" gradients (the default-AI cliché, banned). A faceless explainer has no real interface — an interface mock is correct **only** when the topic itself is about that interface and the frame intentionally reconstructs it.
+
+## Portrait & square (non-16:9 canvases)
+
+The zones, density, hierarchy, and depth principles all still apply; the **aspect ratio** changes, and a wide-frame layout does not transplant into a tall one — design for the storyboard's `format` from the start, never plan landscape and "crop."
+
+- **Stack vertically, not side-by-side** — split-screen / triptych / 60-40 become top/bottom stacks, vertical step lists, stacked bands. Square tolerates side-by-side only for two compact items.
+- **Vertical center moves with the canvas** — anchor a centered hero around **y ≈ 0.42 × height** (portrait ≈806, square ≈454), not a fixed 540.
+- **Type runs larger, fewer words per line** — narrow frames wrap long headlines badly; prefer short kinetic lines, bigger type, more vertical rhythm.
+- **Travels well to portrait:** Centered, Layered Depth, Full-Width Strip (stacked band), vertical Rule-of-Thirds. **Avoid** wide Split Screen and Triptych — use stacked equivalents.
+
+## `## Video direction` — write the invariants ONCE
+
+The whole video shares one look and one motion grammar. Write a **`## Video direction`** block ONCE at the top of `STORYBOARD.md` so every frame inherits it and per-frame Scene lines carry only the **delta**. This block is load-bearing — it is what binds many independent shots into one film. **Keep it.**
+
+- **palette system** — from `frame.md`: which roles map to which hues. Never invent.
+- **motion grammar + reveal model** — long-tail eases (`power3` default, smooth over bouncy) + the **VO-paced reveal** model every frame follows (reveal each piece on its spoken cue; never front-load) + what may stay alive during a hold (subtle jitter at most; no lazy breathing) (→ `motion-language.md`).
+- **rhythm / held-frame allocation** — name the **held / breather frames** (often before a climax or the turn in a story) so the video varies its energy: most frames reveal to the VO, a few hold still (a held read beats bad motion; the anti-monotony discipline; → `motion-language.md`).
+- **negative list** — what never appears: off-brand textures / effects the pack forbids, **plus both motion failure modes** — slideshow (front-load then freeze) and screensaver (everything floating independently) (→ `motion-language.md`).
+
+Do **not** repeat these per frame — restating video-level rules in every frame is exactly the bloat this layer prevents.
+
+## Palette & type — from `frame.md`, never invented
+
+- **Palette** — `frame.md` (the adopted pack) is the color truth; apply its roles per frame. Generic basics (one accent, tint neutrals, avoid pure `#000`/`#fff`) → `hyperframes-creative/references/house-style.md`.
+- **Type** — fonts resolve via `frame.md`'s type tokens; reference them **by role** (display / body / mono / the pack's ramp), never by raw family or px. Generic typography craft (embedded fonts, dark-bg optical compensation, `tabular-nums`) → `hyperframes-creative/references/typography.md`. In a faceless explainer type is often the primary visual — the hero word, the coined term, the kinetic enumeration — so lean on the type ramp hard.
+
+## Caption-band keep-out (plan side)
+
+The bottom ~17% of the canvas is reserved for the caption pill. Plan every frame's content into the **top ~83%** so nothing important lands in the band (the worker enforces the pixel cutoff; you plan the layout). When captions are enabled, primary content and key visuals **cap at the band top**, and a centered hero anchors at **y ≈ 0.42 × height** (landscape ≈454, portrait ≈806), not the canvas midpoint; background / ambient / surface layers are exempt and may stay full-bleed. Holds even when captions are disabled — bottom-edge consistency.
+
+## Where the detail lives
+
+| For…                                                                            | Read                                                                                         |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| the proven shapes + role→blueprint menu + how to pick                           | `../hyperframes-animation/blueprints-index.md` → `blueprints/<id>.md`                        |
+| motion — shot model, vocabulary, holds, idle budget, stillness, seek-safe       | `motion-language.md` (local)                                                                 |
+| layout — framing, density, depth, hierarchy, inventing the visual, caption band | the **Layout** + **Inventing the visual** sections in this file                              |
+| concrete eases / ms / stagger + rule recipe bodies (Step 5)                     | local `../hyperframes-animation/rules/` (the frame worker reads it; you don't)               |
+| palette + type tokens                                                           | the project's `frame.md`; basics → `hyperframes-creative` `house-style.md` / `typography.md` |
+| "produced, not generated" foreground density                                    | `hyperframes-creative/references/video-composition.md`                                       |
+| within-frame cuts / seams (zoom-through · cut-the-curve · waterfall)            | `cut-catalog.md` (the worker builds them inside the composition)                             |
+| transitions                                                                     | story-design owns `transition_in`; you don't touch it                                        |
+
+## Before you finish — checklist
+
+- **`## Video direction`** written once at the top (palette · motion grammar + shot model + idle budget · stillness allocation · negative list incl. both failure modes); per-frame entries are deltas, not restatements.
+- Every frame is a **time-coded shot sequence** with real second windows across its `duration` — not a tag bag.
+- **No frame front-loads** — at t=0 only what the VO is saying enters; each further piece reveals on its spoken cue, across the back ~50%. Window count follows the VO (or the beat, on a silent frame), not a fixed number.
+- Every frame names a **`blueprint:`** id (Reproduce / Adapt) or `compose`; an Adapt states keep/change and **keeps the signature move**; nothing collapses to a single front-loaded dump — reveals stay paced to the VO.
+- **Held frames are deliberate** — allocated in Video direction for rhythm; a held read is fine (prefer stillness to bad motion), but no frame may be front-loaded-then-frozen.
+- Each frame names its **invented** `focal` + per-element `roles` (foreground / background / supporting), kept few and load-bearing.
+- The invented hero fills 40–60% of the frame (a diagram big enough to read, a hero word near full-bleed) — not shrunk into decoration around empty space.
+- Layout named **inline** per Scene (template / density / depth / hierarchy — the **Layout** vocabulary here); motion named **inline** per Scene from the vocabulary (`motion-language.md`). No px / ease curves / ms / JS.
+- Content planned into the top ~83% (caption band clear).
+- Palette / type pulled from `frame.md` by role — nothing invented.
+- You wrote no HTML; every visual is invented (no captured assets).

skills/faceless-explainer/scripts/assemble-index.mjs

@@ -0,0 +1,573 @@
+#!/usr/bin/env node
+// assemble-index.mjs — deterministic top-level index.html assembly for a
+// HyperFrames project. No subagent, no judgment: turns STORYBOARD.md + the
+// built frame files (+ optional audio_meta.json) into the standalone index.html
+// the renderer consumes, and stages the frame-named capture assets into assets/.
+//
+// index.html is a *standalone* composition (root <div id="root"> directly in
+// <body>, no <template> wrapper — template is for sub-comps). Structure is
+// modeled on the canonical fixture packages/studio/fixtures/storyboard-sample/
+// index.html and the authoritative head/audio template in
+// packages/core/docs/quickstart-template.html. Frame mount order = STORYBOARD
+// document order. Transitions are NOT written here — the transitions injector
+// mutates this file afterward (data-start/duration/track-index + GSAP).
+//
+// Track lanes (same-track time-overlap is illegal — lint timeline_track_too_dense):
+//   1      frame sub-comp clips (sequential; the injector 0/1-ping-pongs for overlaps)
+//   2      captions sub-comp clip (full-duration overlay, on top of frames)
+//   10     per-frame voice <audio>
+//   11     BGM <audio>
+//   20+i   SFX <audio> (one lane each)
+//
+// audio_meta.json contract (produced by audio.mjs; OPTIONAL — absent ⇒ silent
+// video, frames only). Durations come from STORYBOARD (audio sync-durations
+// writes them), NOT from here; this file carries only media PATHS, keyed by
+// frame number:
+//   { "bgm":   { "path": "assets/bgm/x.mp3", "volume": 0.12 } | null,
+//     "voices":[ { "frame": 3, "path": "assets/voice/03.wav" } ],
+//     "sfx":   [ { "frame": 3, "file": "assets/sfx/x.mp3", "offset_s": 0,
+//                  "duration_s": 1.0, "volume": 0.35 } ] }
+//
+// Reads:  --storyboard STORYBOARD.md, --hyperframes <project root>,
+//         [--audio-meta audio_meta.json]. On disk: each built frame's src html,
+//         capture/{assets,assets/videos,screenshots}/<basename> for staging, compositions/captions.html.
+// Writes: <project>/index.html  +  stages assets/<basename>  +  (guard ① below)
+//         repairs a frame file in place when its root is missing data-width/height.
+//
+// Pre-assembly frame guards (run in the same pass that reads each frame, so common
+// `lint` failures surface HERE instead of after assembly + a wasted render):
+//   ① AUTO-REPAIR — a sub-comp root missing data-width/data-height: inject the canvas
+//      dims (the renderer needs them on the cloned root; else lint root_missing_dimensions).
+//   ② HARD FAIL  — <video>/<audio> inside a sub-comp: the runtime only drives media that
+//      is a DIRECT child of the host root, so sub-comp media renders blank/black.
+//   ③ HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
+//      and lacks class="clip" (shows the whole frame), or two same-track clips that overlap.
+//
+// Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
+// frames, a built/animated frame missing its src/file, a frame with no
+// duration, an inner data-composition-id mismatch, or a guard ②/③ violation).
+// No backstop: fix upstream.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename, join, resolve } from "node:path";
+import { parseStoryboard } from "./lib/storyboard.mjs";
+import { parseFormat } from "./lib/dimensions.mjs";
+import { stageAssets } from "./lib/assets.mjs";
+import { parseColors, semanticColors } from "./lib/tokens.mjs";
+import { bgmDefaultVolume } from "../../media-use/audio/scripts/lib/bgm.mjs";
+
+// ---------- argv ----------
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+function die(msg) {
+  console.error(`✗ assemble-index.mjs: ${msg}`);
+  process.exit(1);
+}
+
+// Ensure the BGM track is at least `total` seconds long. HeyGen (and most music
+// libraries) return a short loopable clip (~15–30s); mounting it at data-duration=total
+// would leave the video's TAIL SILENT. If the file is short, loop-extend it to `total`
+// (with a 0.4s fade-in + 1.5s fade-out) into a sibling *.loop.mp3 and return that path.
+// Needs ffprobe+ffmpeg (present in the render env); degrades to the original + a warning
+// when they're absent, so assembly never hard-fails on audio tooling.
+function ensureBgmCovers(relPath, hyperframesDir, total) {
+  const abs = join(hyperframesDir, relPath);
+  const probe = spawnSync(
+    "ffprobe",
+    ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", abs],
+    { encoding: "utf8" },
+  );
+  if (probe.status !== 0) return { looped: false, short: false, reason: "ffprobe unavailable" };
+  const dur = parseFloat(String(probe.stdout || "").trim());
+  if (!Number.isFinite(dur) || dur <= 0)
+    return { looped: false, short: false, reason: "unreadable duration" };
+  if (dur >= total - 0.1) return { looped: false, short: false, dur }; // already covers
+  const relOut = relPath.replace(/\.([^./]+)$/, ".loop.$1");
+  const absOut = join(hyperframesDir, relOut);
+  const fadeOut = Math.max(0, total - 1.5);
+  const ff = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-stream_loop",
+      "-1",
+      "-i",
+      abs,
+      "-t",
+      String(total),
+      "-af",
+      `afade=t=in:st=0:d=0.4,afade=t=out:st=${fadeOut}:d=1.5`,
+      "-c:a",
+      "libmp3lame",
+      "-q:a",
+      "2",
+      absOut,
+    ],
+    { encoding: "utf8" },
+  );
+  if (ff.status !== 0 || !existsSync(absOut))
+    return { looped: false, short: true, dur, reason: "ffmpeg unavailable" };
+  return { looped: true, rel: relOut, from: dur };
+}
+
+const hyperframesDir = resolve(flag("hyperframes", "."));
+const storyboardPath = resolve(flag("storyboard", join(hyperframesDir, "STORYBOARD.md")));
+const audioMetaPath = resolve(flag("audio-meta", join(hyperframesDir, "audio_meta.json")));
+const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));
+
+const r3 = (x) => Math.round(x * 1000) / 1000;
+const anomalies = [];
+const frameErrors = []; // fatal per-frame composition violations (guards ②/③) — reported together
+const repairs = []; // auto-repairs applied to frame files in place (guard ①)
+
+// ---------- parse storyboard ----------
+if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+const { width: WIDTH, height: HEIGHT } = parseFormat(manifest.globals.format);
+
+// ---------- per-frame composition guards (see header ①②③) ----------
+// String-level checks on each frame's HTML — no DOM parse, deterministic, run in
+// the same pass that already reads the file. OPEN_TAG matches one opening tag while
+// tolerating quoted attribute values that contain ">" (e.g. inline styles).
+const OPEN_TAG = "<([a-zA-Z][a-zA-Z0-9-]*)((?:[^>\"']|\"[^\"]*\"|'[^']*')*)>";
+const attrPresent = (attrs, name) => new RegExp(`(?:^|\\s)${name}(?:[\\s=]|$)`).test(attrs);
+const attrValue = (attrs, name) => {
+  const m = attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`));
+  return m ? (m[1] ?? m[2]) : null;
+};
+// The root (or a nested-comp mount) legitimately carries timing without class="clip".
+const isRootish = (attrs) =>
+  /(?:^|\s)id\s*=\s*["']root["']/.test(attrs) ||
+  attrPresent(attrs, "data-composition-id") ||
+  attrPresent(attrs, "data-composition-src");
+
+// Locate the composition root opening tag: prefer id="root", else the first element
+// carrying data-composition-id. Returns { start, end, full, attrs } or null.
+function findRootTag(html) {
+  const re = new RegExp(OPEN_TAG, "g");
+  let m;
+  let firstCompId = null;
+  while ((m = re.exec(html))) {
+    const attrs = m[2];
+    if (/(?:^|\s)id\s*=\s*["']root["']/.test(attrs))
+      return { start: m.index, end: m.index + m[0].length, full: m[0], attrs };
+    if (attrPresent(attrs, "data-composition-id") && !firstCompId)
+      firstCompId = { start: m.index, end: m.index + m[0].length, full: m[0], attrs };
+  }
+  return firstCompId;
+}
+
+// Returns { errors: string[], repairedHtml: string|null, repairNote: string|null }.
+function guardFrame(html, label) {
+  const errors = [];
+  // Scan a copy with comments + <script>/<style> bodies blanked, so a tag-like string
+  // in a comment (e.g. "<!-- match the host <video> coords -->") or in GSAP code can't
+  // trip ②/③. ① still splices into the ORIGINAL html, so its offsets stay correct.
+  const scan = html
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
+    .replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ");
+
+  // ② media inside a sub-comp — never driven by the runtime (renders blank/black).
+  const media = scan.match(/<(video|audio)(?=[\s/>])/i);
+  if (media) {
+    errors.push(
+      `${label}: has a <${media[1].toLowerCase()}> inside the sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html) — sub-comp media renders blank/black. Move the clip to index.html as a root-level <video>/<audio> and drive any per-scene motion on the main timeline (composition-patterns.md archetype B).`,
+    );
+  }
+
+  // ③ timed-element checks: missing class="clip", and same-track window overlap.
+  const re = new RegExp(OPEN_TAG, "g");
+  const clips = [];
+  let m;
+  while ((m = re.exec(scan))) {
+    const attrs = m[2];
+    if (
+      !attrPresent(attrs, "data-start") ||
+      !attrPresent(attrs, "data-duration") ||
+      !attrPresent(attrs, "data-track-index")
+    )
+      continue;
+    if (isRootish(attrs)) continue;
+    if (!/(?:^|\s)class\s*=\s*["'][^"']*\bclip\b[^"']*["']/.test(attrs)) {
+      errors.push(
+        `${label}: a timed <${m[1]}> (data-start/duration/track-index) has no class="clip" — it renders for the whole frame instead of only its window. Add class="clip", or remove the timing attrs if it is a GSAP-animated element meant to be present throughout.`,
+      );
+    }
+    const track = attrValue(attrs, "data-track-index");
+    const start = parseFloat(attrValue(attrs, "data-start"));
+    const dur = parseFloat(attrValue(attrs, "data-duration"));
+    if (track != null && Number.isFinite(start) && Number.isFinite(dur))
+      clips.push({ track, start, end: start + dur });
+  }
+  const EPS = 1e-3; // adjacent clips that merely touch are legal
+  const byTrack = new Map();
+  for (const c of clips) {
+    const arr = byTrack.get(c.track);
+    if (arr) arr.push(c);
+    else byTrack.set(c.track, [c]);
+  }
+  for (const [track, list] of byTrack) {
+    list.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < list.length; i++) {
+      if (list[i].start < list[i - 1].end - EPS) {
+        errors.push(
+          `${label}: clips on track ${track} overlap (one ends at ${r3(list[i - 1].end)}s, the next starts at ${r3(list[i].start)}s) — same-track time-overlap causes a render conflict. Put them on distinct data-track-index lanes or fix their windows.`,
+        );
+        break; // one report per track is enough
+      }
+    }
+  }
+
+  // ① auto-repair: ensure the root carries data-width / data-height.
+  let repairedHtml = null;
+  let repairNote = null;
+  const root = findRootTag(html);
+  if (root) {
+    const needW = !attrPresent(root.attrs, "data-width");
+    const needH = !attrPresent(root.attrs, "data-height");
+    if (needW || needH) {
+      const inject =
+        (needW ? ` data-width="${WIDTH}"` : "") + (needH ? ` data-height="${HEIGHT}"` : "");
+      const newTag = root.full.replace(/(\/?>)$/, `${inject}$1`);
+      repairedHtml = html.slice(0, root.start) + newTag + html.slice(root.end);
+      repairNote = `${label}: injected${needW ? " data-width" : ""}${needH ? " data-height" : ""} (${WIDTH}×${HEIGHT}) on the root — was missing (would lint root_missing_dimensions)`;
+    }
+  }
+
+  return { errors, repairedHtml, repairNote };
+}
+
+// ---------- resolve mountable frames in document order ----------
+// A frame mounts when its src html exists on disk. A built/animated frame
+// missing its src/file is a contract break (die). An outline frame with no
+// file is skipped (still a placeholder) with an anomaly note.
+const mounted = [];
+for (const f of manifest.frames) {
+  const label = `frame ${f.number ?? f.index}${f.title ? ` (${f.title})` : ""}`;
+  const built = f.status === "built" || f.status === "animated";
+  if (!f.src) {
+    if (built) die(`${label} is ${f.status} but has no \`src\` — the orchestrator must write it`);
+    anomalies.push(`${label}: status ${f.status}, no src — skipped`);
+    continue;
+  }
+  const compAbs = join(hyperframesDir, f.src);
+  // Read directly and handle ENOENT here rather than an existsSync precheck — the
+  // check→read/write pair is a TOCTOU race CodeQL flags (js/file-system-race).
+  let html;
+  try {
+    html = readFileSync(compAbs, "utf8");
+  } catch {
+    if (built)
+      die(`${label} is ${f.status} but its src ${f.src} is not on disk — re-dispatch the worker`);
+    anomalies.push(`${label}: src ${f.src} not on disk (status ${f.status}) — skipped`);
+    continue;
+  }
+  if (!Number.isFinite(f.durationSeconds) || f.durationSeconds <= 0) {
+    die(
+      `${label}: no positive duration (got ${JSON.stringify(f.duration)}) — run audio sync-durations`,
+    );
+  }
+  // Host data-composition-id MUST equal the inner file's, or the runtime never
+  // finds the timeline. frame_id = src basename (frame-worker contract); verify
+  // the inner html actually declares it.
+  const compId = basename(f.src).replace(/\.html?$/i, "");
+  // Guard against blank/partial scene files: a worker that errors or is
+  // interrupted mid-write leaves an empty (or markup-less) file that exists but
+  // fails at render with "Composition HTML is empty or could not be parsed".
+  // Catch it here — before emitting data-composition-src — and re-dispatch.
+  if (!html.trim() || !/<\w/.test(html)) {
+    die(
+      `${label}: ${f.src} is empty or has no HTML — the worker wrote a blank/partial file. Re-dispatch that worker before assembling.`,
+    );
+  }
+  // pre-assembly guards: ① repair missing root dims in place, ②/③ collect fatal violations.
+  const guard = guardFrame(html, label);
+  if (guard.repairedHtml) {
+    writeFileSync(compAbs, guard.repairedHtml);
+    html = guard.repairedHtml;
+    repairs.push(guard.repairNote);
+  }
+  for (const e of guard.errors) frameErrors.push(e);
+  if (
+    !html.includes(`data-composition-id="${compId}"`) &&
+    !html.includes(`data-composition-id='${compId}'`)
+  ) {
+    die(`${label}: ${f.src} has no data-composition-id="${compId}" (host/inner id must match)`);
+  }
+  mounted.push({ frame: f, compId, durationSeconds: r3(f.durationSeconds) });
+}
+if (frameErrors.length) {
+  die(
+    `${frameErrors.length} frame composition violation(s) — fix the worker output and re-assemble:\n` +
+      frameErrors.map((e) => `  • ${e}`).join("\n"),
+  );
+}
+if (mounted.length === 0) die("no mountable frames (none built with an on-disk src)");
+
+// cumulative starts — emitted data-start[i] + data-duration[i] == start[i+1] by
+// construction (renderer computes end the same way), so adjacent clips touch
+// exactly with no float-overlap.
+let acc = 0;
+for (const m of mounted) {
+  m.start = acc;
+  acc += m.durationSeconds;
+}
+const TOTAL = r3(acc);
+const startOfFrameNumber = new Map();
+for (const m of mounted) if (m.frame.number != null) startOfFrameNumber.set(m.frame.number, m);
+
+// ---------- audio_meta (optional) ----------
+let audio = { bgm: null, voices: [], sfx: [] };
+if (existsSync(audioMetaPath)) {
+  try {
+    const parsed = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+    audio = { bgm: parsed.bgm ?? null, voices: parsed.voices ?? [], sfx: parsed.sfx ?? [] };
+  } catch (e) {
+    die(`audio_meta.json parse: ${e.message}`);
+  }
+}
+const voiceByFrame = new Map();
+for (const v of audio.voices) if (v.frame != null) voiceByFrame.set(v.frame, v);
+
+// ---------- build <body> in track order ----------
+const body = [];
+let voiceCount = 0;
+
+for (const m of mounted) {
+  // (track 1) frame sub-comp clip — no class="clip" semantics needed; .scene CSS sizes it.
+  body.push(
+    `      <div`,
+    `        id="el-${m.compId}"`,
+    `        class="scene"`,
+    `        data-composition-id="${m.compId}"`,
+    `        data-composition-src="${m.frame.src}"`,
+    `        data-start="${m.start}"`,
+    `        data-duration="${m.durationSeconds}"`,
+    `        data-track-index="1"`,
+    `      ></div>`,
+  );
+  // (track 10) voice — only when the file is actually on disk.
+  const v = m.frame.number != null ? voiceByFrame.get(m.frame.number) : undefined;
+  if (v?.path) {
+    if (existsSync(join(hyperframesDir, v.path))) {
+      body.push(
+        `      <audio`,
+        `        id="el-${m.compId}-voice"`,
+        `        src="${v.path}"`,
+        `        data-start="${m.start}"`,
+        `        data-duration="${m.durationSeconds}"`,
+        `        data-track-index="10"`,
+        `        data-volume="1"`,
+        `      ></audio>`,
+      );
+      voiceCount++;
+    } else {
+      anomalies.push(`${m.compId}: voice ${v.path} not on disk — skipped`);
+    }
+  }
+  body.push("");
+}
+
+// (track 11) BGM — duck under narration when any voice is present. Loop-extend a short
+// track to the full video length so the tail isn't silent (libraries return ~15–30s clips).
+let bgmEmitted = false;
+let bgmNote = "";
+if (audio.bgm?.path) {
+  if (existsSync(join(hyperframesDir, audio.bgm.path))) {
+    let bgmSrc = audio.bgm.path;
+    const cov = ensureBgmCovers(audio.bgm.path, hyperframesDir, TOTAL);
+    if (cov.looped) {
+      bgmSrc = cov.rel;
+      bgmNote = ` (looped ${cov.from.toFixed(1)}s→${TOTAL}s)`;
+    } else if (cov.short) {
+      anomalies.push(
+        `bgm is ${cov.dur?.toFixed?.(1) ?? "?"}s (< ${TOTAL}s) and could not be extended (${cov.reason}) — the tail will be silent; install ffmpeg`,
+      );
+    }
+    // An explicit volume from audio_meta always wins; otherwise the shared
+    // media-use default (bed ~ -18 dB under narration, forward for a silent film).
+    const vol = audio.bgm.volume != null ? audio.bgm.volume : bgmDefaultVolume(voiceCount > 0);
+    body.push(
+      `      <!-- BGM -->`,
+      `      <audio`,
+      `        id="el-bgm"`,
+      `        src="${bgmSrc}"`,
+      `        data-start="0"`,
+      `        data-duration="${TOTAL}"`,
+      `        data-track-index="11"`,
+      `        data-volume="${vol}"`,
+      `      ></audio>`,
+      "",
+    );
+    bgmEmitted = true;
+  } else {
+    anomalies.push(`bgm ${audio.bgm.path} not on disk — skipped`);
+  }
+}
+
+// (track 2) captions — captions.mjs writes this or legally skips; key off existence.
+let captionsEmitted = false;
+if (existsSync(join(hyperframesDir, "compositions/captions.html"))) {
+  body.push(
+    `      <!-- captions -->`,
+    `      <div`,
+    `        id="el-captions"`,
+    `        class="scene"`,
+    `        data-composition-id="captions"`,
+    `        data-composition-src="compositions/captions.html"`,
+    `        data-start="0"`,
+    `        data-duration="${TOTAL}"`,
+    `        data-track-index="2"`,
+    `      ></div>`,
+    "",
+  );
+  captionsEmitted = true;
+}
+
+// (track 20+i) SFX — placed at its frame's start + offset.
+let sfxEmitted = 0;
+audio.sfx.forEach((cue, i) => {
+  const host = cue.frame != null ? startOfFrameNumber.get(cue.frame) : undefined;
+  if (!host) {
+    anomalies.push(`sfx ${cue.file}: frame ${cue.frame} not mounted — skipped`);
+    return;
+  }
+  const rel = cue.file;
+  if (!existsSync(join(hyperframesDir, rel))) {
+    anomalies.push(`sfx ${rel} not on disk — skipped`);
+    return;
+  }
+  const t = r3(host.start + (cue.offset_s ?? 0));
+  const dur = r3(cue.duration_s ?? 1);
+  const vol = cue.volume != null ? cue.volume : 0.35;
+  if (sfxEmitted === 0) body.push(`      <!-- SFX -->`);
+  body.push(
+    `      <audio`,
+    `        id="el-sfx-${i}"`,
+    `        src="${rel}"`,
+    `        data-start="${t}"`,
+    `        data-duration="${dur}"`,
+    `        data-track-index="${20 + i}"`,
+    `        data-volume="${vol}"`,
+    `      ></audio>`,
+  );
+  sfxEmitted++;
+});
+
+// ---------- stage frame-named assets: capture/ → assets/ (idempotent backstop) ----------
+// Frame workers + the live preview reference assets/<basename>; stage-assets.mjs
+// already ran this at Step 4 close. Re-run as a backstop so a late-named asset
+// still lands. Shared logic: lib/assets.mjs (first-wins, safe to call twice).
+const {
+  staged,
+  wanted,
+  anomalies: assetAnomalies,
+} = stageAssets({
+  hyperframesDir,
+  frames: manifest.frames,
+});
+for (const a of assetAnomalies) anomalies.push(a);
+
+// ---------- <head> ----------
+// ---------- ground color ----------
+// Per-frame roots carry data-start/data-duration and get clip-gated against the
+// global timeline in render (only the first frame's [0,dur] window overlaps global
+// 0), so a frame's own full-bleed background can't be relied on as the video ground —
+// every frame after the first would render on the bare body color (black). Paint the
+// ground on the always-present root composition instead, using the project's frame.md
+// canvas color (the same ground role the caption skin maps to --cap-canvas). Falls
+// back to the body letterbox color when frame.md is absent or has no resolvable ground.
+const framePath = join(hyperframesDir, "frame.md");
+let groundColor = null;
+if (existsSync(framePath)) {
+  try {
+    const roles = semanticColors(parseColors(readFileSync(framePath, "utf8")));
+    if (roles && roles.canvas) groundColor = roles.canvas;
+  } catch {
+    /* leave groundColor null — #root stays transparent over the body letterbox */
+  }
+}
+
+const headStyle = [
+  "      * {",
+  "        margin: 0;",
+  "        padding: 0;",
+  "        box-sizing: border-box;",
+  "      }",
+  "      html,",
+  "      body {",
+  `        width: ${WIDTH}px;`,
+  `        height: ${HEIGHT}px;`,
+  "        overflow: hidden;",
+  "        background: #000;",
+  "      }",
+  "      #root {",
+  "        position: relative;",
+  `        width: ${WIDTH}px;`,
+  `        height: ${HEIGHT}px;`,
+  "        overflow: hidden;",
+  ...(groundColor ? [`        background: ${groundColor};`] : []),
+  "      }",
+  "      .scene {",
+  "        position: absolute;",
+  "        inset: 0;",
+  "        width: 100%;",
+  "        height: 100%;",
+  "      }",
+].join("\n");
+
+const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=${WIDTH}, height=${HEIGHT}" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
+    <style>
+${headStyle}
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="${TOTAL}"
+      data-width="${WIDTH}"
+      data-height="${HEIGHT}"
+    >
+${body.join("\n")}
+    </div>
+
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>
+`;
+
+writeFileSync(outPath, html);
+
+// ---------- summary ----------
+console.log(`✓ wrote ${outPath}`);
+console.log(`  canvas:            ${WIDTH}×${HEIGHT}`);
+console.log(`  frames (track 1):  ${mounted.length}`);
+console.log(`  voice  (track 10): ${voiceCount}`);
+console.log(`  bgm    (track 11): ${bgmEmitted ? "yes" + bgmNote : "no"}`);
+console.log(`  captions (track 2): ${captionsEmitted ? "yes" : "no"}`);
+console.log(`  sfx    (track 20+): ${sfxEmitted}`);
+console.log(`  assets staged:     ${staged}/${wanted.size}`);
+console.log(`  total duration:    ${TOTAL}s`);
+if (repairs.length) {
+  console.log(`\nrepaired (frame files updated in place):`);
+  for (const rp of repairs) console.log(`  - ${rp}`);
+}
+if (anomalies.length) {
+  console.log(`\nanomalies (non-fatal):`);
+  for (const a of anomalies) console.log(`  - ${a}`);
+}

skills/faceless-explainer/scripts/audio.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// audio.mjs — audio ADAPTER (reuses the product-launch SCRIPT.md / STORYBOARD.md
+// model; this file is intentionally identical across the reusing skills). The
+// TTS / BGM / SFX implementation
+// no longer lives here: it is the shared engine at
+// ../../media-use/audio/scripts/audio.mjs. This file only (a) maps the
+// product-launch model (SCRIPT.md frames + STORYBOARD.md music/sfx) into the
+// engine's neutral audio_request.json, (b) converts the engine's id-keyed
+// audio_meta back into the frame-keyed shape captions.mjs / assemble-index.mjs
+// already consume, and (c) keeps the local `sync-durations` pass (it rewrites
+// STORYBOARD.md, which is product-launch-specific).
+//
+// Three modes (unchanged CLI surface):
+//   (default) generate — engine --only tts,bgm. BGM mode is "retrieve" (strict:
+//        no HeyGen credential ⇒ skip, never a detached generate, since this
+//        workflow has no wait-bgm step). Runs in the background during Step 4.
+//   sync-durations — write real voice durations into STORYBOARD.md (local).
+//   fetch-sfx      — engine --only sfx, merged into the existing meta (Step 5,
+//        after the frames' `sfx:` cues exist).
+//
+//   node audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json
+//   node audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
+//   node audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseStoryboard } from "./lib/storyboard.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ENGINE = join(HERE, "..", "..", "media-use", "audio", "scripts", "audio.mjs");
+
+const flag = (argv, name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const pad2 = (n) => String(n).padStart(2, "0");
+
+// SCRIPT.md → [{ frame, text }]. `## … (Frame N)` opens a line; `**key:**` rows
+// are metadata; the indented block is the spoken text (the only TTS input).
+function parseScript(md) {
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur && cur.text.trim()) out.push({ frame: cur.frame, text: cur.text.trim() });
+    cur = null;
+  };
+  for (const line of md.split(/\r?\n/)) {
+    const h = line.match(/^#{2,3}\s+.*?\(frame\s+(\d+)\)/i);
+    if (h) {
+      flush();
+      cur = { frame: Number(h[1]), text: "" };
+      continue;
+    }
+    if (!cur) continue;
+    if (/^\s*\*\*/.test(line)) continue;
+    const m = line.match(/^(?: {4,}|\t)(.+)$/);
+    if (m) cur.text += (cur.text ? " " : "") + m[1].trim();
+  }
+  flush();
+  return out;
+}
+
+// Path of the engine's neutral meta — a stable sidecar so `--only` merges
+// (generate then fetch-sfx) accumulate, while audio_meta.json holds the PL shape.
+const neutralPath = (plOutPath) => join(dirname(plOutPath), "audio_engine_meta.json");
+
+// Run the shared engine. Returns nothing; dies on a non-zero exit.
+function runEngine({ request, hyperframesDir, neutral, only, extra = [] }, die) {
+  const reqPath = join(hyperframesDir, "audio_request.json");
+  writeFileSync(reqPath, JSON.stringify(request, null, 2));
+  const engine = process.env.HF_MEDIA_ENGINE || DEFAULT_ENGINE;
+  if (!existsSync(engine)) die(`media audio engine not found at ${engine} (set $HF_MEDIA_ENGINE)`);
+  const args = [
+    engine,
+    "--request",
+    reqPath,
+    "--hyperframes",
+    hyperframesDir,
+    "--out",
+    neutral,
+    "--only",
+    only,
+    ...extra,
+  ];
+  const r = spawnSync("node", args, { stdio: "inherit" });
+  if (r.status !== 0) die(`media audio engine exited ${r.status}`);
+}
+
+// Engine neutral meta (id-keyed) → product-launch meta (frame-keyed) consumed by
+// captions.mjs / assemble-index.mjs. id is the zero-padded frame number.
+function toProductLaunchMeta(neutral) {
+  const voices = (neutral.voices ?? []).map((v) => ({
+    frame: Number(v.id),
+    path: v.path,
+    duration_s: v.duration_s,
+    words: (v.words ?? []).map((w) => ({ id: w.id, text: w.text, start: w.start, end: w.end })),
+  }));
+  const bgm = neutral.bgm
+    ? {
+        path: neutral.bgm.path,
+        volume: neutral.bgm.volume,
+        query: neutral.bgm.query ?? null,
+        duration_s: neutral.bgm.duration_s ?? null,
+      }
+    : null;
+  const sfx = (neutral.sfx ?? []).map((s) => ({
+    frame: Number(s.id),
+    file: s.file,
+    offset_s: s.offset_s ?? 0,
+    duration_s: s.duration_s ?? 1,
+    volume: s.volume ?? 0.35,
+  }));
+  return { bgm, voices, sfx };
+}
+
+// ── generate (TTS + BGM) ────────────────────────────────────────────────────
+function runGenerate(argv) {
+  const die = (m) => {
+    console.error(`✗ audio generate: ${m}`);
+    process.exit(1);
+  };
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const scriptPath = resolve(flag(argv, "script", join(hyperframesDir, "SCRIPT.md")));
+  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "audio_meta.json")));
+  const userVoice = flag(argv, "voice", null);
+  const speed = Number(flag(argv, "speed", "1.0")) || 1.0;
+
+  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+  const g = manifest.globals;
+
+  const lines = existsSync(scriptPath)
+    ? parseScript(readFileSync(scriptPath, "utf8")).map((l) => ({
+        id: pad2(l.frame),
+        text: l.text,
+      }))
+    : [];
+  if (!lines.length) console.error("· no SCRIPT.md — silent film (BGM only)");
+
+  // BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
+  // strict here (no wait-bgm step downstream).
+  const query = (g.extra && g.extra.music) || g.message || g.arc || "calm cinematic underscore";
+  const request = {
+    provider: "auto",
+    speed,
+    lines,
+    bgm: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
+  };
+  if (userVoice) request.voice = userVoice;
+
+  const neutral = neutralPath(outPath);
+  runEngine({ request, hyperframesDir, neutral, only: "tts,bgm" }, die);
+
+  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
+  writeFileSync(outPath, JSON.stringify(meta, null, 2));
+  console.log(
+    `✓ audio generate: ${meta.voices.length} voice + ${meta.bgm ? "1 bgm" : "no bgm"} → ${outPath}`,
+  );
+}
+
+// ── fetch-sfx ────────────────────────────────────────────────────────────────
+function runFetchSfx(argv) {
+  const die = (m) => {
+    console.error(`✗ audio fetch-sfx: ${m}`);
+    process.exit(1);
+  };
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const outPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
+
+  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+
+  // Per-frame `sfx:` cues (comma-separated) → engine lines carrying only sfx.
+  const lines = [];
+  for (const f of manifest.frames) {
+    const names = (f.extra?.sfx ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (names.length && f.number != null) lines.push({ id: pad2(f.number), sfx: names });
+  }
+
+  const neutral = neutralPath(outPath);
+  const request = { lines, bgm: { mode: "none" } };
+  // --only sfx is a MERGE, not an overwrite: the engine reads the existing neutral
+  // sidecar (audio_engine_meta.json) and recomputes only the sfx section, so the
+  // voices/bgm written by the earlier generate (--only tts,bgm) pass are preserved.
+  runEngine({ request, hyperframesDir, neutral, only: "sfx" }, die);
+
+  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
+  writeFileSync(outPath, JSON.stringify(meta, null, 2));
+  console.log(`✓ audio fetch-sfx: ${meta.sfx.length} SFX cue(s) → ${outPath}`);
+}
+
+// ── sync-durations (local; rewrites STORYBOARD.md) ────────────────────────────
+function runSyncDurations(argv) {
+  const die = (m) => {
+    console.error(`✗ audio sync-durations: ${m}`);
+    process.exit(1);
+  };
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  if (!existsSync(audioMetaPath)) die(`audio_meta.json not found at ${audioMetaPath}`);
+
+  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+  const durByFrame = new Map();
+  for (const v of meta.voices ?? []) {
+    if (v.frame != null && v.duration_s) durByFrame.set(v.frame, v.duration_s);
+  }
+
+  // Read directly and handle ENOENT here, rather than an existsSync precheck —
+  // the check→write pair (write-back below) is a TOCTOU race CodeQL flags.
+  let storyboardRaw = "";
+  try {
+    storyboardRaw = readFileSync(storyboardPath, "utf8");
+  } catch {
+    die(`STORYBOARD.md not found at ${storyboardPath}`);
+  }
+  const lines = storyboardRaw.split(/\r?\n/);
+  const FRAME_RE = /^#{2,3}\s+(?:frame|beat|scene)\b.*?(\d+)/i;
+  let curFrame = null;
+  let updated = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(FRAME_RE);
+    if (h) {
+      curFrame = Number(h[1]);
+      continue;
+    }
+    if (curFrame != null && durByFrame.has(curFrame)) {
+      const m = lines[i].match(/^(\s*[-*]\s+duration\s*:\s*).*/i);
+      if (m) {
+        lines[i] = `${m[1]}${durByFrame.get(curFrame)}s`;
+        durByFrame.delete(curFrame);
+        updated++;
+      }
+    }
+  }
+  writeFileSync(storyboardPath, lines.join("\n"));
+  const missing = [...durByFrame.keys()];
+  console.log(
+    `✓ audio sync-durations: ${updated} frame duration(s) updated` +
+      (missing.length ? ` · no \`- duration:\` line for frame(s) ${missing.join(", ")}` : ""),
+  );
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────────
+const sub = process.argv[2];
+if (sub === "sync-durations") runSyncDurations(process.argv.slice(3));
+else if (sub === "fetch-sfx") runFetchSfx(process.argv.slice(3));
+else runGenerate(process.argv.slice(2)); // default: generate

skills/faceless-explainer/scripts/build-frame.mjs

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+// build-frame.mjs — Step 2 design system in ONE command. The LLM only chooses a
+// preset; this does the deterministic rest: copy the preset's FRAME.md → frame.md,
+// remix its colors/typography onto the project's brand tokens, copy the preset's
+// caption-skin.html, and self-validate. "Strict on brand" is deterministic, so it's
+// a script, not LLM hand-editing (which mis-copies hex / breaks keys).
+//
+//   node build-frame.mjs --preset capsule --hyperframes .
+//     [--tokens capture/extracted/tokens.json]  [--preset-dir <abs path to frame-presets>]
+//
+// Remix rule — ONLY `colors:` values and `typography:` fontFamily change; keys,
+// structure, geometry, and components are untouched:
+//   colors — map brand tokens onto the preset's keys BY ROLE: the ink-role key takes
+//            the brand ink (darkest/ink-named), the canvas-role key takes the brand
+//            canvas (lightest), and every other color is repainted with the nearest
+//            brand accent's hue+saturation while KEEPING its own lightness, so tint
+//            families (sun / sun-soft / haze) stay a family. Empty brand colors → the
+//            preset palette is kept (it is already a complete, good design).
+//   fonts  — the preset's display family → the brand display font, its body family →
+//            the brand body font, wherever they appear. Empty brand fonts → kept.
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  brandRolesFromStats,
+  chroma,
+  lum,
+  parseColors,
+  parseFonts,
+  pickAccent,
+  semanticColors,
+  STATUS_ROLE_KEY,
+  UA_DEFAULT_COLORS,
+} from "./lib/tokens.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const die = (m) => {
+  console.error(`✗ build-frame: ${m}`);
+  process.exit(1);
+};
+
+const presetName = flag("preset", null);
+const hyperframesDir = resolve(flag("hyperframes", "."));
+const presetDir = resolve(
+  flag("preset-dir", join(__dirname, "../../hyperframes-creative/frame-presets")),
+);
+const tokensPath = resolve(flag("tokens", join(hyperframesDir, "capture/extracted/tokens.json")));
+
+if (!presetName) die("--preset <name> is required");
+const presetFrame = join(presetDir, presetName, "FRAME.md");
+if (!existsSync(presetFrame)) {
+  const avail = existsSync(presetDir)
+    ? readdirSync(presetDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+    : [];
+  die(
+    `no FRAME.md for preset "${presetName}" under ${presetDir}\n  available: ${avail.join(", ")}`,
+  );
+}
+
+// ── HSL helpers (recolor = brand hue+sat, original lightness) ──────────────────
+function hexToHsl(hex) {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex).trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  const r = ((n >> 16) & 255) / 255,
+    g = ((n >> 8) & 255) / 255,
+    b = (n & 255) / 255;
+  const max = Math.max(r, g, b),
+    min = Math.min(r, g, b),
+    d = max - min;
+  let h = 0;
+  const l = (max + min) / 2;
+  const s = d === 0 ? 0 : l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  if (d !== 0) {
+    h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    h *= 60;
+  }
+  return { h, s, l };
+}
+function hslToHex(h, s, l) {
+  h = (((h % 360) + 360) % 360) / 360;
+  const hue = (p, q, t) => {
+    t = (t + 1) % 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  let r, g, b;
+  if (s === 0) {
+    r = g = b = l;
+  } else {
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    r = hue(p, q, h + 1 / 3);
+    g = hue(p, q, h);
+    b = hue(p, q, h - 1 / 3);
+  }
+  const to = (x) =>
+    Math.round(x * 255)
+      .toString(16)
+      .padStart(2, "0")
+      .toUpperCase();
+  return `#${to(r)}${to(g)}${to(b)}`;
+}
+const hueDist = (a, b) => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};
+function hexToRgb(hex) {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex).trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+const rgbToHsl = (r, g, b) =>
+  hexToHsl("#" + [r, g, b].map((x) => Math.round(x).toString(16).padStart(2, "0")).join(""));
+// Repaint a chromatic rgba()/rgb() tint with the brand accent's RGB, keeping its alpha.
+// A near-neutral rgb (shadow / scrim overlay) is left untouched; a non-rgba string → null.
+function remapRgbaToAccent(val, brAccent, brAccent2, prAccentHsl, prAccent2Hsl) {
+  const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*(?:[,/]\s*([\d.]+%?))?\s*\)$/i.exec(
+    String(val).trim(),
+  );
+  if (!m) return null;
+  const r = +m[1],
+    g = +m[2],
+    b = +m[3],
+    a = m[4];
+  if (Math.max(r, g, b) - Math.min(r, g, b) < 16) return null; // neutral overlay — keep as-is
+  const src = rgbToHsl(r, g, b);
+  const useSecond =
+    brAccent2 &&
+    prAccentHsl &&
+    prAccent2Hsl &&
+    src &&
+    hueDist(src.h, prAccent2Hsl.h) < hueDist(src.h, prAccentHsl.h);
+  const t = hexToRgb(useSecond ? brAccent2 : brAccent);
+  if (!t) return null;
+  return a !== undefined
+    ? `rgba(${t[0]}, ${t[1]}, ${t[2]}, ${a})`
+    : `rgb(${t[0]}, ${t[1]}, ${t[2]})`;
+}
+
+// ── brand tokens ──────────────────────────────────────────────────────────────
+let brandColors = [];
+let brandFonts = [];
+let brandFontWeights = []; // weights the brand text font actually ships (tokens fonts[].weights)
+let brandColorStats = []; // rich per-color usage stats (areaBg / interactiveBg / textCount …)
+// Icon/glyph fonts capture surfaces as "fonts" — they are never the brand text face
+// (webflow-icons, Font Awesome, icomoon …) and must not become display/body or contribute weights.
+const isIconFont = (name) =>
+  /(?:^|[\s_-])icons?(?:[\s_-]|$)|icomoon|font\s*-?awesome|glyphicons?|material\s*icons|feather\s*icons/i.test(
+    String(name),
+  );
+if (existsSync(tokensPath)) {
+  try {
+    const t = JSON.parse(readFileSync(tokensPath, "utf8"));
+    brandColors = (t.colors ?? [])
+      .map((c) => (typeof c === "string" ? c : (c?.hex ?? c?.value ?? "")))
+      .map((c) => String(c).trim())
+      .filter((c) => /^#?[0-9a-fA-F]{6}$/.test(c))
+      .map((c) => (c.startsWith("#") ? c : `#${c}`));
+    brandFonts = (t.fonts ?? [])
+      .map((f) => (typeof f === "string" ? f : (f?.family ?? f?.name ?? "")))
+      .map((f) => String(f).split(",")[0].replace(/['"]/g, "").trim())
+      .filter(Boolean)
+      .filter((f) => !isIconFont(f));
+    // Union of the (non-icon) brand fonts' available weights — used to clamp the preset's
+    // type ramp so a font shipping only 400/500 never faux-bolds a 600/700 heading.
+    brandFontWeights = [
+      ...new Set(
+        (t.fonts ?? [])
+          .filter((f) => f && typeof f === "object" && !isIconFont(f.family ?? f.name ?? ""))
+          .flatMap((f) => (Array.isArray(f.weights) ? f.weights : []))
+          .map((w) => parseInt(w, 10))
+          .filter((w) => Number.isFinite(w)),
+      ),
+    ].sort((a, b) => a - b);
+    brandColorStats = Array.isArray(t.colorStats) ? t.colorStats : [];
+  } catch (e) {
+    die(`tokens.json parse: ${e.message}`);
+  }
+}
+
+let md = readFileSync(presetFrame, "utf8");
+const presetColors = parseColors(md);
+const summary = [];
+
+// ── color remix ───────────────────────────────────────────────────────────────
+if (brandColors.length && presetColors.length) {
+  const pr = semanticColors(presetColors);
+  // Brand roles: prefer the function-based reading of capture colorStats (canvas =
+  // largest background, accent = top interactive bg, ink = dominant contrasting text).
+  // Fall back to the legacy luminance/chroma heuristic only when stats are absent —
+  // but pick the accent via pickAccent either way so a UA-default link color never wins.
+  const br =
+    brandRolesFromStats(brandColorStats, brandColors) ??
+    (() => {
+      // strip UA-default link colors so a stray <a> color can't become ink/canvas/accent
+      const clean = brandColors.filter((h) => !UA_DEFAULT_COLORS.has(h.toUpperCase()));
+      const s = semanticColors(clean.map((h, i) => [`c${i}`, h]));
+      return {
+        ink: s.ink,
+        canvas: s.canvas,
+        accent: pickAccent(brandColorStats, clean, [s.ink, s.canvas]) ?? s.accent,
+        accent2: s.accent2,
+      };
+    })();
+  if (!br.accent) die("accent 选取失败：品牌色里没有可用的强调色");
+  if (chroma(br.accent) <= 40) {
+    console.warn(
+      `  ⚠ accent ${br.accent} 彩度很低 (${chroma(br.accent)}) — 确认这是品牌色而非中性/默认色`,
+    );
+  }
+  // Map by LUMINANCE POLARITY. The preset's darker value takes the brand's darker value and
+  // the lighter takes the lighter — UNLESS the brand's GROUND polarity differs from the
+  // preset's. Every shipped preset is light-ground; a dark-mode brand (Linear, Vercel,
+  // Raycast…) has its canvas darker than its ink (colorStats already resolved the real
+  // ground as the largest-area background). On a polarity MISMATCH we INVERT the mapping so a
+  // light preset becomes the dark brand (canvas↔ink swap) instead of forcing the brand onto
+  // an off-brand light video; neutral/tint lightness is then mirrored (L→1−L) so the whole
+  // palette flips to the brand's ground. Same-polarity (the common case) is unchanged.
+  const darker = (a, b) => ((lum(a) ?? 0) <= (lum(b) ?? 0) ? a : b);
+  const prDark = darker(pr.ink, pr.canvas);
+  const prLight = prDark === pr.ink ? pr.canvas : pr.ink;
+  const brDark = darker(br.ink, br.canvas);
+  const brLight = brDark === br.ink ? br.canvas : br.ink;
+  const presetGroundDark = (lum(pr.canvas) ?? 255) < (lum(pr.ink) ?? 0);
+  const brandGroundDark = (lum(br.canvas) ?? 255) < (lum(br.ink) ?? 0);
+  const invert = presetGroundDark !== brandGroundDark;
+  const mapDark = invert ? brLight : brDark; // preset's dark value → this brand value
+  const mapLight = invert ? brDark : brLight; // preset's light value → this brand value
+  const flipL = (l) => (invert ? 1 - l : l); // mirror tint/neutral lightness when flipping
+  const prAccentHsl = hexToHsl(pr.accent);
+  const prAccent2Hsl = hexToHsl(pr.accent2);
+  const newByKey = new Map();
+  for (const [key, val] of presetColors) {
+    const ph = hexToHsl(val);
+    let next;
+    if (val === prDark) next = mapDark;
+    else if (val === prLight) next = mapLight;
+    else if (STATUS_ROLE_KEY.test(key))
+      // semantic status colors (green/red …) — the HUE carries the meaning; never repaint.
+      // MUST precede the accent checks: a preset's red "negative" is often its 2nd-most-chromatic
+      // color and would otherwise be claimed as accent2 and recolored to the brand hue.
+      next = val;
+    else if (val === pr.accent)
+      next = br.accent; // primary accent → the EXACT brand color
+    else if (pr.accent2 !== pr.accent && val === pr.accent2)
+      next = br.accent2; // exact 2nd accent
+    else if (!ph) {
+      // rgba()/rgb() tint → repaint its rgb with the brand accent, keep alpha (a neutral
+      // overlay is kept). A non-color non-hex value (var(), named) falls through unchanged.
+      next = remapRgbaToAccent(val, br.accent, br.accent2, prAccentHsl, prAccent2Hsl) ?? val;
+    } else if (chroma(val) < 16) {
+      // NEUTRAL source (grey text-ladder, hairline borders) → keep it NEUTRAL. Apply at most a
+      // whisper of the brand hue (sat ≤ 0.06); never the accent's full saturation — that is what
+      // turned the grey ladder into saturated blue.
+      const bh = hexToHsl(br.accent);
+      next = bh ? hslToHex(bh.h, Math.min(ph.s, 0.06), flipL(ph.l)) : val;
+    } else {
+      // chromatic tint → repaint with the nearest brand accent's hue+sat, keep THIS color's
+      // lightness so tint families stay families.
+      const useSecond =
+        pr.accent !== pr.accent2 &&
+        prAccentHsl &&
+        prAccent2Hsl &&
+        hueDist(ph.h, prAccent2Hsl.h) < hueDist(ph.h, prAccentHsl.h);
+      const bh = hexToHsl(useSecond ? br.accent2 : br.accent);
+      next = bh ? hslToHex(bh.h, bh.s, flipL(ph.l)) : val;
+    }
+    if (next !== val) newByKey.set(key, next);
+  }
+  // rewrite only the value of each colors: line; everything else byte-identical.
+  let inBlock = false;
+  md = md
+    .split(/\r?\n/)
+    .map((line) => {
+      if (/^colors:\s*$/.test(line)) {
+        inBlock = true;
+        return line;
+      }
+      if (inBlock && /^\S/.test(line)) inBlock = false;
+      if (!inBlock) return line;
+      const m = line.match(
+        /^(\s+)([\w-]+):\s*(?:"[^"]*"|'[^']*'|#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)|[^#\n]*?)(\s+#.*)?$/,
+      );
+      if (m && newByKey.has(m[2])) return `${m[1]}${m[2]}: "${newByKey.get(m[2])}"${m[3] ?? ""}`;
+      return line;
+    })
+    .join("\n");
+  summary.push(
+    `colors: ${invert ? "INVERTED (dark-mode brand on light preset) · " : ""}dark ${prDark}→${mapDark}, light ${prLight}→${mapLight}, accent ${pr.accent}→${br.accent}` +
+      ` (${newByKey.size}/${presetColors.length} keys repainted${brandColorStats.length ? ", via colorStats" : ""})`,
+  );
+} else {
+  summary.push(
+    brandColors.length
+      ? "colors: preset has no parseable colors — kept"
+      : "colors: no brand colors — preset palette kept",
+  );
+}
+
+// ── font remix ────────────────────────────────────────────────────────────────
+if (brandFonts.length) {
+  const pf = parseFonts(md);
+  const strip = (q) => (q ? q.replace(/^"|"$/g, "") : null);
+  const pDisplay = strip(pf.display);
+  const pBody = strip(pf.body);
+  const pMono = strip(pf.mono);
+  // A monospace brand face is for code / labels / chrome — never the reading display or body.
+  // Split the brand fonts: the primary NON-mono family carries display AND body (the common
+  // single-sans case, e.g. Inter for everything), and a captured mono (Berkeley Mono,
+  // JetBrains Mono…) is routed onto the preset's mono role instead of turning the body
+  // monospace. (Distinct display/body brands still resolve to a clean sans; hand-tune the
+  // display in frame.md if a separate display face is wanted.)
+  const isMonoFont = (n) =>
+    /(?:^|[\s_-])mono(?:[\s_-]|$)|monospace|consol|courier|menlo|monaco|jetbrains|berkeley|space\s*mono|ibm\s*plex\s*mono|sf\s*mono|roboto\s*mono|source\s*code|fira\s*code|geist\s*mono|dm\s*mono/i.test(
+      String(n),
+    );
+  const nonMono = brandFonts.filter((f) => !isMonoFont(f));
+  const monoFonts = brandFonts.filter(isMonoFont);
+  const bDisplay = nonMono[0] ?? brandFonts[0];
+  const bBody = nonMono[0] ?? brandFonts[0];
+  const bMono = monoFonts[0] ?? null;
+  const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Replace the preset family as a WHOLE WORD/PHRASE everywhere — frontmatter values,
+  // component strings like "Space Grotesk 600", AND prose — case-sensitive with word
+  // boundaries so a single-word family ("Inter") can never corrupt a substring
+  // ("interactive"). Quote-exact replace alone missed names baked into longer strings + prose.
+  const swapFamily = (from, to) => {
+    if (from && to && from !== to) md = md.replace(new RegExp(`\\b${escRe(from)}\\b`, "g"), to);
+  };
+  swapFamily(pDisplay, bDisplay);
+  if (pBody !== pDisplay) swapFamily(pBody, bBody);
+  // route the brand mono onto the preset's mono role (only if the preset has a DISTINCT mono
+  // family — never collapse body/display into mono)
+  if (bMono && pMono && pMono !== pBody && pMono !== pDisplay) swapFamily(pMono, bMono);
+  summary.push(
+    `fonts: display ${pDisplay}→${bDisplay}, body ${pBody}→${bBody}` +
+      (bMono && pMono && pMono !== pBody && pMono !== pDisplay ? `, mono ${pMono}→${bMono}` : ""),
+  );
+} else {
+  summary.push("fonts: no brand fonts — preset fonts kept");
+}
+
+// ── cap type weights to the brand font's available faces ──────────────────────
+// The remix swaps the font FAMILY but keeps the preset's weights; a brand font that ships
+// only e.g. 400/500 would faux-bold every 600/700 heading. Clamp each `typography:` weight
+// to the NEAREST weight the brand font actually provides (tokens.json fonts[].weights).
+if (brandFonts.length && brandFontWeights.length) {
+  const avail = brandFontWeights;
+  const nearest = (n) =>
+    avail.reduce((best, w) => {
+      const dw = Math.abs(w - n),
+        db = Math.abs(best - n);
+      return dw < db || (dw === db && w > best) ? w : best;
+    }, avail[0]);
+  let capped = 0;
+  const cap = (num) => {
+    const n = parseInt(num, 10);
+    if (avail.includes(n)) return String(n);
+    const c = nearest(n);
+    if (c !== n) capped++;
+    return String(c);
+  };
+  let inType = false;
+  md = md
+    .split(/\r?\n/)
+    .map((line) => {
+      if (/^typography:\s*$/.test(line)) {
+        inType = true;
+        return line;
+      }
+      if (inType && /^\S/.test(line)) inType = false;
+      let out = line;
+      // (a) structured `weight: NNN` in the typography ramp
+      if (inType) out = out.replace(/(\bweight:\s*)(\d{3})\b/g, (m, pfx, num) => pfx + cap(num));
+      // (b) a weight baked into a quoted `typography:` component value, e.g.
+      //     cta-button → typography: "Basier Square 600"  (NNN not followed by a unit like px)
+      out = out.replace(
+        /(typography:\s*"[^"]*?\b)(\d{3})\b(?![a-z%])/gi,
+        (m, pfx, num) => pfx + cap(num),
+      );
+      return out;
+    })
+    .join("\n");
+  if (capped)
+    summary.push(`fonts: capped ${capped} type weight(s) to brand faces {${avail.join(", ")}}`);
+}
+
+// ── brand-adaptation note ─────────────────────────────────────────────────────
+// The remix fixes the NORMATIVE frontmatter, but the preset's PROSE still carries its
+// original weight ranges / color-names. Prepend a short "frontmatter is truth" header so a
+// reader (or frame worker) interprets any lingering preset prose THROUGH the brand values —
+// instead of fragile per-sentence prose surgery.
+if (brandFonts.length || (brandColors.length && presetColors.length)) {
+  const bD = brandFonts[0];
+  const bB = brandFonts[1] ?? brandFonts[0];
+  const note =
+    `## Brand adaptation (READ FIRST — the frontmatter is the source of truth)\n\n` +
+    `This is the **${presetName}** preset remixed onto the captured brand. The YAML frontmatter above ` +
+    `(colors · typography · components) is **normative and already correct — use it verbatim.** The prose ` +
+    `below is the ORIGINAL preset's intent; read it THROUGH the frontmatter:\n\n` +
+    (brandFonts.length
+      ? `- **Fonts** — already set to **${bD}** (display) / **${bB}** (body); ignore any preset font name lingering in prose.\n`
+      : "") +
+    (brandFontWeights.length
+      ? `- **Weights** — the brand font ships \`{${brandFontWeights.join(", ")}}\` only; every weight is clamped to these — ignore higher preset weights (e.g. 600/700) in prose.\n`
+      : "") +
+    `- **Colors** — use the frontmatter hex; preset color NAMES in prose (e.g. "cobalt", "cream") mean the remapped brand values.\n`;
+  if (/^# .*$/m.test(md)) md = md.replace(/^# .*$/m, (m) => `${m}\n\n${note}`);
+  else md = `${note}\n${md}`;
+  summary.push("brand-adaptation note prepended");
+}
+
+// ── stage brand font files + emit @font-face ──────────────────────────────────
+// A brand font is rarely a Google font, so renaming the family in frame.md is not enough:
+// nothing loads the actual face. If the capture downloaded font files, copy them to
+// assets/fonts/ under CLEAN, weight-named names (so captions.mjs' family-prefix matcher
+// finds them too) and append a ready-to-paste, ROOT-RELATIVE @font-face block to frame.md.
+if (brandFonts.length) {
+  const norm = (s) =>
+    String(s)
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, "");
+  const extOf = (f) => (f.match(/\.(woff2|woff|ttf|otf)$/i)?.[1] ?? "").toLowerCase();
+  const FMT = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
+  const weightInfo = (name) => {
+    const s = name.toLowerCase();
+    if (/black|heavy|ultra|extrabold/.test(s)) return { n: 800, w: "ExtraBold" };
+    if (/semibold|demibold/.test(s)) return { n: 600, w: "SemiBold" };
+    if (/bold/.test(s)) return { n: 700, w: "Bold" };
+    if (/medium/.test(s)) return { n: 500, w: "Medium" };
+    if (/light|thin/.test(s)) return { n: 300, w: "Light" };
+    return { n: 400, w: "Regular" };
+  };
+  const fams = [...new Set(brandFonts)];
+  const srcDirs = [
+    join(hyperframesDir, "capture/assets/fonts"),
+    join(hyperframesDir, "assets/fonts"),
+  ].filter((d) => existsSync(d));
+  const files = [];
+  for (const d of srcDirs)
+    for (const f of readdirSync(d).sort()) if (extOf(f)) files.push({ d, f });
+  // Single family → all font files belong to it (the common captured case, hash-named files
+  // included). Multiple families → assign each file to the longest family key its name contains.
+  const ranked = [...fams].sort((a, b) => norm(b).length - norm(a).length);
+  const famOf = (f) =>
+    fams.length === 1 ? fams[0] : ranked.find((x) => norm(f).includes(norm(x)));
+  const outDir = join(hyperframesDir, "assets/fonts");
+  const faces = [];
+  const stagedNames = new Set();
+  for (const { d, f } of files) {
+    const fam = famOf(f);
+    if (!fam) continue;
+    const { n, w } = weightInfo(f);
+    const clean = `${fam.replace(/[^A-Za-z0-9]/g, "")}-${w}.${extOf(f)}`;
+    if (stagedNames.has(clean)) continue;
+    mkdirSync(outDir, { recursive: true });
+    if (!existsSync(join(outDir, clean))) copyFileSync(join(d, f), join(outDir, clean));
+    stagedNames.add(clean);
+    faces.push(
+      `@font-face{font-family:"${fam}";font-weight:${n};font-style:normal;font-display:block;src:url("assets/fonts/${clean}") format("${FMT[extOf(f)]}");}`,
+    );
+  }
+  if (faces.length) {
+    md +=
+      `\n\n## Font loading (auto-generated)\n\n` +
+      `The brand font ships as local files in \`assets/fonts/\` — do NOT link Google Fonts for it. ` +
+      `Paste this \`<style>\` into every frame's \`<head>\`/\`<template>\` (captions use the same files) ` +
+      `so \`font-family\` resolves in preview, snapshot, and render alike:\n\n` +
+      "```html\n<style>\n" +
+      faces.join("\n") +
+      "\n</style>\n```\n";
+    summary.push(
+      `fonts: staged ${stagedNames.size} face(s) → assets/fonts/ + @font-face in frame.md`,
+    );
+  }
+}
+
+// ── write frame.md ────────────────────────────────────────────────────────────
+const framePath = join(hyperframesDir, "frame.md");
+writeFileSync(framePath, md);
+
+// ── copy caption-skin.html ────────────────────────────────────────────────────
+const presetSkin = join(presetDir, presetName, "caption-skin.html");
+let skinCopied = false;
+if (existsSync(presetSkin)) {
+  const skinDir = join(hyperframesDir, ".hyperframes");
+  mkdirSync(skinDir, { recursive: true });
+  copyFileSync(presetSkin, join(skinDir, "caption-skin.html"));
+  skinCopied = true;
+}
+
+// ── self-validate ─────────────────────────────────────────────────────────────
+const outColors = parseColors(md);
+if (outColors.length !== presetColors.length) {
+  die(`color keys changed (${presetColors.length}→${outColors.length}) — keys must be preserved`);
+}
+const outRoles = semanticColors(outColors);
+const li = lum(outRoles.ink),
+  lc = lum(outRoles.canvas);
+// ink (type) and canvas (ground) must differ enough to READ — in EITHER direction. A
+// light-mode spec has ink darker than canvas; a dark-mode spec (the polarity flip above)
+// the reverse. Assert luminance SEPARATION, not a fixed polarity.
+if (li != null && lc != null && Math.abs(li - lc) < 40) {
+  die(
+    `ink (${outRoles.ink}, lum ${li.toFixed(0)}) and canvas (${outRoles.canvas}, lum ${lc.toFixed(0)}) lack contrast — bad brand mapping`,
+  );
+}
+
+console.log(`✓ build-frame: ${presetName} → ${framePath}`);
+for (const s of summary) console.log(`  ${s}`);
+console.log(
+  `  .hyperframes/caption-skin.html: ${skinCopied ? "copied" : "preset ships none — captions will use the default pill"}`,
+);
+console.log(`  self-check: keys preserved, ink/canvas contrast ok ✓`);

skills/faceless-explainer/scripts/captions.mjs

@@ -0,0 +1,508 @@
+#!/usr/bin/env node
+// captions.mjs — build the captions sub-composition from STORYBOARD + audio_meta.
+//
+// One mode: `build`. Reads STORYBOARD.md (frame order + durations → cumulative
+// frame starts) + audio_meta.json (voices[].words, frame-relative) → absolute-
+// timed caption groups → writes:
+//   compositions/captions.html  — a self-contained sub-composition the index
+//        assembler mounts on its captions track (data-composition-id="captions").
+//   caption_groups.json         — the computed groups (debug / inspection / --out).
+//   caption-overrides.json      — an empty `[]` shim (silences the captions runtime's
+//        validate-time fetch; only written when captions.html is).
+// No narration / no words → legal skip: nothing written, assemble-index then omits
+// the captions track (it keys off compositions/captions.html existence).
+//
+//   node captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
+//
+// CAPTION LOOK — two sources, picked automatically:
+//   1. PRESET SKIN (preferred). If a project-local `.hyperframes/caption-skin.html`
+//      exists (Step 2 copies the chosen frame-preset's skin into the project), it is
+//      the caption look.
+//      It is a brand-token-strict skin with three reserved holes; this script fills them
+//      and wraps the result in a <template> for the engine:
+//        - `var GROUPS = [];`            → the computed caption groups
+//        - `var DURATION = 0;` + data-duration="0" (and data-width/height="0") → real values
+//        - `<style data-brand-tokens></style>` → :root tokens derived from the project's
+//          frame.md (colors + fonts), mapped to a fixed semantic vocab every skin shares:
+//          --cap-ink / --cap-canvas / --cap-accent / --cap-accent-2 / --font-display /
+//          --font-body, plus --cap-band-top / --cap-band-height (the keep-out band).
+//      So the brand-token overlay from Step 2 flows into the captions automatically.
+//   2. DEFAULT (fallback). No skin file → the built-in Roboto/black pill (buildCaptionsHtml).
+//
+// Grouping mirrors the proven heuristics (frame boundary · sentence-end punct ·
+// silence gap · density-aware word cap); word timings come inline from audio_meta.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseStoryboard } from "./lib/storyboard.mjs";
+import { captionBand, parseFormat } from "./lib/dimensions.mjs";
+import { parseColors, parseFonts, semanticColors, lum } from "./lib/tokens.mjs";
+
+const flag = (argv, name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const r3 = (x) => Number(x.toFixed(3));
+
+// ── grouping params ───────────────────────────────────────────────────────────
+const SILENCE_GAP = 0.18; // s of silence between words → split
+const TAIL_PAD = 0.12; // s the group lingers after its last word
+const SENT_END = /[.?!,;:—]$/;
+const DENSITY_WINDOW = 1.0; // s window for words/sec density
+function wordCap(density) {
+  return density > 3.5 ? 2 : density > 2.5 ? 3 : 4;
+}
+
+function runBuild(argv) {
+  const skip = (reason) => {
+    console.log(`captions: skipped (${reason})`);
+    process.exit(0);
+  };
+  const die = (m) => {
+    console.error(`✗ captions build: ${m}`);
+    process.exit(1);
+  };
+
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
+  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "caption_groups.json")));
+  const htmlPath = join(hyperframesDir, "compositions/captions.html");
+  const overridesPath = join(hyperframesDir, "caption-overrides.json");
+  const skinArg = flag(argv, "skin", null);
+  const hiddenSkinPath = join(hyperframesDir, ".hyperframes", "caption-skin.html");
+  const legacySkinPath = join(hyperframesDir, "caption-skin.html");
+  const skinPath = resolve(
+    skinArg ?? (existsSync(hiddenSkinPath) ? hiddenSkinPath : legacySkinPath),
+  );
+  const framePath = resolve(flag(argv, "frame", join(hyperframesDir, "frame.md")));
+
+  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+  const { width: W, height: H } = parseFormat(manifest.globals.format);
+
+  if (!existsSync(audioMetaPath)) skip("no audio_meta.json (silent film)");
+  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+  if (!Array.isArray(meta.voices) || meta.voices.length === 0) skip("no narration");
+
+  // cumulative frame starts (by frame number) + total duration, from STORYBOARD.
+  const startByFrame = new Map();
+  let acc = 0;
+  for (const f of manifest.frames) {
+    if (f.number != null) startByFrame.set(f.number, acc);
+    acc += Number.isFinite(f.durationSeconds) ? f.durationSeconds : 0;
+  }
+  const total = r3(acc);
+
+  // absolute word stream: frame start + frame-relative word timing.
+  const words = [];
+  for (const v of meta.voices) {
+    const base = startByFrame.get(v.frame);
+    if (base == null || !Array.isArray(v.words)) continue;
+    for (const w of v.words) {
+      const text = String(w.text ?? "").trim();
+      if (!text || /^[.?!,;:—–-]+$/.test(text)) continue; // drop empties + bare punctuation
+      if (!isFinite(w.start) || !isFinite(w.end)) continue;
+      words.push({ text, start: r3(base + w.start), end: r3(base + w.end), frame: v.frame });
+    }
+  }
+  words.sort((a, b) => a.start - b.start);
+  if (words.length === 0) skip("no usable words");
+
+  // density at i = words whose start falls within [w.start, w.start + WINDOW).
+  const densityAt = (i) => {
+    const t0 = words[i].start;
+    let n = 0;
+    for (let j = i; j < words.length && words[j].start < t0 + DENSITY_WINDOW; j++) n++;
+    return n / DENSITY_WINDOW;
+  };
+
+  // group: split on frame change / silence gap / word cap; always flush after a
+  // sentence-ending word.
+  const groups = [];
+  let cur = null;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const prev = cur && cur.words[cur.words.length - 1];
+    const crossFrame = cur && w.frame !== cur.frame;
+    const gap = prev && w.start - prev.end > SILENCE_GAP;
+    const full = cur && cur.words.length >= cur.cap;
+    if (!cur || crossFrame || gap || full) {
+      if (cur) groups.push(cur);
+      cur = { frame: w.frame, cap: wordCap(densityAt(i)), words: [] };
+    }
+    cur.words.push(w);
+    if (SENT_END.test(w.text)) {
+      groups.push(cur);
+      cur = null;
+    }
+  }
+  if (cur) groups.push(cur);
+
+  // finalize: ids, start/end (tail-padded, clamped < next group's start), text.
+  const finalized = groups.map((g, gi) => {
+    const first = g.words[0];
+    const last = g.words[g.words.length - 1];
+    const next = groups[gi + 1];
+    let end = r3(last.end + TAIL_PAD);
+    if (next && next.words[0].start < end) end = r3(next.words[0].start);
+    return {
+      id: `caption-group-${gi}`,
+      frame: g.frame,
+      start: r3(first.start),
+      end,
+      text: g.words.map((w) => w.text).join(" "),
+      words: g.words.map((w, wi) => ({
+        id: `caption-word-${gi}-${wi}`,
+        text: w.text,
+        start: r3(w.start),
+        end: r3(w.end),
+      })),
+    };
+  });
+
+  // ── write caption_groups.json ──
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(
+    outPath,
+    JSON.stringify({ total_duration_s: total, width: W, height: H, groups: finalized }, null, 2),
+  );
+
+  // ── write compositions/captions.html (preset skin if present, else default) ──
+  mkdirSync(dirname(htmlPath), { recursive: true });
+  let source;
+  if (existsSync(skinPath)) {
+    const tokens = frameTokensCss(framePath, H);
+    const faces = brandFontFaces(framePath, hyperframesDir);
+    const fonts = existsSync(framePath) ? parseFonts(readFileSync(framePath, "utf8")) : {};
+    writeFileSync(
+      htmlPath,
+      buildFromSkin(
+        readFileSync(skinPath, "utf8"),
+        finalized,
+        total,
+        W,
+        H,
+        tokens,
+        die,
+        faces,
+        fonts,
+      ),
+    );
+    source = `preset skin (${skinPath.replace(hyperframesDir + "/", "")})`;
+  } else {
+    writeFileSync(htmlPath, buildCaptionsHtml(finalized, total, W, H));
+    source = "default (built-in pill)";
+  }
+
+  // ── write caption-overrides.json shim ──
+  // Atomic create-if-absent: `wx` throws if the file already exists (which we
+  // ignore) — no existsSync→writeFileSync TOCTOU gap.
+  try {
+    writeFileSync(overridesPath, "[]\n", { flag: "wx" });
+  } catch {
+    /* overrides shim already present */
+  }
+
+  console.log(
+    `✓ captions build: ${finalized.length} group(s) from ${words.length} words → compositions/captions.html (total ${total}s) · skin: ${source}`,
+  );
+}
+
+// ── preset-skin path ────────────────────────────────────────────────────────
+// Fill the skin's three reserved holes + the root's 0-placeholders, then wrap the
+// fragment in a <template> (the engine clones template contents only). One generic
+// fill works for every preset's skin — no per-skin transform.
+//
+// Every preset's skin is authored against ITS OWN fonts/metrics (broadside→Barlow @
+// line-height 1.02, capsule→Bodoni, …). When the project's brand font differs (it
+// almost always does), three things must be reconciled so ANY skin renders correctly
+// for ANY brand — done here generically, not per-project:
+//   · @font-face for the brand fonts (else the renderer can't supply them → fallback)
+//   · the skin's preset-font FALLBACK literals (var(--font-x, "Barlow")) repointed to
+//     the brand family, so no undeclared font name trips font_family_without_font_face
+//   · a metric safety net: a heavier brand font overflows a tight preset line-height,
+//     so the active-word highlight clips — a line-height floor + word padding fixes it
+//   · data-composition-id + dimensions on the <template> root (skins lead with
+//     <script>/<style>, so the root element must carry the id, not the first child)
+function buildFromSkin(skin, groups, total, W, H, tokens, die, faces = "", fonts = {}) {
+  const fillOnce = (src, re, repl, label) => {
+    const n = (src.match(re) || []).length;
+    if (n !== 1) die(`caption-skin.html: expected exactly one ${label}, found ${n}`);
+    return src.replace(re, () => repl);
+  };
+  let out = skin;
+  // Strip HTML doc-comments first. A skin's authoring comment can contain tag-like text
+  // (broadside's literally says "<template>"), which the linter's tag scanner then picks
+  // up as the root element → false root_missing_composition_id / root_missing_dimensions.
+  // The comments are preview/authoring docs, not needed in the generated composition.
+  // Strip in a fixpoint loop, not a single global pass: removing one comment can
+  // re-form a marker from a nested/partial pair (e.g. <!--<!---->-->), which one
+  // pass misses — CodeQL flags the single replace as incomplete sanitization.
+  for (let prev = ""; prev !== out; ) {
+    prev = out;
+    out = out.replace(/<!--[\s\S]*?-->/g, "");
+  }
+  // brand :root tokens + @font-face for the brand fonts, both into the reserved hole
+  out = fillOnce(
+    out,
+    /<style data-brand-tokens>\s*<\/style>/,
+    `<style data-brand-tokens>\n${faces ? faces + "\n" : ""}${tokens}\n    </style>`,
+    "<style data-brand-tokens></style> hole",
+  );
+  // Resolve the skin's font-family var()s to the brand family LITERAL. Two reasons:
+  //  (1) the linter's used-font scanner naively comma-splits, so var(--x, "Brand") yields
+  //      junk tokens ('var(--x', 'brand")') that never match the @font-face → a false
+  //      font_family_without_font_face; a plain "Brand" literal matches the @font-face.
+  //  (2) it drops the preset's own fallback name (Barlow / IBM Plex Mono / …), which has
+  //      no @font-face in this project. The :root token stays for any other consumer.
+  if (fonts.display)
+    out = out.replace(/var\(\s*--font-display\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.display);
+  if (fonts.body) out = out.replace(/var\(\s*--font-body\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.body);
+  out = fillOnce(
+    out,
+    /var GROUPS = \[\];/,
+    `var GROUPS = ${JSON.stringify(groups)};`,
+    "`var GROUPS = [];` hole",
+  );
+  out = fillOnce(out, /var DURATION = 0;/, `var DURATION = ${total};`, "`var DURATION = 0;` hole");
+  out = fillOnce(out, /data-duration="0"/, `data-duration="${total}"`, '`data-duration="0"` hole');
+  out = fillOnce(out, /data-width="0"/, `data-width="${W}"`, '`data-width="0"` hole');
+  out = fillOnce(out, /data-height="0"/, `data-height="${H}"`, '`data-height="0"` hole');
+  // font-robust safety net — appended last so it wins the cascade over the skin's own
+  // (preset-font-tuned) line-height. Kept SNUG (1.1) so the plate hugs the text. NO extra
+  // word/pill padding: inspect's `text_box_overflow` on the highlight words is a cosmetic
+  // false-positive here (heavy-glyph ink slightly exceeds the line box, but there's no
+  // overflow:hidden — nothing is clipped); zeroing it would need an airy line-height that
+  // balloons the pill, which is worse. Override only if a brand font genuinely clips.
+  out += "\n<style>\n  .caption-line { line-height: 1.1 !important; }\n</style>";
+  // dark-ground caption contrast (auto). The preset caption skins are tuned for a LIGHT
+  // pill (cream); on a dark brand ground the pill goes near-black, so the skin's faint
+  // upcoming-word mix and light highlight block turn unreadable. When the resolved caption
+  // canvas is dark, override the three word states: a brighter muted upcoming color + an
+  // on-brand ACCENT highlight block with light text. Light grounds are left untouched.
+  const capCanvas = (tokens.match(/--cap-canvas:\s*(#[0-9a-fA-F]{6})/) || [])[1];
+  if (capCanvas && (lum(capCanvas) ?? 255) < 90) {
+    out +=
+      "\n<style>\n" +
+      "  .caption-word { color: color-mix(in srgb, var(--cap-ink) 64%, var(--cap-canvas)); }\n" +
+      "  .caption-word.is-active { color: var(--cap-ink); background: var(--cap-accent); box-shadow: 0 0 0 0.06em var(--cap-accent); }\n" +
+      "  .caption-word.is-spoken { color: var(--cap-ink); background: transparent; box-shadow: none; }\n" +
+      "</style>";
+  }
+  return `<template id="captions-template" data-composition-id="captions" data-width="${W}" data-height="${H}">\n${out.trim()}\n</template>\n`;
+}
+
+// @font-face for the brand display/body fonts, matched from the project's font dirs
+// (staged assets/fonts first, else capture/assets/fonts) by family-name prefix, with
+// weight parsed from the filename. Paths are relative to compositions/captions.html.
+// Returns "" when frame.md or font files are absent (then the skin's fallback applies).
+function brandFontFaces(framePath, hyperframesDir) {
+  if (!existsSync(framePath)) return "";
+  const { display, body } = parseFonts(readFileSync(framePath, "utf8"));
+  const families = [
+    ...new Set([display, body].filter(Boolean).map((f) => f.replace(/^"|"$/g, ""))),
+  ];
+  if (!families.length) return "";
+  const dirs = [
+    // ROOT-RELATIVE — compositions are served with the project root as their base URL, so a
+    // "../" prefix escapes the root (lint: invalid_parent_traversal_in_asset_path) and 404s in
+    // Studio/preview. Mirror what the frame workers use for images.
+    { abs: join(hyperframesDir, "assets/fonts"), rel: "assets/fonts" },
+    { abs: join(hyperframesDir, "capture/assets/fonts"), rel: "capture/assets/fonts" },
+  ].filter((d) => existsSync(d.abs));
+  const weightOf = (n) => {
+    const s = n.toLowerCase();
+    if (/black|heavy|ultra|extrabold/.test(s)) return 800;
+    if (/semibold|demibold/.test(s)) return 600; // before /bold/ — "demibold" contains "bold"
+    if (/bold/.test(s)) return 700;
+    if (/medium/.test(s)) return 500;
+    if (/light|thin/.test(s)) return 300;
+    return 400; // book / regular / roman
+  };
+  const fmtOf = (f) =>
+    /\.woff2$/i.test(f)
+      ? "woff2"
+      : /\.woff$/i.test(f)
+        ? "woff"
+        : /\.ttf$/i.test(f)
+          ? "truetype"
+          : "opentype";
+  // Normalize away ALL non-alphanumerics (spaces, underscores, hyphens) on BOTH the
+  // family name and the filename. Real font files use "_" / "-" as word separators
+  // ("TT_Norms_Pro_Bold.woff2"), so stripping only whitespace never matched them — the
+  // family key "ttnormspro" failed `startsWith` against "tt_norms_pro_bold", and the
+  // function silently returned "" → captions shipped with NO @font-face for any
+  // underscore/hyphen-named brand font (e.g. TT Norms Pro), which is exactly the
+  // font_family_without_font_face bug.
+  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const faces = [];
+  const seen = new Set();
+  const claimed = new Set(); // each file is claimed by the MOST SPECIFIC family only
+  // Match the longest family key first so "TT Norms Pro" can't swallow the files that
+  // belong to "TT Norms Pro Mono" (its key is a prefix of the longer one's).
+  const ranked = [...families].sort((a, b) => norm(b).length - norm(a).length);
+  for (const fam of ranked) {
+    const key = norm(fam);
+    for (const d of dirs) {
+      let files = [];
+      try {
+        files = readdirSync(d.abs);
+      } catch {
+        continue;
+      }
+      for (const f of files.sort()) {
+        if (!/\.(woff2|woff|ttf|otf)$/i.test(f)) continue;
+        if (claimed.has(f)) continue; // a more specific family already took this file
+        if (!norm(f.replace(/\.(woff2|woff|ttf|otf)$/i, "")).startsWith(key)) continue;
+        const w = weightOf(f);
+        const dedup = `${fam}-${w}`;
+        if (seen.has(dedup)) continue; // one src per weight; assets/fonts wins over capture
+        seen.add(dedup);
+        claimed.add(f);
+        faces.push(
+          `      @font-face { font-family: '${fam}'; src: url('${d.rel}/${f}') format('${fmtOf(f)}'); font-weight: ${w}; font-display: block; }`,
+        );
+      }
+    }
+  }
+  // Loud signal instead of a silent "". If frame.md named a brand font but no file
+  // matched, the caption text WILL fall back to a generic font in the render — surface
+  // the cause here (at build time) rather than letting it surface 2 steps later as a
+  // font_family_without_font_face lint error disconnected from its root cause.
+  if (!faces.length) {
+    const where = dirs.length
+      ? dirs.map((d) => d.rel).join(" / ")
+      : "assets/fonts or capture/assets/fonts (neither exists)";
+    console.warn(
+      `  ⚠ captions: frame.md names font ${families.map((f) => `"${f}"`).join(", ")} ` +
+        `but no matching .woff2/.woff/.ttf/.otf was found in ${where} — captions will fall back ` +
+        `(text may render in the wrong font). Stage a font file whose name starts with the family ` +
+        `(e.g. "TT Norms Pro" → TT_Norms_Pro_Bold.woff2) so it ships with the project.`,
+    );
+  }
+  return faces.join("\n");
+}
+
+// frame.md colors:/typography: → a :root token block, mapped to the fixed semantic
+// vocab every preset skin references. Robust to per-preset key names: colors are
+// matched by name, then by luminance. Brand-token overlay (Step 2) flows through
+// because the values come from the project's frame.md. No frame.md → band vars only.
+function frameTokensCss(framePath, H) {
+  const band = captionBand(H);
+  const out = [];
+  if (existsSync(framePath)) {
+    const md = readFileSync(framePath, "utf8");
+    const colors = parseColors(md);
+    for (const [k, v] of colors) out.push(`      --${k}: ${v};`); // raw, for completeness
+    const sem = semanticColors(colors);
+    if (sem.ink) out.push(`      --cap-ink: ${sem.ink};`);
+    if (sem.canvas) out.push(`      --cap-canvas: ${sem.canvas};`);
+    if (sem.accent) out.push(`      --cap-accent: ${sem.accent};`);
+    if (sem.accent2) out.push(`      --cap-accent-2: ${sem.accent2};`);
+    const { display, body } = parseFonts(md);
+    if (display) out.push(`      --font-display: ${display}, system-ui, serif;`);
+    if (body) out.push(`      --font-body: ${body}, system-ui, sans-serif;`);
+  }
+  out.push(`      --cap-band-top: ${band.bandTopY}px;`);
+  out.push(`      --cap-band-height: ${band.bandHeight}px;`);
+  return `      :root {\n${out.join("\n")}\n      }`;
+}
+
+// ── default path (no preset skin) ─────────────────────────────────────────────
+// Self-contained captions sub-composition. The <template> holds the band container
+// + style AND the <script> (the HyperFrames loader only executes scripts INSIDE the
+// cloned template — a sibling <script> after </template> never runs, so the timeline
+// never registers and captions render blank). The script builds per-word spans and a
+// paused, seek-safe GSAP timeline (opacity for group show/hide, a quick color tween
+// per word for the karaoke highlight — no className flips, no JS state) and ends each
+// group with a hard tl.set kill so an exit can't get stuck. gsap is loaded via CDN
+// inside the template (matching the frame compositions). Band = captionBand(H).
+function buildCaptionsHtml(groups, total, W, H) {
+  const band = captionBand(H);
+  const fs = Math.round(H * 0.038);
+  const pad = Math.round(fs * 0.4);
+  return `<template id="captions-template">
+  <div
+    data-composition-id="captions"
+    data-width="${W}"
+    data-height="${H}"
+    data-duration="${total}"
+    id="captions-root"
+  >
+    <div id="cap"></div>
+  </div>
+  <style>
+    #captions-root {
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+    }
+#cap {
+      position: absolute;
+      left: 0;
+      right: 0;
+      top: ${band.bandTopY}px;
+      height: ${band.bandHeight}px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+.caption-group {
+      position: absolute;
+      max-width: 80%;
+      padding: ${pad}px ${Math.round(pad * 1.8)}px;
+      background: rgba(0, 0, 0, 0.72);
+      border-radius: ${Math.round(fs * 0.3)}px;
+      font-family: Roboto, sans-serif;
+      font-weight: 700;
+      font-size: ${fs}px;
+      line-height: 1.25;
+      text-align: center;
+      color: #fff;
+      opacity: 0;
+    }
+.caption-word {
+      color: rgba(255, 255, 255, 0.55);
+    }
+  </style>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
+  <script>
+    (function () {
+      var GROUPS = ${JSON.stringify(groups)};
+      var cap = document.getElementById("cap");
+      var tl = gsap.timeline({ paused: true });
+      GROUPS.forEach(function (g) {
+        var el = document.createElement("div");
+        el.className = "caption-group";
+        g.words.forEach(function (w) {
+          var s = document.createElement("span");
+          s.className = "caption-word";
+          s.textContent = w.text + " ";
+          el.appendChild(s);
+        });
+        cap.appendChild(el);
+        tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: 0.18, overwrite: "auto" }, g.start);
+        tl.to(el, { opacity: 0, duration: 0.12, overwrite: "auto" }, g.end);
+        tl.set(el, { opacity: 0, visibility: "hidden" }, g.end + 0.12); // deterministic hard kill
+        g.words.forEach(function (w, i) {
+          tl.to(el.children[i], { color: "#ffffff", duration: 0.06 }, w.start);
+        });
+      });
+      tl.to({}, { duration: ${total} }, 0); // full-span anchor
+      window.__timelines = window.__timelines || {};
+      window.__timelines["captions"] = tl;
+    })();
+  </script>
+</template>
+`;
+}
+
+const sub = process.argv[2];
+if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
+else {
+  console.error(
+    "usage: node captions.mjs build [--storyboard …] [--audio-meta …] [--hyperframes .]",
+  );
+  process.exit(2);
+}

skills/faceless-explainer/scripts/lib/assets.mjs

@@ -0,0 +1,55 @@
+// assets.mjs — stage frame-named capture assets into assets/.
+// Shared by stage-assets.mjs (Step 4 close, BEFORE the frame workers run) and
+// assemble-index.mjs (Step 5, idempotent backstop). Only assets a frame names
+// in `asset_candidates` are staged; unnamed assets never reach the project.
+// asset_candidates value form: "assets/<basename> — desc; assets/… — …".
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export function basenamesFromCandidates(value) {
+  if (typeof value !== "string") return [];
+  return value
+    .split(";")
+    .map((seg) => seg.split(/\s+[—–-]\s+/)[0].trim()) // strip the " — description"
+    .filter(Boolean)
+    .map((p) => basename(p.replace(/^assets\//, "")));
+}
+
+// Copy each frame's asset_candidates from capture/{assets,assets/videos,
+// screenshots} into assets/. Already-staged files are left as is (first-wins),
+// so calling this twice is safe. Returns { staged, wanted, anomalies }.
+export function stageAssets({ hyperframesDir, frames }) {
+  const wanted = new Set();
+  for (const f of frames) {
+    for (const b of basenamesFromCandidates(f.extra?.asset_candidates)) wanted.add(b);
+  }
+  const captureDirs = [
+    join(hyperframesDir, "capture/assets"),
+    join(hyperframesDir, "capture/assets/videos"), // videos download into a subdir
+    join(hyperframesDir, "capture/screenshots"),
+  ];
+  const assetsDir = join(hyperframesDir, "assets");
+  const anomalies = [];
+  let staged = 0;
+  if (wanted.size > 0) {
+    mkdirSync(assetsDir, { recursive: true });
+    for (const b of wanted) {
+      const dest = join(assetsDir, b);
+      if (existsSync(dest)) {
+        staged++;
+        continue;
+      } // first-wins / already staged
+      const src = captureDirs.map((d) => join(d, b)).find((p) => existsSync(p));
+      if (src) {
+        copyFileSync(src, dest);
+        staged++;
+      } else {
+        anomalies.push(
+          `asset "${b}" named by a frame but not found under capture/ — frame will 404 it`,
+        );
+      }
+    }
+  }
+  return { staged, wanted, anomalies };
+}

skills/faceless-explainer/scripts/lib/dimensions.mjs

@@ -0,0 +1,45 @@
+// dimensions.mjs — canvas size + caption-band geometry for the video
+// pipeline. Single source of truth = the STORYBOARD frontmatter `format` global
+// ("1920x1080" / "1080x1920" / "1080x1080", or a named orientation). Every
+// script and the index assembler reads the size from here; none hardcodes it.
+
+// Named orientation presets. Square/portrait are 1080-based so they share the
+// long-edge pixel budget with landscape (same render-cost ballpark).
+export const ORIENTATION_PRESETS = {
+  landscape: { width: 1920, height: 1080 }, // 16:9 — default
+  portrait: { width: 1080, height: 1920 }, // 9:16 — reels / shorts / TikTok
+  square: { width: 1080, height: 1080 }, // 1:1 — feed
+};
+
+export const DEFAULT_DIMENSIONS = ORIENTATION_PRESETS.landscape;
+
+function sane(w, h) {
+  return Number.isFinite(w) && Number.isFinite(h) && w >= 240 && h >= 240 && w <= 8192 && h <= 8192;
+}
+
+// Parse a STORYBOARD `format` global into { width, height, source }. Accepts
+// "WxH" (e.g. "1920x1080"; `x` or `×`, any inner spacing) or a named orientation;
+// falls back to landscape so a storyboard with a missing/garbled format still
+// renders (no behavior change vs the old landscape lock).
+export function parseFormat(format) {
+  const s = typeof format === "string" ? format.trim().toLowerCase() : "";
+  if (ORIENTATION_PRESETS[s]) return { ...ORIENTATION_PRESETS[s], source: `orientation=${s}` };
+  const m = s.match(/^(\d+)\s*[x×]\s*(\d+)$/);
+  if (m) {
+    const w = parseInt(m[1] ?? "", 10);
+    const h = parseInt(m[2] ?? "", 10);
+    if (sane(w, h)) return { width: w, height: h, source: "format" };
+  }
+  return { ...DEFAULT_DIMENSIONS, source: "default(landscape)" };
+}
+
+// Caption band geometry, derived from canvas height: the bottom ~16.67% (180px
+// at h=1080). Frame content must end `safetyPx` above the band top. Holds even
+// when captions are disabled (bottom-edge consistency).
+export const CAPTION_BAND_FRACTION = 0.1667;
+export function captionBand(height, safetyPx = 20) {
+  const h = Number.isFinite(height) ? height : DEFAULT_DIMENSIONS.height;
+  const bandHeight = Math.round(h * CAPTION_BAND_FRACTION);
+  const bandTopY = h - bandHeight; // foreground must end at/above this y
+  return { bandHeight, bandTopY, foregroundMaxY: bandTopY - safetyPx };
+}

skills/faceless-explainer/scripts/lib/pad-frame-duration.mjs

@@ -0,0 +1,36 @@
+// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
+// sync with the padded index.html wrapper duration transitions.mjs computes.
+//
+// The frame's OWN internal file declares its #root/clip data-duration to the
+// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
+// upstream"). When an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, the frame's own internal
+// duration is left short — the render engine clip-gates the sub-composition's
+// visible content at that shorter value, so content vanishes abruptly at
+// content-end instead of fading gracefully through the wrapper's extended
+// fade-out tween. Pad the frame's own file to match so both durations agree.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
+  const framePath = resolve(hyperframesDir, frameSrc);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
+    if (!/data-duration="[\d.]+"/.test(tag)) continue;
+    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
+    if (newTag === tag) return;
+    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
+    return;
+  }
+}

skills/faceless-explainer/scripts/lib/storyboard.mjs

@@ -0,0 +1,249 @@
+// storyboard.mjs — vendored lenient parser for STORYBOARD.md.
+//
+// Faithful plain-JS port of @hyperframes/core/storyboard
+// (packages/core/src/storyboard/parseStoryboard.ts). Vendored because skills
+// ship standalone: installed via `npx skills add`, a skill's scripts can't reach
+// the monorepo's core package, and the core export points at .ts source that
+// `node` (which runs these scripts) can't load. CANONICAL contract = the core
+// parser + skills/hyperframes-core/references/storyboard-format.md; keep this in
+// lockstep. Behavior: never throws, accepts freeform narrative, recognizes
+// Frame/Beat/Scene headings at H2/H3, preserves unknown keys verbatim under
+// `extra` (keys lowercased). Pure node — no deps.
+
+export const FRAME_STATUSES = ["outline", "built", "animated"];
+export const DEFAULT_FRAME_STATUS = "outline";
+
+// Detection-only frame heading (ends at the keyword); ReDoS-hardened — keep as-is.
+const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
+const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
+const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
+const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
+const LEADING_INT_RE = /^(\d+)/;
+const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
+const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
+const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
+export const VOICEOVER_ALIASES = ["voiceover", "vo", "voice_over", "narration"];
+const VOICEOVER_KEYS = new Set(VOICEOVER_ALIASES);
+
+export function parseStoryboard(source) {
+  const warnings = [];
+  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
+  const frames = parseFrames(body, bodyStartLine, warnings);
+  return { globals, frames, warnings };
+}
+
+function emptyGlobals() {
+  return { extra: {} };
+}
+
+function isFrameStatus(value) {
+  return FRAME_STATUSES.includes(value);
+}
+
+// ── Frontmatter ─────────────────────────────────────────────────────────────
+function findFrontmatterRange(lines, warnings) {
+  let start = 0;
+  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
+  if ((lines[start] ?? "").trim() !== "---") return null;
+  for (let i = start + 1; i < lines.length; i++) {
+    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
+  }
+  warnings.push({
+    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
+    line: start + 1,
+  });
+  return null;
+}
+
+function parseFrontmatterEntries(lines, start, end, warnings) {
+  const globals = emptyGlobals();
+  for (let i = start + 1; i < end; i++) {
+    const raw = lines[i] ?? "";
+    if (raw.trim() === "") continue;
+    const colon = raw.indexOf(":");
+    if (colon === -1) {
+      warnings.push({
+        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
+        line: i + 1,
+      });
+      continue;
+    }
+    const key = raw.slice(0, colon).trim().toLowerCase();
+    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
+  }
+  return globals;
+}
+
+function parseFrontmatter(source, warnings) {
+  const lines = source.split(/\r?\n/);
+  const range = findFrontmatterRange(lines, warnings);
+  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };
+  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
+  const body = lines.slice(range.end + 1).join("\n");
+  return { globals, bodyStartLine: range.end + 2, body };
+}
+
+function assignGlobal(globals, key, value) {
+  switch (key) {
+    case "format":
+      globals.format = value;
+      break;
+    case "message":
+      globals.message = value;
+      break;
+    case "arc":
+      globals.arc = value;
+      break;
+    case "audience":
+      globals.audience = value;
+      break;
+    default:
+      globals.extra[key] = value;
+  }
+}
+
+// ── Frames ──────────────────────────────────────────────────────────────────
+function openFrameSection(line, headingLine) {
+  const match = FRAME_HEADING_RE.exec(line);
+  if (!match) return null;
+  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
+  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
+}
+
+function endsFrameSection(line, current) {
+  if (!current) return false;
+  const heading = HEADING_LEVEL_RE.exec(line);
+  return heading !== null && (heading[1] ?? "").length <= current.level;
+}
+
+function parseFrames(body, bodyStartLine, warnings) {
+  const lines = body.split(/\r?\n/);
+  const sections = [];
+  let current = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const opened = openFrameSection(line, bodyStartLine + i);
+    if (opened) {
+      sections.push(opened);
+      current = opened;
+    } else if (endsFrameSection(line, current)) {
+      current = null;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
+}
+
+function buildFrame(section, index, warnings) {
+  const frame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
+  const { number, title } = parseHeading(section.headingText);
+  if (number !== undefined) frame.number = number;
+  if (title) frame.title = title;
+
+  const narrativeLines = [];
+  for (const line of section.lines) {
+    const meta = META_RE.exec(line);
+    if (meta) {
+      applyMeta(
+        frame,
+        (meta[1] ?? "").toLowerCase(),
+        (meta[2] ?? "").trim(),
+        section.headingLine,
+        warnings,
+      );
+    } else {
+      narrativeLines.push(line);
+    }
+  }
+  frame.narrative = narrativeLines.join("\n").trim();
+  return frame;
+}
+
+function parseHeading(text) {
+  if (!text) return {};
+  const intMatch = LEADING_INT_RE.exec(text);
+  if (!intMatch) return { title: text };
+  const number = Number.parseInt(intMatch[1] ?? "", 10);
+  const rest = text
+    .slice((intMatch[0] ?? "").length)
+    .replace(/^[\s.:—-]+/, "")
+    .trim();
+  return { number, title: rest || undefined };
+}
+
+// Dispatch a recognized metadata key to its field, else stash under `extra`.
+// Mirrors core's META_SETTERS map exactly (direct keys + alias sets).
+function applyMeta(frame, key, value, headingLine, warnings) {
+  switch (key) {
+    case "duration":
+      applyDuration(frame, value, headingLine, warnings);
+      return;
+    case "status":
+      applyStatus(frame, value, headingLine, warnings);
+      return;
+    case "poster":
+      applyPoster(frame, value);
+      return;
+    case "src":
+      frame.src = value;
+      return;
+  }
+  if (TRANSITION_KEYS.has(key)) {
+    frame.transitionIn = value;
+    return;
+  }
+  if (SCENE_KEYS.has(key)) {
+    frame.scene = value;
+    return;
+  }
+  if (VOICEOVER_KEYS.has(key)) {
+    frame.voiceover = stripQuotes(value);
+    return;
+  }
+  frame.extra[key] = value;
+}
+
+function applyPoster(frame, value) {
+  const num = DURATION_NUM_RE.exec(value);
+  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
+}
+
+function applyDuration(frame, value, headingLine, warnings) {
+  frame.duration = value;
+  const num = DURATION_NUM_RE.exec(value);
+  if (num) {
+    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
+    return;
+  }
+  warnings.push({
+    message: `Frame ${frame.index}: could not parse duration "${value}".`,
+    line: headingLine,
+    frameIndex: frame.index,
+  });
+}
+
+function applyStatus(frame, value, headingLine, warnings) {
+  const normalized = value.toLowerCase();
+  if (isFrameStatus(normalized)) {
+    frame.status = normalized;
+    return;
+  }
+  frame.extra.status = value;
+  warnings.push({
+    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
+    line: headingLine,
+    frameIndex: frame.index,
+  });
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}

skills/faceless-explainer/scripts/lib/tokens.mjs

@@ -0,0 +1,219 @@
+// tokens.mjs — shared brand-token parsing + semantic role mapping for frame.md /
+// FRAME.md. Used by build-frame.mjs (remix a preset onto brand tokens) and
+// captions.mjs (derive caption colors from frame.md). One mapping → frames and
+// captions stay consistent. Pure node.
+
+// Collect `key: value` pairs under the top-level `colors:` block (until dedent).
+export function parseColors(md) {
+  const out = [];
+  let inBlock = false;
+  for (const line of md.split(/\r?\n/)) {
+    if (/^colors:\s*$/.test(line)) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) continue;
+    if (/^\S/.test(line)) break; // dedent to a top-level key → end of block
+    const m = line.match(
+      /^\s+([\w-]+):\s*(?:"([^"]+)"|'([^']+)'|(#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)|[^#\s][^#\n]*?))\s*(?:#.*)?$/,
+    );
+    if (m) out.push([m[1], (m[2] ?? m[3] ?? m[4]).trim()]);
+  }
+  return out;
+}
+
+// relative luminance of a #rrggbb (null for non-hex like rgba()).
+export function lum(v) {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(v).trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return 0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255);
+}
+
+// chroma (max−min channel) of a #rrggbb — a cheap "how colorful" proxy; −1 for non-hex.
+export function chroma(v) {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(v).trim());
+  if (!m) return -1;
+  const n = parseInt(m[1], 16);
+  const r = (n >> 16) & 255,
+    g = (n >> 8) & 255,
+    b = n & 255;
+  return Math.max(r, g, b) - Math.min(r, g, b);
+}
+
+// Browser user-agent default colors for links / visited links. These leak into a
+// capture from any UNSTYLED <a> and are NOT brand colors — but being pure & saturated
+// they beat a real accent on chroma alone. Never let one become the accent.
+export const UA_DEFAULT_COLORS = new Set(
+  ["#0000EE", "#0000FF", "#0000CC", "#1A0DAB", "#551A8B", "#EE0000"].map((c) => c.toUpperCase()),
+);
+
+// Semantic STATUS roles (green "positive", red "negative"/"error", amber "warning" …). Their HUE
+// carries the meaning, so they are never a brand ACCENT — a status red is frequently the most
+// chromatic color in a palette (e.g. #dc2626 chroma 182 beats a deep-blue accent #1E40AF chroma
+// 145) and would otherwise win a pure chroma ranking, painting captions/highlights the error red.
+// build-frame.mjs uses this same key set to protect status colors during the preset→brand remix.
+export const STATUS_ROLE_KEY =
+  /(?:^|[-_])(?:positive|negative|success|error|warning|danger|good|bad|up|down|info|neutral|alert|caution|critical)(?:[-_]|$)/i;
+
+// Pick the brand ACCENT — never by raw chroma alone, never a UA-default link color.
+// Priority:
+//   1) with capture colorStats → the colorful color that RECURS across the UI. The brand
+//      accent shows up in MANY roles (link text + icon + button + badge), whereas a one-off
+//      CTA fill appears in just one. So rank chromatic (chroma>40) candidates by role
+//      diversity first, then total prevalence, then interactive use, then chroma. This keeps
+//      a pervasive brand color (e.g. an indigo used everywhere) ahead of a single bright
+//      button fill (e.g. a lime used once) — the old "top interactiveBg" rule picked the
+//      latter. Requiring interactiveBg>0 is dropped so a text/icon-only accent can still win.
+//   2) no stats → most chromatic color AFTER removing UA defaults + `exclude`.
+// A stray default link color (e.g. #0000EE) can win under neither path.
+export function pickAccent(stats, colors, exclude = []) {
+  const ban = new Set([...exclude, ...UA_DEFAULT_COLORS].map((c) => String(c).toUpperCase()));
+  const ok = (h) => /^#[0-9a-fA-F]{6}$/.test(String(h)) && !ban.has(String(h).toUpperCase());
+  // Prominence rank from the (frequency-ordered) `colors` palette: index 0 = most used.
+  // A saturated color sitting at the TAIL is almost always a one-off (a single CTA fill),
+  // not the brand accent — capture colorStats counts are too sparse to tell these apart
+  // (e.g. Linear's indigo and a lime CTA both register count≈1), but palette ORDER does.
+  const rank = new Map((colors ?? []).map((h, i) => [String(h).toUpperCase(), i]));
+  const prom = (h) => (rank.has(String(h).toUpperCase()) ? rank.get(String(h).toUpperCase()) : 1e9);
+  if (Array.isArray(stats) && stats.length) {
+    const roles = (s) =>
+      ((s.interactiveBg || 0) > 0 ? 1 : 0) +
+      ((s.textCount || 0) > 0 ? 1 : 0) +
+      ((s.bgCount || 0) > 0 ? 1 : 0);
+    const a = stats
+      .filter((s) => ok(s?.hex) && chroma(s.hex) > 40)
+      .sort(
+        (x, y) =>
+          roles(y) - roles(x) || // used in MORE roles (link+icon+button) = the brand accent
+          prom(x.hex) - prom(y.hex) || // earlier in the palette = more prominent
+          (y.count || 0) - (x.count || 0) ||
+          (y.interactiveBg || 0) - (x.interactiveBg || 0) ||
+          chroma(y.hex) - chroma(x.hex),
+      );
+    if (a.length) return a[0].hex;
+  }
+  const c = (colors ?? [])
+    .map(String)
+    .filter(ok)
+    .sort((x, y) => chroma(y) - chroma(x));
+  return c[0];
+}
+
+// Derive brand roles from rich capture colorStats (areaBg / interactiveBg / textCount /
+// maxArea) — by semantic FUNCTION, not luminance/chroma proxies. Returns null when stats
+// are unusable, so the caller can fall back. canvas = the color painting the most real
+// background area (the page ground, dark or light); ink = the dominant text color that
+// actually contrasts with the canvas; accent via pickAccent.
+export function brandRolesFromStats(stats, colorsInOrder) {
+  if (!Array.isArray(stats) || !stats.length) return null;
+  const v = stats.filter((s) => /^#[0-9a-fA-F]{6}$/.test(s?.hex || ""));
+  if (!v.length) return null;
+  const canvas = [...v].sort(
+    (a, b) =>
+      (b.areaBg || 0) - (a.areaBg || 0) ||
+      (b.maxArea || 0) - (a.maxArea || 0) ||
+      (b.bgCount || 0) - (a.bgCount || 0),
+  )[0]?.hex;
+  // pass the frequency-ordered palette (tokens.colors) so pickAccent can use palette
+  // PROMINENCE — colorStats counts alone are too sparse to rank rare accents.
+  const accent = pickAccent(v, colorsInOrder ?? v.map((s) => s.hex), [canvas]);
+  if (!canvas || !accent) return null;
+  const cl = lum(canvas) ?? 0;
+  const ink =
+    [...v]
+      .filter((s) => s.hex !== canvas && s.hex !== accent)
+      .sort((a, b) => (b.textCount || 0) - (a.textCount || 0))
+      .find((s) => Math.abs((lum(s.hex) ?? 0) - cl) > 64)?.hex ??
+    (cl > 128 ? "#000000" : "#FFFFFF");
+  const accent2 =
+    v
+      .filter(
+        (s) =>
+          ![canvas, ink, accent].includes(s.hex) &&
+          (s.interactiveBg || 0) > 0 &&
+          chroma(s.hex) > 40 &&
+          !UA_DEFAULT_COLORS.has(s.hex.toUpperCase()),
+      )
+      .sort((a, b) => (b.interactiveBg || 0) - (a.interactiveBg || 0))[0]?.hex ?? accent;
+  return { ink, canvas, accent, accent2 };
+}
+
+// Map a list of [key, value] colors to semantic roles. ink = a dark/ink-named
+// color (else darkest); canvas = a paper/cream/white-named color (else lightest);
+// accents = whatever's left, ranked by chroma (the loudest color is almost always
+// the brand accent) — UA-default link colors AND semantic status colors (positive/
+// negative/error…) excluded so neither a stray <a> color nor a status red ever wins.
+// For an unkeyed brand list, pass synthetic keys — name matching simply no-ops and it
+// falls back to luminance/chroma, which is what we want. NOTE: when capture colorStats
+// exist, prefer brandRolesFromStats() — it picks by function, not these proxies.
+export function semanticColors(colors) {
+  if (!colors.length) return {};
+  const named = (re) => colors.find(([k]) => re.test(k));
+  const hexes = colors.filter(([, v]) => lum(v) != null);
+  const byLum = [...hexes].sort((a, b) => (lum(a[1]) ?? 1e9) - (lum(b[1]) ?? 1e9));
+  const pick = (m, fallback) => (m ? m[1] : fallback ? fallback[1] : undefined);
+  // "ink" must be a whole word-segment so "soft-pink"/"pink" don't match it.
+  const ink = pick(
+    named(/(?:^|[-_])ink(?:[-_]|$)|black|charcoal|^text(?:-dark)?$|outline|noir/i),
+    byLum[0] ?? colors[0],
+  );
+  const canvas = pick(
+    named(/cream|paper|canvas|white|bg|ground|surface|base|sand|parchment|off-?white|bone/i),
+    byLum[byLum.length - 1] ?? colors[colors.length - 1],
+  );
+  const accents = colors
+    .filter(
+      ([k, v]) =>
+        v !== ink &&
+        v !== canvas &&
+        !UA_DEFAULT_COLORS.has(String(v).toUpperCase()) &&
+        !STATUS_ROLE_KEY.test(k), // a status red/green carries meaning by hue — never an accent
+    )
+    .sort((a, b) => chroma(b[1]) - chroma(a[1]))
+    .map(([, v]) => v);
+  return { ink, canvas, accent: accents[0] ?? ink, accent2: accents[1] ?? accents[0] ?? ink };
+}
+
+// Collect role→fontFamily under the top-level `typography:` block; pick a display
+// + body family from the usual role names. Returns quoted families (or null).
+export function parseFonts(md) {
+  const roles = {};
+  let inBlock = false;
+  for (const line of md.split(/\r?\n/)) {
+    if (/^typography:\s*$/.test(line)) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) continue;
+    if (/^\S/.test(line)) break;
+    const m = line.match(/^\s+([\w-]+):\s*\{[^}]*fontFamily:\s*"([^"]+)"/);
+    if (m) roles[m[1]] = m[2];
+  }
+  const q = (s) => (s ? `"${s}"` : null);
+  const body = roles.body ?? roles.subtitle ?? Object.values(roles)[0];
+  const display =
+    roles.display ??
+    roles.headline ??
+    roles["card-headline"] ??
+    roles["section-headline"] ??
+    roles["quote-display"] ??
+    roles.h1 ??
+    roles.h2 ??
+    roles.title ??
+    roles.hero ??
+    body;
+  // the monospace / chrome family (code, tags, ticks, page numbers) — so the remix can
+  // route a captured brand mono (Berkeley Mono, JetBrains Mono…) onto this role instead
+  // of the reading body. null when the preset has no distinct mono role.
+  const mono =
+    roles.mono ??
+    roles["mono-tag"] ??
+    roles["mono-chrome"] ??
+    roles["mono-tick"] ??
+    roles.code ??
+    roles.data ??
+    roles.pagenum ??
+    null;
+  return { display: q(display), body: q(body), mono: q(mono) };
+}

skills/faceless-explainer/scripts/lib/transition-registry.mjs

@@ -0,0 +1,38 @@
+// transition-registry.mjs — loader for this skill's vendored transition registry
+// (./transitions.json). The registry is the curated Tier-B subset (transform /
+// opacity / filter on the two frame clip wrappers `#el-<id>`, no overlay DOM) +
+// each type's GSAP template. Vendored into the skill so it ships standalone; the
+// recipes originate from the shared catalog skills/hyperframes-animation/
+// transitions/ (css-*.md) — keep them in step if those shared recipes change.
+
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_REGISTRY_PATH = resolve(here, "./transitions.json");
+
+let _cache = null;
+
+export function loadTransitionRegistry(registryPath = DEFAULT_REGISTRY_PATH) {
+  if (_cache && _cache.path === registryPath) return _cache.data;
+  let data;
+  try {
+    data = JSON.parse(readFileSync(registryPath, "utf8"));
+  } catch (e) {
+    throw new Error(`transition registry not loadable at ${registryPath}: ${e.message}`);
+  }
+  if (!Array.isArray(data.transitions) || data.transitions.length === 0) {
+    throw new Error(`transition registry ${registryPath} has no transitions[]`);
+  }
+  _cache = { path: registryPath, data };
+  return data;
+}
+
+// Convenience: a Map name -> transition record.
+export function transitionsByName(registryPath = DEFAULT_REGISTRY_PATH) {
+  const data = loadTransitionRegistry(registryPath);
+  const map = new Map();
+  for (const t of data.transitions) map.set(t.name, t);
+  return map;
+}

skills/faceless-explainer/scripts/lib/transitions.json

@@ -0,0 +1,71 @@
+{
+  "_comment": "Vendored transition registry for the product-launch workflow — the curated Tier-B subset (transform/opacity/filter on the two frame clip wrappers #el-<id>, no overlay DOM, no per-frame cooperation). Each type carries its GSAP template; the transitions.mjs injector stamps it onto window.__timelines[\"main\"]. Recipes originate from the shared catalog skills/hyperframes-animation/transitions/ (css-*.md) — keep in step if those change. Token placeholders the injector substitutes: __OLD__ (#el-<from>), __NEW__ (#el-<to>), __T__ (overlap-start s), __DUR__ (this boundary's duration), __DX__/__DXIN__ (horizontal travel + incoming offset), __DY__/__DYIN__ (vertical).",
+  "transitions": [
+    {
+      "name": "crossfade",
+      "energy": "any",
+      "default_duration_s": 0.5,
+      "directions": [],
+      "source": "css-dissolve.md",
+      "gsap_template": [
+        "tl.to(__OLD__, { opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { opacity: 0 }, { opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "blur-crossfade",
+      "energy": "calm",
+      "default_duration_s": 0.6,
+      "directions": [],
+      "source": "css-dissolve.md",
+      "note": "Default when the two frames' #root backgrounds differ a lot — the blur masks the background-color clash a plain crossfade would expose.",
+      "gsap_template": [
+        "tl.to(__OLD__, { filter: \"blur(10px)\", scale: 1.03, opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { filter: \"blur(10px)\", scale: 0.97, opacity: 0 }, { filter: \"blur(0px)\", scale: 1, opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "push-slide",
+      "energy": "medium",
+      "default_duration_s": 0.5,
+      "directions": ["LEFT", "RIGHT", "UP", "DOWN"],
+      "default_direction": "LEFT",
+      "source": "css-push.md",
+      "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
+      "gsap_template_horizontal": [
+        "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ],
+      "gsap_template_vertical": [
+        "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ]
+    },
+    {
+      "name": "zoom-through",
+      "energy": "high",
+      "default_duration_s": 0.4,
+      "directions": [],
+      "source": "css-scale.md",
+      "gsap_template": [
+        "tl.to(__OLD__, { scale: 2.5, opacity: 0, filter: \"blur(8px)\", duration: __DUR__, ease: \"power3.in\" }, __T__);",
+        "tl.fromTo(__NEW__, { scale: 0.5, opacity: 0, filter: \"blur(8px)\" }, { scale: 1, opacity: 1, filter: \"blur(0px)\", duration: __DUR__, ease: \"power3.out\" }, __T__);"
+      ]
+    },
+    {
+      "name": "squeeze",
+      "energy": "medium",
+      "default_duration_s": 0.4,
+      "directions": [],
+      "source": "css-push.md",
+      "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
+      "gsap_template": [
+        "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
+        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+      ]
+    }
+  ],
+  "default_high_energy": "zoom-through",
+  "default_calm": "blur-crossfade",
+  "max_duration_s": 2.0
+}

skills/faceless-explainer/scripts/transitions.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+// transitions.mjs — inter-frame transition injector + verifier for the video workflow.
+//
+//   inject  — read STORYBOARD frame order + each frame's transition_in, overlap
+//             the frame clip wrappers in index.html, and stamp the GSAP template.
+//   verify  — deterministic gate over the injector's output.
+//
+// transition_in (written by story-design on the INCOMING frame) names a registry
+// type directly: crossfade | blur-crossfade | push-slide | zoom-through | squeeze,
+// optionally "<type> <DIR>" / "<type> <N>s" (e.g. "push-slide LEFT", "crossfade
+// 0.4s"). `cut` / `none` / empty ⇒ hard cut (no overlap, no stamp).
+//
+// Mechanics — EXTEND-OUTGOING-ONLY (keeps voice/SFX/captions synced; their timing
+// is keyed to the original frame start). At boundary i→i+1 (type = the incoming
+// frame's transition_in): extend ONLY the outgoing wrapper's data-duration by
+// `dur` so it holds its final frame across the window; do NOT move any data-start;
+// the incoming — already present from the cut on a higher track — fades/pushes in
+// over it. Then 0/1-ping-pong ALL frame clips' data-track-index (adjacent
+// overlapping wrappers never share a track — lint timeline_track_too_dense) and
+// stamp the token-substituted GSAP template into __timelines["main"] at T =
+// incoming start. captions(2)/voice(10)/bgm(11)/sfx(20+) are never touched.
+//
+//   node transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
+//   node transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseStoryboard } from "./lib/storyboard.mjs";
+import { parseFormat } from "./lib/dimensions.mjs";
+import { loadTransitionRegistry, transitionsByName } from "./lib/transition-registry.mjs";
+import { padFrameInternalDuration } from "./lib/pad-frame-duration.mjs";
+
+const flag = (argv, name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const NO_TRANSITION = new Set(["cut", "none", ""]);
+const r3 = (x) => Number(x.toFixed(3));
+
+// transition_in → { type, direction?, dur? } | null (hard cut).
+function parseTransitionIn(raw) {
+  const s = (raw ?? "").trim();
+  if (NO_TRANSITION.has(s.toLowerCase())) return null;
+  const parts = s.split(/\s+/);
+  const spec = { type: parts[0].toLowerCase() };
+  for (const p of parts.slice(1)) {
+    const m = p.match(/^(\d+(?:\.\d+)?)s?$/);
+    if (m) spec.dur = Number(m[1]);
+    else spec.direction = p.toUpperCase();
+  }
+  return spec;
+}
+
+// Mounted STORYBOARD frames present in index.html, in document order: { id, frame }.
+function mountedFramesInOrder(manifest, html) {
+  const out = [];
+  for (const f of manifest.frames) {
+    if (!f.src) continue;
+    const id = f.src
+      .split("/")
+      .pop()
+      .replace(/\.html?$/i, "");
+    if (html.includes(`id="el-${id}"`)) out.push({ id, frame: f });
+  }
+  return out;
+}
+
+// Frame clip wrappers parsed out of index.html (ids carry hyphens; excludes
+// el-captions and audio by keying off the known frame-id set). The id is matched
+// from anywhere in the tag's attribute list — never assume it is the first attribute
+// (the index assembler emits data-hf-id before id, so an id-first regex finds nothing
+// and inject crashes on the empty clip map).
+function parseFrameClips(html, frameIds) {
+  const clipRe = /<div\b([^>]*)><\/div>/g;
+  const clips = new Map();
+  let m;
+  while ((m = clipRe.exec(html)) !== null) {
+    const attrs = m[1];
+    const idm = attrs.match(/\bid="el-([A-Za-z0-9_-]+)"/);
+    if (!idm || !frameIds.has(idm[1])) continue;
+    const num = (re) => {
+      const x = attrs.match(re);
+      return x ? Number(x[1]) : null;
+    };
+    clips.set(idm[1], {
+      id: idm[1],
+      block: m[0],
+      start: num(/data-start="([\d.]+)"/),
+      duration: num(/data-duration="([\d.]+)"/),
+      track: num(/data-track-index="(\d+)"/) ?? 0,
+    });
+  }
+  return clips;
+}
+
+// The host wrapper is extended across an outgoing transition, so the mounted
+// frame must remain visually populated for the same local-time window. Extend
+// the frame root and every non-audio timed element that reached the original
+// storyboard boundary. This also repairs worker files whose root was already
+// inflated while their ground/content clips still ended at the synced duration.
+function extendFrameTail(hyperframesDir, frame, baseDuration, targetDuration, die) {
+  if (!frame?.src || targetDuration <= baseDuration) return;
+  const framePath = join(hyperframesDir, frame.src);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch {
+    die(`outgoing frame file not found at ${framePath}`);
+  }
+
+  const compId = frame.src
+    .split("/")
+    .pop()
+    .replace(/\.html?$/i, "");
+  const EPS = 0.011;
+  let foundRoot = false;
+  let extended = 0;
+  const rewritten = html.replace(/<([A-Za-z][\w:-]*)\b([^>]*)>/g, (tag, name, attrs) => {
+    const durationMatch = attrs.match(/\bdata-duration="([\d.]+)"/);
+    if (!durationMatch) return tag;
+    const duration = Number(durationMatch[1]);
+    if (!Number.isFinite(duration)) return tag;
+
+    const compositionMatch = attrs.match(/\bdata-composition-id="([^"]+)"/);
+    if (compositionMatch?.[1] === compId && !foundRoot) {
+      foundRoot = true;
+      return tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${targetDuration}"`);
+    }
+
+    if (name.toLowerCase() === "audio") return tag;
+    const startMatch = attrs.match(/\bdata-start="([\d.]+)"/);
+    if (!startMatch) return tag;
+    const start = Number(startMatch[1]);
+    const end = start + duration;
+    if (end < baseDuration - EPS || end >= targetDuration - EPS) return tag;
+    extended++;
+    return tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${r3(targetDuration - start)}"`);
+  });
+
+  if (!foundRoot) die(`${frame.src} has no data-composition-id="${compId}" root`);
+  writeFileSync(framePath, rewritten);
+  console.log(
+    `  ${compId}: extended root + ${extended} tail clip(s) ${baseDuration}s→${targetDuration}s`,
+  );
+}
+
+// Resolve a transition_in spec to a registry record (calm default on unknown).
+function resolveRecord(spec, byName, reg, warn) {
+  let rec = byName.get(spec.type);
+  if (!rec) {
+    rec = byName.get(reg.default_calm);
+    warn(`transition_in "${spec.type}" not in registry — using ${reg.default_calm}`);
+  }
+  return rec;
+}
+function resolveDur(spec, rec, reg) {
+  let dur = spec.dur ?? rec.default_duration_s ?? 0.5;
+  return Math.min(dur, reg.max_duration_s ?? 2.0);
+}
+
+// GSAP lines for one transition record (token substitution).
+function buildGsap(rec, fromId, toId, dur, T, direction, canvasW, canvasH, die) {
+  const subs = {
+    __OLD__: `"#el-${fromId}"`,
+    __NEW__: `"#el-${toId}"`,
+    __T__: String(T),
+    __DUR__: String(dur),
+  };
+  let template;
+  if (rec.directions && rec.directions.length > 0) {
+    const dir = (direction || rec.default_direction || rec.directions[0]).toUpperCase();
+    const vertical = dir === "UP" || dir === "DOWN";
+    template = vertical ? rec.gsap_template_vertical : rec.gsap_template_horizontal;
+    if (!template)
+      die(`transition ${rec.name}: missing ${vertical ? "vertical" : "horizontal"} template`);
+    if (vertical) {
+      const dy = dir === "UP" ? -canvasH : canvasH;
+      subs.__DY__ = String(dy);
+      subs.__DYIN__ = String(-dy);
+    } else {
+      const dx = dir === "LEFT" ? -canvasW : canvasW;
+      subs.__DX__ = String(dx);
+      subs.__DXIN__ = String(-dx);
+    }
+  } else {
+    template = rec.gsap_template;
+    if (!template) die(`transition ${rec.name}: missing gsap_template`);
+  }
+  return template.map((line) => {
+    let out = line;
+    for (const [k, v] of Object.entries(subs)) out = out.split(k).join(v);
+    return out;
+  });
+}
+
+function runInject(argv) {
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const indexPath = join(hyperframesDir, "index.html");
+  const die = (msg) => {
+    console.error(`✗ transitions inject: ${msg}`);
+    process.exit(1);
+  };
+
+  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+  const { width: CW, height: CH } = parseFormat(manifest.globals.format);
+  const reg = loadTransitionRegistry();
+  const byName = transitionsByName();
+
+  // Read directly and handle ENOENT here, rather than an existsSync precheck —
+  // the check→write pair (write-back below) is a TOCTOU race CodeQL flags.
+  let html = "";
+  try {
+    html = readFileSync(indexPath, "utf8");
+  } catch {
+    die(`index.html not found at ${indexPath} — run assemble-index.mjs first`);
+  }
+  const order = mountedFramesInOrder(manifest, html);
+  if (order.length === 0) die("no frame clips found in index.html");
+  const frameIds = new Set(order.map((x) => x.id));
+  const clips = parseFrameClips(html, frameIds);
+
+  const gsapLines = [];
+  const applied = [];
+  for (let i = 1; i < order.length; i++) {
+    const spec = parseTransitionIn(order[i].frame.transitionIn);
+    if (!spec) continue; // hard cut
+    const incoming = clips.get(order[i].id);
+    const outgoing = clips.get(order[i - 1].id);
+    const rec = resolveRecord(spec, byName, reg, (m) =>
+      console.error(`  ! frame ${order[i].id}: ${m}`),
+    );
+    const dur = resolveDur(spec, rec, reg);
+    const T = r3(incoming.start); // cut = incoming start (frames tile)
+    const baseDuration = outgoing.duration;
+    outgoing.duration = r3(baseDuration + dur); // extend outgoing only
+    extendFrameTail(hyperframesDir, order[i - 1].frame, baseDuration, outgoing.duration, die);
+    padFrameInternalDuration(
+      hyperframesDir,
+      order[i - 1].frame.src,
+      outgoing.id,
+      outgoing.duration,
+    );
+    gsapLines.push(
+      ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
+    );
+    applied.push({ from: outgoing.id, to: incoming.id, type: rec.name, dur, T });
+  }
+
+  if (applied.length === 0) {
+    console.log(`✓ transitions inject: 0 transitions (all cuts) — index.html unchanged`);
+    return;
+  }
+
+  // 0/1 ping-pong all frame clips in play order.
+  const ordered = [...clips.values()].sort((a, b) => a.start - b.start || a.id.localeCompare(b.id));
+  ordered.forEach((c, i) => {
+    c.track = i % 2;
+  });
+
+  // rewrite each clip block: start unchanged; duration possibly extended; track ping-ponged.
+  for (const c of clips.values()) {
+    const nb = c.block
+      .replace(/data-duration="[\d.]+"/, `data-duration="${c.duration}"`)
+      .replace(/data-track-index="\d+"/, `data-track-index="${c.track}"`);
+    html = html.replace(c.block, nb);
+  }
+
+  // stamp the GSAP after the master timeline anchor.
+  const anchor = 'window.__timelines["main"] = gsap.timeline({ paused: true });';
+  if (!html.includes(anchor)) die("master timeline anchor not found in index.html");
+  // The transition tweens alone leave window.__timelines["main"] spanning only the
+  // last transition (e.g. 24.7s), shorter than the real composition. The Studio
+  // reads main.duration() as its master duration and parses clips against it, so a
+  // short master collapses its timeline (clips dropped, duration wrong, blank stage)
+  // — the render engine is unaffected (it trusts the root data-duration attr). Stamp
+  // a full-span anchor so main.duration() == composition total. Mirrors the
+  // `tl.to({}, { duration })` anchor captions.html already uses.
+  const rootDurMatch = html.match(/data-composition-id="main"[^>]*?data-duration="([\d.]+)"/);
+  const totalDur = rootDurMatch ? Number(rootDurMatch[1]) : null;
+  const block = [
+    anchor,
+    "      // ── frame transitions (injected by transitions.mjs) ──",
+    '      (function () { var tl = window.__timelines["main"];',
+    ...gsapLines.map((l) => "        " + l),
+    ...(totalDur
+      ? [
+          `        tl.to({}, { duration: ${totalDur} }, 0); // full-span anchor — main.duration() == composition total (Studio master duration)`,
+        ]
+      : []),
+    "      })();",
+  ].join("\n");
+  html = html.replace(anchor, block);
+
+  writeFileSync(indexPath, html);
+  console.log(`✓ transitions inject: ${applied.length} transition(s) stamped into index.html`);
+  for (const a of applied) console.log(`  ${a.from}→${a.to}: ${a.type} ${a.dur}s @ T=${a.T}s`);
+  const tracks = ordered
+    .map((c) => `${c.id}[t${c.track} ${c.start}→${r3(c.start + c.duration)}]`)
+    .join(" ");
+  console.log(`  tracks: ${tracks}`);
+}
+
+function runVerify(argv) {
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const indexPath = resolve(flag(argv, "index", join(hyperframesDir, "index.html")));
+  const bail = (msg) => {
+    console.error(`✗ transitions verify: ${msg}`);
+    process.exit(1);
+  };
+
+  if (!existsSync(storyboardPath)) bail("STORYBOARD.md not found");
+  if (!existsSync(indexPath)) bail("index.html not found");
+
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+  const html = readFileSync(indexPath, "utf8");
+  const order = mountedFramesInOrder(manifest, html);
+  const frameIds = new Set(order.map((x) => x.id));
+  const clips = parseFrameClips(html, frameIds);
+
+  const EPS = 0.011;
+  const overlaps = (a, b) =>
+    a.start < b.start + b.duration - EPS && b.start < a.start + a.duration - EPS;
+  const fail = [];
+
+  // (4) global no same-track overlap (the lint invariant).
+  const all = [...clips.values()];
+  for (let i = 0; i < all.length; i++)
+    for (let j = i + 1; j < all.length; j++) {
+      const a = all[i];
+      const b = all[j];
+      if (a.track === b.track && overlaps(a, b))
+        fail.push(`same-track overlap: ${a.id}[t${a.track}] & ${b.id}[t${b.track}]`);
+    }
+
+  const bm = html.match(/frame transitions \(injected[\s\S]*?\}\)\(\);/);
+  const txBlock = bm ? bm[0] : "";
+
+  let expected = 0;
+  for (let i = 1; i < order.length; i++) {
+    const spec = parseTransitionIn(order[i].frame.transitionIn);
+    if (!spec) continue;
+    expected++;
+    const to = clips.get(order[i].id);
+    const from = clips.get(order[i - 1].id);
+    if (!to || !from) {
+      fail.push(`boundary ${order[i - 1].id}→${order[i].id}: wrapper missing`);
+      continue;
+    }
+    if (!txBlock.includes(`"#el-${from.id}"`) || !txBlock.includes(`"#el-${to.id}"`))
+      fail.push(`boundary ${from.id}→${to.id}: injected block does not reference both ids`);
+    const overlapAmt = r3(from.start + from.duration - to.start);
+    if (overlapAmt <= 0) fail.push(`boundary ${from.id}→${to.id}: no overlap (${overlapAmt}s)`);
+    if (from.track === to.track)
+      fail.push(`boundary ${from.id}→${to.id}: both on track ${from.track}`);
+  }
+  if (expected > 0 && !txBlock)
+    fail.push(`${expected} transition(s) expected but no injected block found`);
+
+  if (fail.length) {
+    console.error(`✗ transitions verify: ${fail.length} failure(s):`);
+    for (const f of fail) console.error(`  - ${f}`);
+    process.exit(1);
+  }
+  console.log(
+    `✓ transitions verify: ${expected} transition(s) verified (cross-track, overlap>0, both ids referenced, no same-track overlap)`,
+  );
+}
+
+const sub = process.argv[2];
+const rest = process.argv.slice(3);
+if (sub === "inject") runInject(rest);
+else if (sub === "verify") runVerify(rest);
+else {
+  console.error("usage: node transitions.mjs <inject|verify> [args...]");
+  process.exit(2);
+}

skills/faceless-explainer/sub-agents/frame-worker.md

@@ -0,0 +1,75 @@
+# Frame worker — faceless-explainer per-frame composition author
+
+> You build **one** frame's composition HTML and nothing else. You run N-up, one frame each — siblings build the others. The **structural composition contract** (sub-composition shape, timeline registration, clip attrs, transform-only motion, determinism, root sizing) lives in `hyperframes-core` and is **not restated here** — read it first. This file carries only what's specific to a faceless-explainer frame. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in `hyperframes-core`.
+
+**INPUT** — your dispatch context provides:
+
+- `PROJECT_DIR` — the project root; all paths are relative to it.
+- `frame_id` — e.g. `03-compounds`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-compounds.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
+- Your **`## Frame N` block** in `STORYBOARD.md` (read it; never write to that file — see below):
+  - `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
+  - `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
+  - `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
+  - `transition_in` — informational. The injector stamps it at the root; **you do not author transitions.**
+  - the **time-coded shot sequence** — your build spec. A sequence of Scene lines (`Scene 1 (0.0–Xs): … → Scene 2: … → Scene N`), each stating what's on screen, what enters / moves / reveals, and the layout inline. Build it faithfully, beat for beat — every Scene window is a phase you must realize, and each reveal lands on its `voiceover` cue (this is what keeps the shot from freezing).
+  - `blueprint:` — an id (or the literal `compose`). The id points to `../hyperframes-animation/blueprints/<id>.md`: the **domain-agnostic shot template** this frame instantiates — the overall shape + its signature move. Read it for the shape; `compose` means there's no template, sequence the shot from the Scene lines directly.
+  - `focal:` — which **invented** element is the hero.
+  - `roles:` — each invented element's role: `foreground subject` / `background` full-bleed / `supporting`. Because the explainer is **faceless, these are elements you design** (a hero word, a diagram node, a chart series, a coined-term card), not captured assets. The **only** real media is a user-supplied image, when present: `public/<basename> — description` (a **`[video]`** tag marks a `.mp4` clip the user provided).
+  - `sfx:` — the orchestrator's; you mount no audio.
+- `frame.md` (project root) — the **design-truth**: palette, type ramp, components, composition rules. The LOOK. Pull every visual token from here.
+- `RULES_DIR` — absolute path to this skill's local `../hyperframes-animation/rules/`. The **named motion verbs in the Scene lines** (and the moves the blueprint cites) resolve to rule recipes here: `RULES_DIR/<id>.md` is the mechanics for a motion. (A few rules link an optional runnable demo in the shared `../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.)
+- `../references/cut-catalog.md` — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
+- Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
+
+**Retry** — if your context carries lint / validate feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
+
+**OUTPUT** — `compositions/frames/<frame_id>.html`, one self-contained sub-composition. Writing it (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
+
+## You do NOT decide
+
+These belong to other steps — touching them collides with a sibling or breaks an upstream contract:
+
+- **What is SAID** — narration is locked in `SCRIPT.md` / the `voiceover` line. You only show; you never write or restate narration text.
+- **Duration** — fixed from real voice timing. Build your entrance to land within it; don't stretch or trim it.
+- **Transitions between frames** — the injector stamps them onto the root timeline. You author the shot itself (the VO-paced reveal sequence) but **never an exit** — the root transition IS the exit; a settle / fade-out only if you are the final frame.
+- **Audio** (narration / BGM / SFX) — assembled at the root by the orchestrator. **No `<audio>` element in your composition.**
+- **Design tokens** — palette / fonts / components come from `frame.md`. Don't invent them, and **never lift a word, label, or wordmark out of `frame.md` as your copy** — it is a style spec, not the video's content. On-screen text comes from your frame's `scene` / narrative.
+- **Which motions exist** — named upstream in your block (the shot sequence's motion verbs + `blueprint:`). Implement them; don't invent new ones. You design the **invented visuals** the Scene lines describe (typography / abstract graphics / diagrams / data-viz), but you have **no asset-fetch tool** — never fabricate an image URL or reference a file that isn't the user-supplied `public/<basename>`.
+- **The shared `STORYBOARD.md`** — read your block, never write it. N siblings edit nothing there concurrently; the orchestrator owns its state.
+
+## Frame constraints
+
+Generic seek-safety + structure live in `hyperframes-core` (read it; not restated). These are the **faceless-explainer deltas**, each load-bearing:
+
+- **Caption keep-out — all content in the top ~83%.** A karaoke caption pill owns the bottom ~17% of the canvas. Keep every element (headline, diagram, coined-term card, stats) above `y ≈ 0.83 × height` — compute the pixel cutoff from your canvas (e.g. `≤ 900` on a 1080-tall frame, `≤ 1600` on a 1920-tall portrait). Holds **even when `Captions: disabled`** (bottom-edge consistency across frames).
+- **Fill the content area — especially portrait.** Compose the whole top-83% region; don't float one small cluster mid-frame. Anchor the hero high (~0.2–0.35 × height), flow supporting elements down with rhythm, scale hero type toward full-bleed. (Landscape's region is short, so vertical centering near 0.42 × height is fine.)
+- **Visible text is short motion-graphics copy** — a hero word / coined term / stat / one-word emphasis (`"COMPOUNDING"`, `"2×"`), never a sentence from the narration. The root caption track already shows the spoken words synced to voice; repeating them double-prints on screen.
+- **Build the whole shot — reveal across the full `duration`, never front-load.** Dumping the whole canvas in the first ~25% then holding it is exactly what reads as a PowerPoint slide. Instead reveal each piece — a line, a layer, a node, a stat — **as the `voiceover` reaches it** (on a silent frame, on the beat), sequencing reveals across the shot and especially the back ~50%, with the macro camera move running underneath. **Only EXITS are banned** — a non-final frame unmounts mid-frame, so an exit tween truncates and reads as a glitch (the root transition IS the exit); mid-shot reveals are free and seek-safe. The lone exception is a note marked as a deliberate hold / stillness frame: there, an entrance + a quiet settle is right (a held read beats bad motion).
+- **Implement the shot sequence faithfully — every Scene is a timeline phase.** The Scene lines ARE the build: map each Scene onto a phase of the one timeline, each piece revealing as the `voiceover` reaches it. For each **named motion** in a Scene, open its rule recipe under `RULES_DIR/<id>.md` and reproduce its mechanics — **never name-guess** (a guess loses the signature move). The **`blueprint:` template** (`../hyperframes-animation/blueprints/<id>.md`) gives the overall shape; read it and keep its **signature move** recognizable, then instantiate it with this frame's invented content / timing. `compose` → no template; sequence the shot straight from the Scene lines. Whichever, never front-load the whole sequence at `t=0` — pace the reveals to the voiceover.
+- **Design each element by its `roles`** (the `focal` is the hero): a `foreground subject` is the thing the eye lands on — respect the 83% keep-out, lay text around it, not over it; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible; `supporting` elements (labels, secondary shapes, ambient layers) stay quiet. These are **invented** — you build them in SVG / CSS / type, not from a file. **If the user supplied a real image** named in `roles:`/`focal:`, place it: a `[video]` candidate (`.mp4`) renders as a **muted** `<video class="clip">` (`data-start` / `data-duration` / `data-track-index` per the core clip contract), a **direct child of the frame root** — never nested in another timed element, or the renderer freezes it; an untagged image → `<img>`.
+
+## Workflow
+
+1. **Read** — `hyperframes-core`'s composition contract (the structural law), then `frame.md` (the look) and your `## Frame N` block (the shot sequence + `blueprint:` / `focal:` / `roles:`). **Then read the blueprint template** `../hyperframes-animation/blueprints/<id>.md` (skip if `compose`) for the shot's shape and signature move, and **open the rule recipe `RULES_DIR/<id>.md` for every named motion** in the Scene lines (plus the shared `../hyperframes-animation/examples/<id>.html` when the recipe is unclear): you reproduce these mechanics, not improvise them. Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and `lint` / `validate` / `inspect` can miss the resulting blank sub-composition.
+2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe you just read, the blueprint's signature move kept recognizable. Invent the visual elements the Scene lines describe (the diagram, the hero word, the metaphor), and find a visual idea that reinforces the beat, not a literal restyle of the words.
+3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously — per the core contract.
+4. **Self-check, then finish** — re-read your file against the checklist below and fix in place. Writing the file is your terminal action; you do **not** run the CLI.
+
+## Self-check before finishing (you do NOT run the CLI)
+
+You **can't** meaningfully run `hyperframes lint` / `validate` / `inspect` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them at **Step 6, after assembly** (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back (the rules behind them live in `hyperframes-core`):
+
+- `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
+- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
+- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
+- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
+- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
+- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
+- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
+- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
+- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
+- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
+- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
+- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
+- `font_family_without_font_face` — every font you name has a matching `@font-face` (or `@import`) **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.
+- **Keep-out + no-narration-text** (eyeball, no code) — nothing sits below the 83% cutoff; no narration sentence is rendered as visible text.