launch-video

Build a release video for a Spool version. The output is a 1080p MP4 plus a poster JPG, intended for X / Twitter. Runtime scales with feature count: 20–40s, 3–8 feature beats + brand outro, optionally a stylised capstone scene before the outro for releases whose payoff is a tangible outcome the captured clips can't show on their own.

## Mental model

A release video for Spool has two halves running in parallel on screen:

1. **Left third** — a text panel that introduces the current scene (kicker `01 / 04 — POLISH`, a 2-line headline, a 1–2 line sub).
2. **Right two-thirds** — the real Spool app, recorded as a native macOS window. The camera (CSS `transform-origin + scale` on the `.window`) zooms into the specific UI region for each feature.

Focus on the active feature is carried by one of two devices:
- **Amber annotation rectangles** inside `.window` that track the camera — good for "look at this strip" callouts. Cheap and precise when the feature is a single bounded region.
- **Spotlight mask** — an SVG overlay that dims everything except 1–2 transparent "holes" punched through. Softer falloff means small coordinate drift disappears into the dim instead of reading as a misaligned outline. Dual holes let you keep the preview bright while a control on the right side lights up in sync with a click. See `references/spotlight.md`.

This is **not** a PPT: text panel and demo coexist continuously, with hard match-cuts between feature clips. Don't reintroduce slide-style title cards.

## Required preparation

Read these references before you start composing. They are not optional — each captures hard-won decisions from prior releases.

- `references/composition.md` — the proven layout, dimensions, drop-shadow recipe, panel + annotation timing patterns, beat-sync approach, the panel-leads-spotlight rhythm rule, the optional capstone scene
- `references/capture.md` — how to record native macOS windows of the Electron app, helper functions to use, per-release seed authoring, the feature-flag-at-build-time gotcha
- `references/cursor-overlay.md` — synthetic cursor that tracks Playwright mouse + visualises clicks. Solves "Playwright doesn't move the OS cursor and screencapture only films pixels"; required whenever a scene's whole point is a click
- `references/spotlight.md` — SVG-mask focus technique; single-hole for one target, dual-hole for cause-effect (preview always bright + active control bright); the payoff pattern (collapse secondary to redirect the eye)
- `references/pitfalls.md` — things we tried that look bad in motion (decorative chrome, smooth camera drifts, pre-clip resets, clip-boundary gaps, etc.) and why
- `references/poster.md` — the `tpad clone` trick so Twitter's auto-thumbnail grabs the hero frame instead of a leading black frame

## End-to-end checklist

1. **Inventory the features to demo.** A release video shows 3–4 features max. Pick the ones with the most visible UI change.
2. **Author a per-release seed.** Write a `ProjectSeed[]` array (see `packages/app/e2e/helpers/demo-fixtures.ts` for the type). Titles should be English-only and **must not reference real user sessions** — invent plausible session titles relevant to the release theme.
3. **Write an ad-hoc capture spec.** A Playwright spec under `packages/app/e2e/` (not committed) that:
   - Calls `launchDemoApp(seed)` + `setDemoWindowBounds(ctx, 1080, 740)`
   - Calls `installCursorOverlay(ctx.window)` (from `helpers/cursor-overlay.ts`) before any clip is recorded so the synthetic cursor is in frame from t=0
   - Records one `.mov` per feature via `recordNativeWindow()` from `helpers/native-window-capture.ts`
   - Uses `cursorClick(window, selector, opts)` / `cursorTo(...)` / `cursorPark(x, y)` from the same helper instead of bare `.click()` so the cursor's path is visibly filmed
   - Outputs to `videos/spool-vX.Y.Z/assets/live/` (gitignored)
   - If your release gates a feature behind a Vite flag, build the app with `VITE_FEATURE_<NAME>=1 pnpm --filter @spool/app run build:electron` *before* running the spec — `import.meta.env.VITE_FEATURE_<NAME>` is inlined at build time, not read at runtime
   - Bump `--global-timeout` if pacing is relaxed: Playwright's default 300s isn't enough for 7-beat spec runs (~50s of `screencapture -V` plus warmup)
4. **Copy `videos/launch-template/` to `videos/spool-vX.Y.Z/`.**
5. **Customise the composition** (`index.html`):
   - Update `<video>` `data-start`, `data-duration`, `src` per clip. Verify each pair satisfies `prev.data_start + prev.data_duration ≥ next.data_start + 0.10` — gaps where neither clip is playing render as a dark frame and read as a full-screen flash (see `pitfalls.md` #11)
   - Author one text panel per scene (kicker + headline + sub)
   - **Measure focus-region coords fresh** from your raw `.mov` frames — last release's coords are wrong for this release
   - Time the panel `~0.3–0.4s ahead of the spotlight retarget` so the headline anchors before the action starts (see `composition.md` on panel-leads-spotlight)
   - Update the brand-mark version + outro version strings
6. **Drop in BGM** at `assets/bgm.mp3`. Identify strong beats with `ffmpeg silencedetect` (for tracks with clear silences) OR `aubiotrack` (more reliable for steady-state atmospheric pieces); align scene cuts or camera punches to them. If your video needs to be longer than the source BGM, stretch with `atempo` — 0.85 is the comfortable floor (subtle pitch drop, no audible quality loss), 0.79 still acceptable, below 0.75 starts to degrade. Add a 0.6–0.8s `afade=t=out` tail so the music decays into the lockup instead of cutting off.
7. **Iterate with drafts.**
   ```
   cd videos/spool-vX.Y.Z
   npm run check     # lint + validate + inspect
   npm run render -- --quality draft --output renders/draft.mp4
   ```
   Pull frames at scene boundaries to verify before re-rendering.
8. **Render standard quality.**
   ```
   npm run render -- --quality standard --output renders/spool-vX.Y.Z-raw.mp4
   ```
9. *