freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/skills/product-launch-video/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: product-launch-video
+description: "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 — confirm with the user before running:** `this pack is bundled offline and is not updated at runtime 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-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.
+
+> **figma source**: If the source is a figma.com URL, run `/figma` first — 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.jsonl` provenance, and brand-token `var()` 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.md` carries 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 `/hyperframes` first — the intent layer owns every route decision, and a fresh creation arriving here without `BRIEF.md` goes 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/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.
+
+Create the project directory and its composition file directly; this pack needs no scaffolding step.
+
+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/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.
+
+This pack has no hosted account, so voice and music come from a provider the user configured or are omitted.
+
+- **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.
+
+This pack cannot capture a website, so the composition is authored from supplied media or local files.
+post-navigation budget unless the caller owns a smaller deadline; then pass a positive
+`--capture-budget <milliseconds>` that leaves time for downstream work. `--timeout` controls page
+navigation only. Use `--skip-vision` only when optional image captioning is intentionally disabled.
+
+Inspect the command result and output directory immediately. A non-zero exit, JSON `ok: false`, or
+`capture/BLOCKED.md` is a **hard stop** for the capture path: report the recorded reason and do not
+consume partial screenshots, DOM, tokens, or assets. Do not manufacture a synthetic no-capture
+fallback after a failed URL capture. Continue through the no-capture path only when the original
+brief supplied the source material, or when the user explicitly switches to a provided screenshot
+or brief after the failure.
+
+Warnings such as `very little text content` together with an empty asset catalog are not proof of a
+usable page. For a site tour or show-it-as-is brief, require trustworthy captured structure or a
+provided screenshot; if neither exists, stop. Do not invent or rebuild the page merely because the
+capture is unusable.
+
+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; an unusable capture alone is not authorization.
+
+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 JSON reported `ok: true`; `capture/BLOCKED.md` does not exist;
+`capture/extracted/tokens.json`, `capture/extracted/visible-text.txt`,
+`capture/extracted/asset-descriptions.md`, and `capture/assets/` exist; and 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. Warnings about a degraded optional phase are
+acceptable only when this structural gate still passes.
+
+---
+
+## 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:
+
+```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 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, source-traceable visuals), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes/references/storyboard-format.md`, and `../hyperframes/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/references/review-loop.md` § 1: present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback arrives as a chat reply; loop until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is 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 storyboard sheet first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself as a cell of `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3), mark each `built`, pause for the one layout question when every frame is `built`, and revise only the sketches named until the sheet 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.
+
+This plugin ships no hosted look registry, so the local materials this skill carries are the catalogue.
+
+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 sheet 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/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/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/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 sheet 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`
+
+`freecodego_design_lint`
+
+`freecodego_design_lint`
+
+`freecodego_design_snapshot`
+
+`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/references/review-loop.md` § 4): one question, on the final Studio preview — 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: `freecodego_design_preview`
+
+Render only after user approval (autonomous mode: after the preview-or-render question):
+
+`freecodego_design_render`
+
+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/references/brief-contract.md](../hyperframes/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, source-traceable visuals. |
+| `[../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/references/storyboard-format.md](../hyperframes/references/storyboard-format.md)`                                                          | Step 3: write `STORYBOARD.md`.                                                                           |
+| `[../hyperframes/references/script-format.md](../hyperframes/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/references/frame-worker-core.md](../hyperframes/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/references/subagent-dispatch.md](../hyperframes/references/subagent-dispatch.md)`                                                          | Step 5: dispatch sub-agents safely.                                                                      |

package/dist/assets/design/skills/product-launch-video/references/cut-catalog.md

@@ -0,0 +1,220 @@
+# 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. (Learned 2026-06-10: the until-now inverse zooms shipped at 20px and read mushy; 10px keeps letterforms readable mid-cut.) |
+| 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
+
+Shipped examples: `boring → until-now` and `B3 → "That changes today."` (sfx-music-launch);
+seams 3/4 in editorial-paper (`follow-up → thinking`, `thinking → compose UI`).
+
+---
+
+## 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.
+
+Shipped example: `until-now.html` B1→B2→B3 (sfx-music-launch).
+
+---
+
+## 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                           |