WaterrrForever
e0dc255e8a
* fix(capture,audio): three defects found running product-launch-video end to end
Found while running the full product-launch-video workflow twice against a real
site (linear.app) to verify PRs #2880/#2881/#2882. All three are independent of
those PRs.
**Scraped SVGs were unusable as files.** `assetDownloader` wrote an inline
`<svg>`'s `outerHTML` straight to `assets/svgs/*.svg`. An inline SVG inherits its
namespace from the HTML parser, so `outerHTML` omits `xmlns` — valid pasted back
into HTML, but not a standalone document, and `<img src="logo-abc.svg">` renders a
broken-image icon. That is exactly how these assets get consumed. `toStandaloneSvg`
now declares the namespace on the way to disk (plus `xmlns:xlink`, but only when an
`xlink:` attribute is actually used). The filename hash moved to the bytes that
land on disk so it still cannot drift from content.
**`sfx: none` became a cue named "none".** `fetch-sfx` split the storyboard's
`sfx:` list and dropped only empty strings, so the absence marker reached the
engine as a real cue that could not resolve. The absence spellings are part of the
storyboard vocabulary; drop them.
**`bgm_pending` was lost translating neutral meta to product-launch meta.** A
detached Lyria/MusicGen generate leaves `bgm: null, bgm_pending: true` until the
track lands. `toProductLaunchMeta` returned only `{bgm, voices, sfx}`, so "not
ready yet" became indistinguishable from "silent by design" — and because
`fetch-sfx` rewrites `audio_meta.json` from the sidecar, a still-generating bed was
snapshotted away with nothing to signal it. The flag now survives, and `fetch-sfx`
warns when it snapshots a pending bed instead of leaving a silent film that the
storyboard claims has music.
Not included, deliberately: `assemble-index.mjs` rewrites `index.html` wholesale
and so discards the block `transitions.mjs inject` wrote, meaning any Step 6 rework
silently loses transitions. Fixing that means deciding whether assemble preserves an
injected block or inject becomes re-appliable — it touches both scripts and the
Step 5/6 ordering in SKILL.md, so it deserves its own change.
Validation: `node --test skills/product-launch-video/scripts/audio.test.mjs`
(13 pass, 5 new) · `vitest run src/capture` (85 pass, 5 new) · `bun run lint:skills`
· oxlint/oxfmt clean · `tsc --noEmit` clean
* feat(capture): re-add the full-page plate a scroll shot needs, at 1x
`product-launch-video` tells a scroll shot to animate a viewport over a full-page
capture. No such file existed: capture emits 15 viewport-sized scroll-position
tiles, and a plate is not substitutable by tiles — a viewport travelling down one
continuous image is the whole point.
An earlier `full-page.png` was dropped in 62b55171e because 1/8 agents read it and
the contact sheet covered the same ground. That measured it as a *comprehension*
artifact, on an eval where nothing was building scroll shots. The scroll shot is a
different consumer, so this brings the plate back — but not as it was, because two
things have to hold for it to be worth having:
- **Taken last.** After the scroll traversal, so lazy images have loaded and
scroll-triggered reveals have fired. A plate shot on arrival is full of blank
bands, which is a good reason for an agent to look once and never again.
- **Sticky chrome neutralised.** `fullPage` bakes a fixed header in at one
position, freezing a nav across the middle of the plate. The viewport tiles keep
sticky on purpose (natural browsing state); the plate cannot. Positions are
recorded and restored in a `finally`, so the extraction passes that run afterwards
see an unmodified DOM.
**1x, deliberately.** 2x is what you'd want to push in without softening text, but
doubling a long marketing page passes Chrome's 16384px screenshot cap precisely on
the pages that most want a scroll shot (linear.app: 10962 CSS px → 21924 at 2x). At
1x a 1920-wide plate is pixel-exact for a 1920x1080 viewport. A frame that needs
headroom captures its own region at 2x instead. Pages over the cap get no plate
rather than a silently clipped one, and the caller falls back to the tiles.
Validation: `vitest run src/capture` — 90 pass (5 new) · oxlint/oxfmt clean ·
`tsc --noEmit` clean
* docs(product-launch-video): point the scroll shot at the plate, make handoff fields binding
Two follow-ups from the same end-to-end runs, now that #2880 and #2881 have landed and
their sentences exist to edit.
**The scroll shot pointed at an artifact that did not exist.** #2881 said "use a 2x
full-page capture and animate the viewport over it". Neither half held: capture emitted
no full-page image, and 2x on a long marketing page passes Chrome's 16384px screenshot
cap precisely on the pages that most want a scroll shot. Both runs watched the agent go
looking, not find it, and improvise — once by re-capturing 2x strips per section, once by
using the native 1920x1080 tiles full-bleed. This PR's capture commit adds the 1x plate,
so the sentence can now name something real: the plate, its absence on pages too tall to
capture in one piece, the tile fallback, and why pushing in past 1:1 still wants a region
capture of its own.
**A constant field was being read as an absent one.** #2880 asks for x/y, scale, opacity
and direction/speed on every handoff. Across two runs on the same model, `opacity` went
0/12 then 12/12 — when the value never changes, leaving it out is a reasonable reading of
the instruction. But downstream an omission and "there is no handoff here" are the same
thing, so the field set has to be stated as binding even when constant. Same clause added
to the worker's side of the contract.
Validation: `bun run lint:skills`
* fix(capture,audio): close the three contract gaps raised in review
Review on #2892 (Rames, Magi) found the fixes correct inside the changed files but
incomplete at the contract level. All three hold up against source; two of the three
were reachable in production, and the plate one was self-inflicted by this PR.
**The plate guard checked a stale height.** `scrollHeight` was measured before the scroll
traversal and handed to the guard, but the plate is deliberately shot *after* it so lazy
content has loaded — and lazy loading grows the document. The guard's input therefore read
low on exactly the long pages it exists for, letting the check pass and a clipped plate
through, undetectable downstream because the skill only teaches the tile fallback when the
file is *absent*. `captureFullPagePlate` now measures the height itself at call time, and
verifies what Chrome actually produced by reading the PNG's IHDR before writing, since the
capture can trigger another round of loading. Over the cap, nothing is emitted.
**Assembly dropped the flag again.** `bgm_pending` survived into `audio_meta.json` but
`assemble-index.mjs` rebuilt its audio object from three named keys, so at the step that
actually builds the film "not ready yet" still looked like "silent by design" — this PR's
own framing of the defect, one layer further down. The flag rides along now, and a pending
bed with no file raises an anomaly instead of quietly assembling a silent cut against a
storyboard that promises music.
**The sibling adapters had both audio bugs, and there were two of them.** The review named
`faceless-explainer`; `pr-to-video` carries the same file. Its own test asserts the two are
byte-identical ("intentionally identical across the reusing skills"), so fixing one alone
broke that test — which is what caught the second copy. Both now carry the absence-sentinel
filter and the surviving `bgm_pending`, and `faceless-explainer` gets the same five
regression tests.
Also from review (Miga): the sticky-restore in `finally` is wrapped, so a page that broke
mid-capture cannot replace the real error with a cleanup one.
Validation: `vitest run src/capture` — 95 pass (5 new) · product-launch audio 13 pass ·
faceless-explainer audio 10 pass (5 new, incl. the byte-identity contract) ·
`bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean
* fix(capture,audio): meet the two review asks I under-delivered on
Follow-up to 194fb6995. Re-read Magi's review body rather than working from the summary,
and two of the three blockers were addressed in spirit but not to the letter.
**The plate probed before neutralisation, not after.** 194fb6995 moved the measurement off
the caller's stale value and into the function, but took it before forcing fixed/sticky
elements to `static`. The review called this out specifically and is right: dropping those
elements back into flow grows the document, so the probe could still read under the cap on a
page that is over it once neutralised. The probe now runs after neutralisation and before the
shot, inside the same `try` so restoration still happens on the early return. Added the exact
case asked for — initial height under the cap, final height over it — asserting no
screenshot is taken, no file is written, and the page is still handed back unmodified.
**Assembly warned where the review asked it to refuse.** An anomaly in a list is not
enforcement: assemble is re-run on Step 6 rework, long after the audio step's warning
scrolled past, and a warning still lets a silent film out the door over a snapshot whose own
JSON says the bed is generating. `assemble-index.mjs` now dies on `bgm_pending && !bgm`, with
`--allow-pending-bgm` as the deliberate escape for previewing mid-generate. Pinned with three
tests in a new `assemble-index.test.mjs`: refusal writes no index.html, the escape assembles
and says so, and a film that is silent *by design* still assembles untouched — the
distinction the flag exists to make.
Validation: `vitest run src/capture` — 96 pass (6 new) · product-launch audio 13 pass ·
assemble-index 3 pass (new file) · faceless-explainer audio 10 pass ·
`bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean
* fix(audio): carry the bgm_pending gate into the sibling assemblers
The remaining blocker, and one this PR created: the previous commit made all three copies of
the audio adapter *emit* bgm_pending, but only product-launch-video's assembler *reads* it.
So faceless-explainer and pr-to-video would do exactly what this PR set out to stop — parse
an audio_meta.json that says the bed is still generating and assemble the silent film without
a word. Producer fixed in three places, consumer in one, is worse than neither: before this
PR there was no flag to drop.
Both siblings now get the same three changes product-launch-video got — the flag carried
through the audio object, `die` on `bgm_pending && !bgm`, and `--allow-pending-bgm` as the
deliberate escape — plus the same three tests: refusal writes no index.html, the escape
assembles and says so, and a film that is silent *by design* still assembles untouched. That
last one is the one worth having; it proves the flag restored a distinction rather than just
adding a gate.
Applied as three separate patches rather than a file copy: these assemblers have diverged
(pr-to-video validates a bare `<template>` fragment where product-launch takes a `<div>`
root, which its fixture reflects).
`music-to-video` has the fourth copy of this assembler and is deliberately untouched: it has
no audio producer, and its assembler reads `{ voices: [] }` with no bgm path at all, so the
flag can never reach it.
Validation: product-launch / faceless-explainer / pr-to-video assemble-index — 3 pass each ·
product-launch audio 13 pass · faceless-explainer audio 10 pass · `vitest run src/capture`
96 pass · `bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean
30 KiB
name, description
| name | description |
|---|---|
| product-launch-video | Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes. |
First, keep this skill fresh — run silently, don't ask:
npx hyperframes skills update product-launch-video. 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-useto resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run--adoptfirst to register existing assets. See/media-useskill.
figma source: If the source is a figma.com URL, run
/figmafirst — asset export, brand tokens, and components/storyboard reconstruction if needed — then build this workflow from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization,.media/manifest.jsonlprovenance, and brand-tokenvar()binding, so a later brand change can't propagate without a full re-import.
Product Launch to HyperFrames
Use this skill to capture a product, understand its brand, plan a launch video, and build it frame by frame in HyperFrames.
The front door is
/hyperframes. You are the orchestrator. Run each step, verify its gate, and only then continue to the next step. This skill is for a product being marketed, launched, promoted, or revealed, including requests such as "promo for our site" when the purpose is promotional. A site tour / showcase ask stays here too:BRIEF.mdcarries the show-it-as-is intent, and the captured screens become the assets the video features. Any other intent, a bare "make a video", or any uncertainty → read/hyperframesfirst — the intent layer owns every route decision, and a fresh creation arriving here withoutBRIEF.mdgoes through it anyway (Setup's opening rule).
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 gate types and how BRIEF.md's flow/storyboard derive the mode that governs the Step 3/4/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 capture -> capture/; 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
Goal: Enter with a confirmed brief, create the HyperFrames project, and make the brief durable.
The brief is confirmed by the intent layer, not by questions asked here. Opening rule, in order: (1) BRIEF.md exists → read it and ask nothing — the brief is settled, and its flow/storyboard derive the mode (brief contract § 1). (2) No BRIEF.md but the project exists (hyperframes.json / STORYBOARD.md on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. (3) Neither — a fresh creation request that arrived here directly → read /hyperframes and run its intent layer (references/intent-interview.md): it checks recipes and remembered defaults, conducts this route's questions (../hyperframes/references/routes/product-launch-video.md), and hands back the locked brief. Edit requests skip all of this — go do the edit.
Initialize only if hyperframes.json is missing. Name <project> from the brand or domain in kebab-case, such as acme-promo; never use workspace name or timestamp.
npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=product-launch-video — init checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
After init, let <PROJECT_ROOT> be videos/<project> and run every subsequent relative-path command with that directory as its working directory. In the commands below, . means <PROJECT_ROOT>; never write .media, capture, or output files in the caller directory.
Write BRIEF.md immediately after init (never before — init refuses a non-empty directory): the intent layer's locked brief, shape per ../hyperframes-core/references/brief-format.md. Resolve <MEDIA_DIR> as the installed /media-use skill directory. Then record each preference-backed answer with node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md names the subset). If the intent layer adopted a recipe, run node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>; it copies its frame.md into the project (Step 2 is then skipped) and returns the skeletons Step 3 drafts from. A recipe fills answers, not approvals; the review gates still run.
Show sign-in status before proceeding past Setup — run npx hyperframes auth status and relay its output verbatim. It reports whether voice/BGM will use HeyGen or local engines and, when signed out, how to sign in. Note the exit code contract: auth status exits 1 when not signed in (and when the stored credential is rejected) — that non-zero exit is the normal signed-out state, not a command failure, so don't treat it as an error, don't retry it, and don't chain it with &&/set -e in a way that would abort the workflow. Apply one branch:
- Collaborative: wait for the user to sign in or explicitly choose
offline/go. - Autonomous: state the status and continue through the available local engines.
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo .env. Auth ownership and offline fallbacks: /media-use references/setup-providers.md § Providers.
Gate: hyperframes.json and BRIEF.md exist; the preference-backed answers were recorded (brief contract § 2); sign-in status was shown (signed in, or continuing offline).
Step 1: Capture assets
Goal: Collect the source material, brand signals, and usable assets for the video.
Classify the input and choose the path. Explicit URL -> capture it and use the site for narration and assets. Pasted script/brief -> save verbatim as user_script.txt; VO_MODE (verbatim or restructured) comes from BRIEF.md — the intent layer asks it when a script arrives (ask once here only if the brief somehow lacks it). Then resolve capture target: URL in text -> use it; brand name only -> WebSearch, confirm URL in one line, then crawl; no URL/site (or the brief says don't scrape) -> no-capture path.
Run capture with: npx hyperframes capture "<URL>" -o ./capture
For a site tour or show-it-as-is brief, the captured page is the visual source of truth. Use the real screenshot instead of rebuilding the full website in HTML. If the shot needs internal movement, keep the screenshot as the base and overlay real captured assets at measured positions, or rebuild only the one component that moves. For a scroll shot, animate the viewport over capture/screenshots/full-page.png — the 1x plate of the whole document, pixel-exact for a 1920-wide viewport travelling down it. It is absent when the page was too tall to capture in one piece; fall back to the overlapping scroll-position shots in the same directory. Pushing in past 1:1 wants its own 2x capture of that region instead, since the plate has no headroom above 1x. Recreate the whole page only when the user explicitly asks for a stylized interpretation or the capture is unusable.
If GEMINI_API_KEY, GOOGLE_API_KEY, or an OpenRouter key exists, capture auto-captions assets into capture/extracted/asset-descriptions.md. This is not a review gate. Without a vision key, use DOM context and continue.
No-capture path: create capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md, and capture/assets/ by hand. tokens.json should be { "title": "", "description": "", "colors": [], "fonts": [] }; fill title/description from the brief when possible. visible-text.txt contains the full brief or script. asset-descriptions.md should say no assets were captured unless the user gave asset notes.
Gate: capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md, and capture/assets/ exist; you can state the brand in one clear sentence. Treat asset-descriptions.md as the main asset inventory. If it is missing after real capture, stop and report capture incomplete. If capture/BLOCKED.md exists, follow it.
Step 2: Design System
Goal: Choose one shipped frame preset; a script turns it into this video's frame.md + caption skin.
When BRIEF.md names a style_preset — the user picked it by eye from the showcases at the intent layer — use it; the judgment call is yours only when the brief is silent. Then you make the one call — which preset: read ../hyperframes-creative/references/design-spec.md and pick the preset whose look best fits the brand and brief. Then run:
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 the brand tokens in capture/extracted/tokens.json (brand colors mapped onto the preset's color keys by role — ink, canvas, accents — keeping keys/structure/components; 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 to the next step as soon as it exits 0 — no hand-editing of the spec.
tokens.json with no brand colors/fonts (e.g. no capture) → the script keeps the preset's own palette, a complete shippable design. If the brief names brand colors/fonts the capture missed, add them to capture/extracted/tokens.json before running (or use the user's design.md to populate it); 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; the chosen preset was recorded as a preference (--key style_preset --workflow <this workflow>, brief contract § 2).
Step 3: Storyboard and Script
Goal: Turn the brief and captured material into an approved frame-by-frame story 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. Set the frontmatter duration: from the brief's length — a rough expectation; assembly reports where the cut lands against it.
Use story-design.md for story blueprint, hook, persuasion logic, beats, VO_MODE, and asset choices. As a soft guide, consult the role→blueprint menu in ../hyperframes-animation/blueprints-index.md: for each beat, note a candidate blueprint id when one fits. Story 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. Choose each visual frame's asset_candidates from capture/extracted/asset-descriptions.md (the canonical inventory) — don't browse raw capture/assets/. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
After drafting, run the review loop's plan pass — ../hyperframes-core/references/review-loop.md § 1: open the board (don't ask whether to), present the plan as a proposal, and ask the two questions — approve or change, and sketches first (recommended) or skip. Feedback loops through chat or the board's comments file until approved. This is a checkpoint gate (brief contract § 1): in autonomous mode there is no board and nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6.
Gate: STORYBOARD.md exists, every visual frame has asset_candidates, 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.
Choose the narration provider and voice from the user's ask before invoking. Pass the provider selected in Step 0 with --provider <provider> (or set HF_TTS_PROVIDER). 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_DIR>/audio/scripts/heygen-tts.mjs --list (or GET /v3/voices?engine=starfish); Kokoro (offline) via the voice table in <MEDIA_DIR>/audio/references/tts.md (prefixes am_/bm_ male, af_/bf_ female). When the user expressed no preference, fall back to the remembered voice (brief contract § 2) before the pipeline default, and say which one you used; omit --voice only when neither names one. When the user explicitly picked a voice this run, record it (prefs.mjs record --key voice).
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json --provider <provider> --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; music: none turns BGM off. This uses the HeyGen Audio API for retrieval, not generation, and uses 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.
The canonical fully-silent marker: music: none in the STORYBOARD.md top YAML block and no SCRIPT.md. That combination marks the project silent — no narration, no BGM, no SFX. audio.mjs recognizes it and generates nothing (it removes any stale audio_meta.json; an absent audio_meta.json is what assemble treats as silent), so Step 3.1 is a clean skip. Use it when the user asks for a silent / music-free video — don't improvise other spellings.
Gate: audio job has started, or the project is marked silent (music: none + no SCRIPT.md).
Step 4: Frame Visual Design
Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.
Sketch the board first (collaborative only). The moment the plan is approved, run the sketch pass — ../hyperframes-core/references/review-loop.md § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself, mark each built, pause for the one layout question when the board is full, and revise only the sketches named until the board is confirmed. Stand-ins: plain labeled blocks for the captured assets — the real files arrive with Step 5's workers. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from outline to animated at Step 5.
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 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 visual 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 product's content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. State layout and motion inline per Scene (vocabularies in visual-design.md and motion-language.md). Add one video-wide ## Video direction block.
When an element visibly continues across a frame boundary, give both workers the same numerical handoff in STORYBOARD.md: add handoff_out: to the outgoing frame and a matching handoff_in: to the incoming frame. Name the element and its exact x/y position, scale, opacity, and motion direction/speed at the cut — state every field even when it does not change, because a constant is opacity: 1, not an omission. Omit the whole block only for a deliberate clean cut. The goal is simple: parallel workers must not invent two different versions of the same seam.
Do not change story, script, asset choices, asset_candidates, transition_in, or captured source material. Do not write HTML in this step.
Stage named assets after visual design is locked:
node <SKILL_DIR>/scripts/stage-assets.mjs --storyboard ./STORYBOARD.md --hyperframes .
Gate: every visual frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); ## Video direction exists; assets/ contains the named assets. Collaborative: the sketch board was confirmed.
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.
Check the music against the final cut before assembly. A library track can match the requested mood but open on a quiet build that drains the first seconds of a short launch video. Compare the opening with later five-second sections; when a later section has a stronger, musically clean start, trim from there and keep a short fade-in plus a longer fade-out. If frame or narration timing changes, redo this check against the new final duration so the music never ends early or leaves silence at the tail.
Before dispatch, read ../hyperframes-core/references/subagent-dispatch.md. Build the per-frame packets and the worker role payload:
node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"
The builder writes one bounded packet per frame under .hyperframes/frame-packets/ (the frame's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and _role.md (../hyperframes-core/references/frame-worker-core.md + this skill's sub-agents/frame-worker.md, concatenated verbatim — the complete worker role). Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame: its prompt carries _role.md and that frame's packet — paste both in full, or hand the two file paths for the worker to read first (equivalent; the worker starts from exactly those two documents either way) — plus a dispatch context with PROJECT_DIR, frame_id, whether the frame has a confirmed sketch on disk (the worker dresses that layout rather than redrawing it — frame-worker core § When a confirmed sketch exists), canvas size, and caption status + keep-out band if captions are enabled.
Workers read only their packet and frame.md; they never open STORYBOARD.md or the skill documents (the packet inlines what was selected upstream). 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: ../hyperframes-core/references/frame-worker-core.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 (collaborative: the sketch board was confirmed at Step 4), 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 snapshot --at <frame-midpoints-and-each-cut-minus-0.1s-and-plus-0.2s>
snapshot stitches the captured frames into one contact sheet (snapshots/contact-sheet.jpg). Inspect the midpoint frames for layout failures, then compare the two images around every cut. A continuing element must keep the promised position, scale, opacity, and direction; fix any visible pop before rendering.
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.
After checks pass, pause for user review — the review loop's final look (../hyperframes-core/references/review-loop.md § 4): one question, on the Studio that has been open since Step 3 — render now, or what changes? (Autonomous: the one kept question, preview first or render.) 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=product-launch-video --quality high --output renders/video.mp4
Do not rerun lint, check, or snapshot after rendering unless the user asks.
Gate: lint and check passed and the snapshots were inspected 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.
Background scripts: the workflow ships only these scripts 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; stage-assets for copying frame-named assets into assets/; and assemble-index. Everything else is handled by the hyperframes CLI.
The reusable, product-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) |
Gate types, mode derivation from BRIEF.md, field semantics. |
[../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 product-launch 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. |
[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md) |
Step 5: the shared worker contract (packet builder prepends it to the delta). |
[sub-agents/frame-worker.md](sub-agents/frame-worker.md) |
Step 5: the workflow's frame-worker delta. |
[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md) |
Step 5: dispatch sub-agents safely. |