diff --git a/.cursor/rules/video-playwright.mdc b/.cursor/rules/video-playwright.mdc
new file mode 100644
index 0000000..5f8eadc
--- /dev/null
+++ b/.cursor/rules/video-playwright.mdc
@@ -0,0 +1,55 @@
+---
+description: Video recording uses the isolated video/ Playwright package — never ad-hoc installs
+alwaysApply: true
+---
+
+# Short-form videos & Playwright
+
+Exploration videos (9:16 vertical) are recorded by the **isolated** `website/video/` package.
+Playwright is intentionally **not** in the root `package.json` (CI stays lean).
+
+Chromium is **shared with the OG pipeline** — if `npm run og:check` passes, video recording
+can use the same browser cache.
+
+## One-time human setup (Holger's machine only)
+
+From `feelyourprotocol/website/`:
+
+```bash
+npm run og:setup       # if not done yet — downloads Chromium (~once per machine)
+npm run video:setup    # npm install in video/ only
+npm run video:check    # should print: OK: Playwright Chromium is installed...
+```
+
+**Holger has already run og:setup.** Do not run setup again unless he explicitly asks.
+
+`video/` CLIs reuse `og/` bootstrap — redirect Cursor's sandbox `PLAYWRIGHT_BROWSERS_PATH`
+to the developer's real browser cache. Use `required_permissions: ["all"]` and **never**
+run `video:setup` / `playwright install` as the first fix.
+
+## Agent rules (mandatory)
+
+### NEVER do these
+
+- `npm run video:setup`, `npm run og:setup`, or any `playwright install`
+- Ad-hoc `npx playwright install` or sandbox browser downloads
+- Retry setup when record fails — that is almost never the fix
+
+### ALWAYS do these
+
+1. Run video commands with **`required_permissions: ["all"]`**
+2. Use npm scripts from `website/`:
+   - `npm run video:preflight`
+   - `npm run video:record -- <project-id>`
+3. Optional fast check: `npm run video:preflight` with `required_permissions: ["all"]`
+   - `status: ready` → proceed
+   - `status: needs_agent_permissions` → re-run with `required_permissions: ["all"]`
+   - `status: needs_human_setup` → ask user to run `npm run og:check` locally
+
+### When record fails
+
+1. Permission errors → re-run with `required_permissions: ["all"]`
+2. Still fails → ask user for `npm run og:check` output; do **not** run setup
+3. Selector timeout / 404 → fix app or playbook, not Playwright setup
+
+See `video/README.md` and `docs/contributing/video-pipeline.md`.
diff --git a/.gitignore b/.gitignore
index 813a59b..2749606 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,4 +35,10 @@ roadmap/.vitepress/cache
 SERVER_NOTES.md
 
 # Dist
-dist/
\ No newline at end of file
+dist/
+
+# Isolated Playwright packages (local node_modules + artifacts)
+og/node_modules
+og/.chromium-ready.json
+video/node_modules
+video/projects/*/output/
\ No newline at end of file
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index ca484fd..99abc55 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -101,6 +101,8 @@ export default defineConfig({
           { text: 'Styling & Design', link: '/contributing/styling' },
           { text: 'Code Conventions', link: '/contributing/code-conventions' },
           { text: 'Third-Party Libraries', link: '/contributing/third-party-libraries' },
+          { text: 'Video Pipeline', link: '/contributing/video-pipeline' },
+          { text: 'Authoring a Video Short', link: '/contributing/video-authoring' },
         ],
       },
       {
diff --git a/docs/contributing/video-authoring.md b/docs/contributing/video-authoring.md
new file mode 100644
index 0000000..b7e6ccc
--- /dev/null
+++ b/docs/contributing/video-authoring.md
@@ -0,0 +1,386 @@
+# Authoring a video short
+
+How to plan, write, and record a Feel Your Protocol vertical short (~45–60 s) from a
+live exploration.
+
+Operational commands and file layout: [Video pipeline](/contributing/video-pipeline).
+Reference project: `video/projects/eip-8024/`.
+
+---
+
+## Goals
+
+Each short should:
+
+1. Show **real** exploration UI (not mockups).
+2. Use the **video overlay language** (black bars, Bebas Neue / Barlow Condensed) — not site chrome.
+3. Guide the viewer's eye with layered overlays without overcrowding the frame.
+4. Start with a **title-card thumbnail** (frame 0 after trim).
+
+Rendering lives in `src/video/`; copy and timing live in `video/projects/<id>/`.
+Run `npm run website:build` before recording whenever overlay components change.
+
+---
+
+## Workflow overview
+
+```
+Plan story arc → content.json (overlays, annotations, highlights)
+              → zones.json (focus areas)
+              → playbook.json (beats + structure)
+              → npm run video:generate   ← final *-final.mp4 (video + voice)
+              → npm run video:record --no-voice   ← silent .webm only
+              → verify frame 0 thumbnail + audio sync
+```
+
+Silent-only path (no voice): omit `narration.json` / `voice/` and set manual `cue`/`wait` in `playbook.json`.
+See [Voice-over pipeline](/contributing/video-voice).
+
+---
+
+## 1. Plan the story arc
+
+Break the video into **beats** — one playbook step each. Each beat can include:
+
+| Phase | Playbook | Purpose |
+|-------|----------|---------|
+| Guide | `annotate` | Pointer on live UI (parallel through the beat) |
+| Cue | `overlay` + `cue` | Story text the viewer reads before action |
+| Reveal | `selectExample`, `step`, `scroll`, `expandCompanion` | Exploration action |
+| Hold | `wait` | Pause after action so the result sinks in |
+
+Typical arc for an opcode demo:
+
+1. **Title** — hook and topic
+2. **Context** — hardfork / problem statement
+3. **Setup** — select example, grow state (steps)
+4. **Climax** — the one opcode that matters (slow step + highlights)
+5. **Extra** — companion panel, calculator, etc. (optional)
+6. **Recap** — tie back to the takeaway (text-only on current state)
+7. **Outro** — closing line + CTAs
+
+Use `npm run video:storyboard -- <project-id>` to preview timing before recording.
+
+---
+
+## 2. Project files
+
+Create `video/projects/<exploration-id>/`:
+
+| File | Contents |
+|------|----------|
+| `content.json` | `overlays`, `annotations`, `highlightSets` |
+| `playbook.json` | Ordered beats with timing and actions |
+| `zones.json` | Focus-area selectors for `focus` and annotation targets |
+| `output/` | Recorded `.webm` (gitignored) |
+
+Add the exploration to `video/src/explorationRegistry.ts` if not already listed.
+
+### `zones.json` — focus areas + YouTube Shorts safe zone
+
+`focusAreas` / `placements` drive playbook `focus` scrolling. Add **`safeZone`** (540×960 px) so readable content clears Shorts platform chrome:
+
+| Edge | Default | Notes |
+|------|---------|-------|
+| top | 56px | Username / top controls (text sits lower inside black bars) |
+| bottom | 120px | Like / comment / caption row |
+| left | 32px | Edge crop — e.g. keep “3 NEW OPCODES” fully visible |
+| right | 48px | Right-side action column |
+
+Black overlay bars stay **edge-to-edge**; only the **text inside** is inset (same horizontal safe zone as exploration UI). CSS applies `--video-safe-left` / `--video-safe-right` to `.video-banner__line`, punch lines, and title/outro band content — not as outer margin on the black box.
+
+Vertical rhythm inside top/bottom ribbons uses `--video-ribbon-clear-top` (Shorts chrome clearance, ~60% of `--video-safe-top`), `--video-ribbon-pad-top`, and `--video-ribbon-pad-bottom` (top still larger than bottom). Tune in `src/video/video.css` if a project’s banner feels cramped.
+
+---
+
+## 3. Story overlays (`content.json` → `overlays`)
+
+Story overlays carry the narrator text.
+
+| Type | Use |
+|------|-----|
+| `title-card` | Opening — full band layout (see [Title and outro cards](#title-and-outro-cards)) |
+| `outro-card` | Closing + CTAs |
+| `punch` | Single headline + optional subline |
+| `split` | Two staggered lines |
+| `list-flash` | Headline + bullet list |
+
+In the playbook, pair overlays with **`placement: "top-banner"`** and a **`focus`** key
+so the exploration panel stays visible below the banner.
+
+**Pattern:**
+
+```json
+{
+  "beat": "stack-grow",
+  "overlay": "stack-cue",
+  "placement": "top-banner",
+  "focus": "stack",
+  "cue": 3000,
+  "step": { "count": 9, "interval": 360 },
+  "wait": 1600
+}
+```
+
+Show overlay → `cue` ms → hide → run actions → `wait` ms.
+
+---
+
+## 4. UI annotations (`content.json` → `annotations`)
+
+Annotations are black callouts with a ring on a UI target. They answer: *where should I look?*
+
+```json
+"annotations": {
+  "guide-stack": {
+    "target": "stack",
+    "label": "Live stack",
+    "hint": "Watch depth grow",
+    "side": "top"
+  }
+}
+```
+
+In the playbook: `"annotate": "guide-stack"`. The annotation **stays visible** while the
+beat runs — including after the story overlay hides and steps begin — whenever the banner
+alone does not point at the action area. If a **top-banner story overlay** covers the
+annotation target, the callout is suppressed automatically (avoids collisions like
+“Example presets” over “3 NEW OPCODES”).
+
+Targets are keys from `zones.json` `focusAreas`, or built-in aliases:
+
+| Target key | Resolves to |
+|------------|-------------|
+| `disassembly-active` | `[data-disassembly-active="true"]` |
+| `stack-top` | `[data-stack-depth="1"]` |
+| `stack-depth-{n}` | `[data-stack-depth="{n}"]` |
+
+Explorations used in videos need stable `data-testid` / `data-stack-depth` attributes on
+the elements you annotate (see `BytecodeStepperEC` for the EIP-8024 pattern).
+
+---
+
+## 5. Climax highlights (`content.json` → `highlightSets`)
+
+Use a third layer for the **peak moment** — translucent yellow **area boxes** over the
+exact text cells (opcode mnemonic, stack value). No labels, no full-row width, no site chrome.
+
+Target the **text cell**, not the full row:
+
+| Target key | Highlights |
+|------------|------------|
+| `disassembly-active-opcode` | Opcode text on the active PC row (windup) |
+| `disassembly-dupn` | `DUPN …` mnemonic row (payoff — PC may have moved on) |
+| `stack-top-value` | `[0x…]` on stack depth 1 |
+| `stack-depth-{n}-value` | Value cell at depth *n* |
+
+Requires `data-disassembly-opcode`, `data-stack-value` on exploration widgets (see
+`BytecodeStepperEC`).
+
+Define sets in `content.json`:
+
+```json
+"highlightSets": {
+  "dupn-windup": {
+    "marks": [
+      { "target": "disassembly-active-opcode", "padX": 12, "padY": 10 },
+      { "target": "stack-depth-17-value", "padX": 12, "padY": 10 }
+    ]
+  },
+  "dupn-payoff": {
+    "marks": [
+      { "target": "disassembly-dupn", "padX": 14, "padY": 12 },
+      { "target": "stack-top-value", "padX": 14, "padY": 12 }
+    ]
+  }
+}
+```
+
+Wire timing in the playbook `step` action:
+
+```json
+"step": {
+  "count": 9,
+  "interval": 380,
+  "climaxFrom": 9,
+  "climaxInterval": 1050,
+  "climaxPauseMs": 550,
+  "highlightSet": "dupn-windup",
+  "highlightAfterStep": 9,
+  "highlightSetAfter": "dupn-payoff",
+  "holdAfterClimaxMs": 1500
+}
+```
+
+| Field | Purpose |
+|-------|---------|
+| `climaxFrom` | 1-based step index to enter slow motion |
+| `climaxInterval` | Step delay during climax (ms) |
+| `climaxPauseMs` | Pause before the first climax step |
+| `highlightSet` | Highlights shown when climax starts |
+| `highlightAfterStep` | Step number after which to switch sets |
+| `highlightSetAfter` | Payoff highlight set |
+| `holdAfterClimaxMs` | Extra hold after payoff highlights |
+
+---
+
+## 6. Pacing and cue times
+
+Allocate enough read time for overlay density:
+
+| Overlay density | Recommended `cue` |
+|-----------------|-------------------|
+| Headline + subline (`punch`, `split`) | 3000–3400 ms |
+| Headline + list (`list-flash`, 3+ items) | 4000–4200 ms |
+| Title / outro band cards | 4500–5000 ms |
+| Text-only recap (no actions) | 4000+ ms (`wait` only) |
+
+Step intervals: ~360–400 ms for routine steps; ~1000 ms+ for the climax step.
+
+Example timings from `eip-8024`:
+
+| Beat | Overlay | Timing |
+|------|---------|--------|
+| hook | title-card | `wait` 4500 ms |
+| context | glamsterdam | `cue` 3400 ms |
+| opcodes | three-opcodes | `cue` 4200 ms, `wait` 1200 ms |
+| stack-grow | stack-cue | `cue` 3000 ms, `wait` 1600 ms |
+| dupn-hit | dupn-cue | `cue` 3000 ms + climax step |
+| calculator | calculator-tease | `cue` 2800 ms, `wait` 2400 ms |
+| recap | old-limit-cue | `wait` 4200 ms (no actions) |
+| outro | outro-card | `wait` 5000 ms |
+
+Storyboard validation warns when `cue` is missing on overlay+action beats or when ids
+do not resolve in `content.json` / `zones.json`.
+
+---
+
+## 7. Title and outro cards
+
+Full-screen cards use **`VideoBandShell`**:
+
+- Middle **~3/5** — black band with hero type (title, subtitle, hook / closing, CTAs).
+- Top and bottom **~1/5** — live exploration peeking through.
+
+| Card | Peek role |
+|------|-----------|
+| Title | Show that a live demo runs underneath |
+| Outro | Keep exploration visible behind CTAs |
+
+Outro CTAs support `variant: "secondary"` (smaller, e.g. Forkcast) and `"primary"`
+(larger, e.g. FYP). Use `"READ ABOUT THE EIP"` for Forkcast, not generic "READ MORE".
+
+CSS: `html.fyp-video-capture` locks hero font sizes; `html.fyp-video-band-active` during band cards.
+
+---
+
+## 8. Recap and example switches
+
+**Recap beats** should stay on the current exploration state — overlay text only, no
+`selectExample` or `step`. Point `focus` at the result the viewer just watched (e.g. stack).
+
+```json
+{
+  "beat": "recap",
+  "overlay": "old-limit-cue",
+  "annotate": "guide-stack",
+  "focus": "stack",
+  "wait": 4200
+}
+```
+
+Write recap copy that references what already happened ("You just copied depth 17"), not
+a new demo.
+
+Switch examples mid-video only when the overlay **introduces** a new scenario and the
+reset is intentional. Pick an example that matches the overlay message (e.g. do not use
+`invalid-dupn` to explain the historical DUP depth-16 limit — that example shows a
+shallow-stack revert, a different concept).
+
+---
+
+## 9. Record and verify
+
+```bash
+npm run website:build
+npm run video:record -- <project-id> --preview   # 540×960 — fast iteration
+npm run video:generate -- <project-id>           # 1080×1920 *-final.mp4 (2× upscale on mux)
+```
+
+All captures use a **540×960 Playwright viewport** — the layout reference. Preview and
+full-res differ only at mux: `video:generate` upscales 2× to 1080×1920 (lanczos). Composition
+is identical; do not hand-upscale a preview file.
+
+After recording:
+
+1. Check the trim log — frame 0 should be the title band (valid stats: dark pixel ratio
+   ~0.8, mean luminance ~40 in the center crop).
+2. Scrub the `.webm` at **0:00** (thumbnail), the climax timestamp, and the outro.
+3. Confirm overlays, annotations, and highlights appear as storyboarded.
+
+The recorder hides the exploration until the title card is ready, preloads display fonts,
+and post-trims lead-in with ffmpeg. Requires `ffmpeg` on PATH.
+
+---
+
+## Troubleshooting
+
+| If you see… | Check… |
+|-------------|--------|
+| Missing overlays / annotations in output | Run `npm run website:build` before record |
+| Gray letterboxing | Playwright `recordVideo.size` matches viewport dimensions |
+| Frame 0 shows exploration UI | Trim log; title-band detection needs black center band |
+| Small fallback font on thumbnail | Font preload (`display=block`) and capture CSS |
+| Top banner covers example selector | Banner max-height CSS; `focus` uses `block: 'start'` scroll |
+| Climax highlights / slow motion absent | All climax fields present on `step` in playbook JSON |
+| UI resets without explanation | Remove mid-video `selectExample`; use text-only recap |
+| Banner overlaps during focus | `zones.json` scroll margins; `--video-top-banner-max-h` |
+
+---
+
+## Guidelines
+
+- Keep **three layers separate**: story overlays, annotations, climax highlights.
+- Use **area highlights** on text cells (`*-opcode`, `*-value`) — not full rows.
+- Give **dense overlays ≥ 3 s** cue time; run storyboard before recording.
+- Make **frame 0** the title card; verify after every record.
+- Put **`data-testid`** on controls the playbook clicks.
+
+---
+
+## Reference example: EIP-8024
+
+| ~Time | Beat | Content |
+|-------|------|---------|
+| 0:00 | title-card | EIP-8024, Glamsterdam, opcodes, stack-too-deep hook |
+| 0:08 | glamsterdam → opcodes | Hardfork; three opcodes; select DUPN |
+| 0:14 | stack-grow | 17 pushes — stack grows |
+| 0:22 | dupn-hit | DUPN copies depth 17 — climax with markers + slow step |
+| 0:34 | calculator | Companion / magic-byte calculator |
+| 0:39 | recap | Classic DUP depth 16 vs depth 17 just demonstrated |
+| 0:44 | outro | Closing + Forkcast + FYP CTAs |
+
+Files: `video/projects/eip-8024/{content,playbook,zones}.json`.
+
+---
+
+## Checklist
+
+- [ ] Story arc defined in beats
+- [ ] `zones.json` covers every `focus` and annotation target
+- [ ] Dense overlays have adequate `cue` (3000–4200 ms); storyboard reviewed
+- [ ] Annotations on beats with UI action after overlay hides
+- [ ] Climax beat has `highlightSets` + climax timing (if applicable)
+- [ ] Recap beats are text-only on current state; no unexplained example switches
+- [ ] First step is `title-card`
+- [ ] `npm run website:build` before record
+- [ ] Frame 0 thumbnail verified after record
+
+---
+
+## Related
+
+- [Video pipeline](/contributing/video-pipeline) — architecture, overlay types, selectors
+- [Voice-over pipeline](/contributing/video-voice) — ElevenLabs narration, timing, mux
+- [Architecture — Video pipeline](/guide/architecture#video-pipeline-short-form)
+- `video/README.md` — CLI and Playwright selectors
diff --git a/docs/contributing/video-pipeline.md b/docs/contributing/video-pipeline.md
new file mode 100644
index 0000000..efff84e
--- /dev/null
+++ b/docs/contributing/video-pipeline.md
@@ -0,0 +1,256 @@
+# Video pipeline
+
+Short-form vertical videos (YouTube Shorts, Instagram Reels, X) that educate about
+EIPs using live Feel Your Protocol explorations.
+
+## Architecture
+
+Two layers stay separate:
+
+1. **Website (`src/video/`)** — overlay rendering and video-mode chrome stripping.
+   Activated with `?fyp-video=1`. Does not contain video copy or playbooks.
+2. **Video package (`video/`)** — `content.json`, `playbook.json`, Playwright recording CLI.
+   Mirrors the isolated `og/` package pattern.
+
+```
+website:build → static server → Playwright recordVideo
+                     ↑
+              ?fyp-video=1 + injected __FYP_VIDEO_CONFIG__
+```
+
+## URL parameters
+
+| Param | Scope | Description |
+|-------|-------|-------------|
+| `fyp-video=1` | Any route | Video capture mode — hides header, footer, roadmap banner |
+| `example=<key>` | Explorations | Pre-selects an example preset on load |
+
+Example deep link:
+
+```
+/eip-8024-stack-opcodes-dupn-swapn-exchange?fyp-video=1&example=swapn
+```
+
+The `example` param works for **all** explorations:
+
+- E-Component explorations (`BytecodeStepperEC`, `PrecompileInterfaceEC`) via shared init logic
+- Custom explorations (`eip-7594`, `eip-7928`) via `resolveInitialExample()` and `useExplorationExampleQuery()`
+
+Invalid keys fall back to each exploration's default example.
+
+For precompile explorations that also support field-level share URLs (`?b=`, `?hash=`, …),
+`?example=` takes precedence when present.
+
+## Overlay system
+
+Overlays use a **separate visual language** from the main site: black bars, Bebas Neue /
+Barlow Condensed, no rounded corners, topic color as accent only.
+
+Components in `src/video/`:
+
+| File | Role |
+|------|------|
+| `VideoShell.vue` | Overlay layer + `window.__FYP_VIDEO__` bridge |
+| `VideoOverlay.vue` | Routes to type-specific overlay components |
+| `overlays/VideoTitleCard.vue` | Full-screen movie title |
+| `overlays/VideoSplitOverlay.vue` | Staggered split read flow |
+| `video.css` | Capture-only typography and animations |
+
+Overlay types in `content.json`:
+
+| Type | Use |
+|------|-----|
+| `title-card` | Full-screen opening (black, movie poster) |
+| `outro-card` | Full-screen closing |
+| `punch` | Massive single-line highlight bar |
+| `split` | Staggered black bars (upper-left → lower-right) |
+| `list-flash` | Bold bullet list |
+
+Copy is injected via `window.__FYP_VIDEO_CONFIG__` before navigation.
+
+Full-screen **title** and **outro** cards use `VideoBandShell`: middle ~3/5 black hero band,
+top/bottom ~1/5 peek zones show live exploration. See
+[Authoring a video short](/contributing/video-authoring#title-and-outro-cards).
+
+### UI annotations (`content.json` → `annotations`)
+
+Parallel **guide callouts** point at exploration regions while story text may hide:
+
+```json
+"annotations": {
+  "guide-stack": {
+    "target": "stack",
+    "label": "Live stack",
+    "hint": "Watch depth grow",
+    "side": "top"
+  }
+}
+```
+
+Reference playbook step: `"annotate": "guide-stack"`. Targets use `zones.json` focus area keys
+or built-in aliases (`disassembly-active-opcode`, `disassembly-dupn`, `stack-top-value`, …).
+Callouts are **auto-suppressed** when a top-banner overlay covers the target — see
+[Authoring § annotations](/contributing/video-authoring#4-ui-annotations-contentjson--annotations).
+
+### Climax highlights (`content.json` → `highlightSets`)
+
+Third overlay layer — translucent yellow **area boxes** over text cells during peak
+moments (opcode mnemonic, stack value — not full rows). Playbook climax fields on `step`:
+
+| Field | Purpose |
+|-------|---------|
+| `climaxFrom` | 1-based step index to enter slow motion |
+| `climaxInterval` | Step delay during climax (ms) |
+| `climaxPauseMs` | Pause before first climax step |
+| `highlightSet` | Highlight set id before climax step |
+| `highlightAfterStep` | Switch highlights after this step completes |
+| `highlightSetAfter` | Payoff highlight set id |
+| `holdAfterClimaxMs` | Extra hold after payoff |
+
+See [Authoring a video short](/contributing/video-authoring#climax-highlights-content-json-highlightsets).
+
+## Story beats (cue → reveal)
+
+Each playbook step can tell a **story beat** synchronized with the exploration:
+
+| Field | Purpose |
+|-------|---------|
+| `beat` | Label for storyboard / validation |
+| `overlay` | Text the viewer reads **before** the action |
+| `annotate` | UI guide callout id — **stays visible** while story overlay hides and actions run |
+| `placement` | `top-banner` or `bottom-banner` — keeps the focus area clear |
+| `focus` | UI region to keep visible (see `zones.json`) |
+| `cue` | Read time (ms) — overlay stays up, then hides before actions |
+| `wait` | Hold time (ms) after actions — let the viewer absorb |
+
+**Pattern:** show overlay → `cue` → hide → step / select example → `wait`
+
+Preview the narrative timeline:
+
+```bash
+npm run video:storyboard -- eip-8024
+npm run video:record -- eip-8024 --dry-run   # storyboard + validation
+```
+
+### Safe zones (`zones.json`)
+
+Per-project map of exploration focus areas and overlay placements (540×960 reference).
+Black ribbon backgrounds stay edge-to-edge; text is inset horizontally and vertically via
+`--video-safe-*` and `--video-ribbon-*` CSS vars — details in
+[Authoring § safe zone](/contributing/video-authoring#zonesjson--focus-areas--youtube-shorts-safe-zone).
+Author overlays in `top-banner` so stack, disassembly, or companion stay visible below.
+
+## Playbook format
+
+Each project lives in `video/projects/<exploration-id>/`:
+
+| File | Purpose |
+|------|---------|
+| `content.json` | Overlay copy, annotations, highlight sets |
+| `playbook.json` | Story beats: `overlay`, `cue`, `focus`, `selectExample`, `step`, … |
+| `zones.json` | Focus-area selectors + banner placement metadata |
+| `output/` | Recorded `.webm` (gitignored) |
+
+Example beat — read, then step with stack visible:
+
+```json
+{
+  "beat": "stack-grow",
+  "overlay": "stack-cue",
+  "placement": "top-banner",
+  "focus": "stack",
+  "cue": 2400,
+  "step": { "count": 9, "interval": 340 },
+  "wait": 1400
+}
+```
+
+## Automation hooks
+
+Stable selectors for Playwright (see `video/README.md` for the full list).
+
+When adding new interactive controls to explorations, add a `data-testid` if the
+video playbook needs to click them.
+
+`BytecodeStepperEC` auto-scrolls the disassembly and stack panels during stepping
+(active PC row + deep stack entries stay in view). Playwright also syncs panel
+scroll after each `step` action in the playbook.
+
+## Local development
+
+Preview video mode in the dev server (overlays only appear when config is injected — use record dry-run to validate copy):
+
+```bash
+npm run dev
+# /eip-8024-stack-opcodes-dupn-swapn-exchange?fyp-video=1&example=dupn
+```
+
+## Recording
+
+From `website/`:
+
+```bash
+# ── Final (video + voice) — upload / listen with audio ──
+npm run video:generate:preview -- eip-8024   # 540×960 → *-final.mp4
+npm run video:generate -- eip-8024           # 1080×1920 → *-final.mp4 (same layout, 2× upscale)
+
+# ── Silent intermediate only (no audio) — always 540×960 capture ──
+npm run video:record -- eip-8024 --preview --no-voice
+npm run video:record -- eip-8024 --dry-run
+```
+
+Playwright always records at **540×960** (layout reference). Full-res deliverables are
+upscaled to 1080×1920 during mux — never a separate 1080px CSS viewport.
+
+Final: `video/projects/eip-8024/output/<id>-<timestamp>-final.mp4`  
+Intermediate: same stem with `.webm` (Playwright capture, no audio track).
+
+**Always run `npm run website:build` before recording** if `src/video/` changed (`video:generate` does this automatically).
+
+Recordings auto-trim lead-in (Playwright captures black/hidden frames before the title
+card renders) and verify frame 0 shows the title band for preview thumbnails. Detection
+uses center-crop dark-pixel ratio — not brightness alone. Requires `ffmpeg` on PATH.
+
+Details: [Record and verify](/contributing/video-authoring#record-and-verify).
+
+## Voice-over (ElevenLabs)
+
+Narration is synthesized first; character timestamps drive playbook timing; silent video is
+muxed with audio at the end. Full workflow: [Voice-over pipeline](/contributing/video-voice).
+
+```bash
+npm run video:voice:synth -- <project-id>   # ElevenLabs → voice/
+npm run video:voice:plan -- <project-id>    # voice-aligned storyboard
+
+# Final (video + audio):
+npm run video:generate:preview -- <project-id>
+npm run video:generate -- <project-id>
+
+# Silent webm only:
+npm run video:record -- <project-id> --preview --no-voice
+```
+
+## Tests
+
+Unit tests cover:
+
+- `src/libs/__tests__/exampleFromQuery.spec.ts` — query parsing and resolution
+- `src/libs/__tests__/exampleFromQuery.explorations.spec.ts` — all live explorations
+- `src/video/__tests__/` — video mode detection and bridge logic
+- `video/src/__tests__/` — project loading, playbook duration, lead-in trim
+
+Playwright recording is **not** run in CI (same policy as OG images).
+
+## Authoring guide
+
+[Authoring a video short](/contributing/video-authoring) — how to plan beats, write
+overlays/annotations/highlights, set pacing, record, and verify thumbnails. Reference:
+`video/projects/eip-8024/`.
+
+## Adding a new video
+
+1. Create `video/projects/<exploration-id>/content.json` and `playbook.json`
+2. Add exploration to `video/src/explorationRegistry.ts` if not already listed
+3. Run `npm run video:record -- <exploration-id>`
+
+No website changes required if the exploration type is already supported.
diff --git a/docs/contributing/video-voice.md b/docs/contributing/video-voice.md
new file mode 100644
index 0000000..f1f7a59
--- /dev/null
+++ b/docs/contributing/video-voice.md
@@ -0,0 +1,333 @@
+# Voice-over pipeline
+
+How to add ElevenLabs narration to Feel Your Protocol short-form videos.
+
+Operational baseline: [Video pipeline](/contributing/video-pipeline),
+[Authoring a video short](/contributing/video-authoring).
+
+---
+
+## Core idea
+
+**Today:** you hand-pick `cue` / `wait` / step `interval` ms in `playbook.json`, record a
+silent `.webm`, publish.
+
+**With voice:** ElevenLabs drives the **clock**. You write spoken copy, the API returns audio
+plus **character-level timestamps**. The playbook timing is **derived** (then refined) to
+match that audio. Recording stays silent; **ffmpeg muxes** video + voice at the end.
+
+ElevenLabs does **not** accept our time markers — it gives markers **back**. The workflow
+flips:
+
+```
+OLD:  story plan → manual ms timing → record
+NEW:  story plan → narration script → synthesize → derive ms timing → record → mux
+```
+
+You still need a **rough visual plan before synthesis** (which beats, which actions, climax).
+Voice generation is a **refinement step**, not a substitute for storyboarding.
+
+---
+
+## What we keep
+
+| Layer | Change |
+|-------|--------|
+| Title / outro cards | Keep — can be spoken over (band still shows peek + type) |
+| Story overlays (`punch`, `split`, …) | Keep copy — may differ from spoken script |
+| Annotations | Keep — still guide the eye during action |
+| Climax highlights | Keep — timing derived from voice + action budget |
+| Playwright recording | Keep — still drives the browser |
+| `zones.json`, exploration actions | Keep |
+
+On-screen text and spoken narration **may diverge** (shorter banners, fuller voice). Link
+them by **beat id**, not by identical strings.
+
+---
+
+## Project layout (planned)
+
+Per project `video/projects/<id>/`:
+
+| File / dir | Role |
+|------------|------|
+| `playbook.json` | **Structure** — beats, overlay ids, actions, focus, climax fields (intervals optional once voice timing exists) |
+| `narration.json` | **Spoken copy** — segments tied to beat ids |
+| `content.json` | Unchanged — visual overlay copy, annotations, highlights |
+| `voice/` | Generated artifacts (gitignored): `full.mp3`, `alignment.json`, `manifest.json` |
+| `output/` | Silent `.webm` + final muxed `.mp4` |
+
+Credentials: `video/.env` (`ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`, optional `ELEVENLABS_MODEL_ID=eleven_v3`).
+
+---
+
+## `narration.json` format (proposed)
+
+One segment per beat that has speech. Beats without an entry stay silent (e.g. pure action
+holds) or use `"text": ""`.
+
+```json
+{
+  "model": "eleven_v3",
+  "segments": [
+    {
+      "beat": "hook",
+      "text": "EIP-8024. Three new stack opcodes. Glamsterdam is coming."
+    },
+    {
+      "beat": "context",
+      "text": "Solidity developers know this error — stack too deep."
+    },
+    {
+      "beat": "opcodes",
+      "text": "DUPN, SWAPN, and EXCHANGE let the EVM reach deeper into the stack."
+    },
+    {
+      "beat": "stack-grow",
+      "text": "Watch the stack grow — seventeen values pushed."
+    },
+    {
+      "beat": "dupn-hit",
+      "text": "Now DUPN copies from depth seventeen. No compiler gymnastics."
+    },
+    {
+      "beat": "recap",
+      "text": "Classic DUP stops at depth sixteen. You just copied depth seventeen."
+    },
+    {
+      "beat": "outro",
+      "text": "Read the EIP on Forkcast. Explore it on Feel Your Protocol."
+    }
+  ]
+}
+```
+
+**Segment strategy:** synthesize **one segment per beat** (multiple API calls), then
+concatenate with a short crossfade or silence gap (~200–400 ms). This gives clean
+`startMs` / `endMs` per beat without parsing a monologue. Alternative: one full script +
+substring alignment lookup (see below) — better prosody, harder mapping.
+
+---
+
+## ElevenLabs API artifacts
+
+Endpoint (already validated):
+
+`POST /v1/text-to-speech/{voice_id}/with-timestamps`
+
+Response (per call):
+
+```json
+{
+  "audio_base64": "…",
+  "alignment": {
+    "characters": ["E", "I", "P", …],
+    "character_start_times_seconds": [0.0, 0.04, …],
+    "character_end_times_seconds": [0.04, 0.09, …]
+  }
+}
+```
+
+From alignment we can:
+
+1. **Duration** — last `character_end_times_seconds` × 1000.
+2. **Substring timing** — find beat text in the character stream → `startMs`, `endMs`.
+3. **Word boundaries** — group characters between spaces for caption-style overlays (v2+).
+
+Store per segment in `voice/manifest.json`:
+
+```json
+{
+  "generatedAt": "2026-07-04T…",
+  "audioFile": "voice/full.mp3",
+  "totalDurationMs": 47200,
+  "beats": {
+    "context": { "startMs": 5200, "endMs": 9100, "segmentFile": "voice/seg-context.mp3" },
+    "opcodes": { "startMs": 9300, "endMs": 14200 }
+  }
+}
+```
+
+---
+
+## Deriving playbook timing from voice
+
+For each playbook step with a narration segment:
+
+| Playbook field | Derivation |
+|----------------|------------|
+| `cue` | `beat.endMs - beat.startMs` while overlay is visible (narrator reads banner copy or parallel narration) |
+| Overlay hide | When beat speech ends (or slightly before last word if action should start on final syllable) |
+| `step.interval` | Fit N steps into `(nextBeat.startMs - actionStartMs - holdBudget)` |
+| Climax `climaxInterval` | Stretch to cover spoken emphasis on dupn-hit beat |
+| `wait` | `nextBeat.startMs - currentBeatEndMs - transitionMs`, floored at ~400 ms |
+
+**Action beats** (stack-grow, dupn-hit): speech often plays **during** overlay (`cue`), then
+overlay hides and steps run **while the next segment hasn't started yet**. Budget step
+intervals from the **gap** between segment end and next segment start, minus highlight holds.
+
+**Text-only beats** (recap): `wait` = segment duration (no `cue` split).
+
+**Title / outro:** treat like overlay-only beats — speech over the band; `wait` = voice
+duration (+ optional 300 ms tail).
+
+### Merge strategy
+
+Do **not** hand-edit derived ms in `playbook.json`. Use a generated overlay:
+
+- `playbook.json` — structure only (or legacy manual timing as fallback).
+- `voice/manifest.json` — authoritative timestamps from ElevenLabs.
+- `playbookRunner` loads **merged** step timing: `structure ⊕ voice manifest`.
+
+If voice files are missing, fall back to manual `cue`/`wait` (silent video mode).
+
+---
+
+## Pipeline commands (planned)
+
+From `website/`:
+
+```bash
+# One-shot final (video + voice) — open the *-final.mp4, not the .webm
+npm run video:generate:preview -- eip-8024
+npm run video:generate -- eip-8024
+npm run video:generate -- eip-8024 --skip-synth --preview   # reuse voice/, re-record + mux
+
+# Silent webm only (visual iteration, no audio):
+npm run video:record -- eip-8024 --preview --no-voice
+
+# Or step-by-step:
+npm run video:voice:synth -- eip-8024
+npm run video:voice:plan -- eip-8024
+npm run website:build
+npm run video:record -- eip-8024 --preview
+npm run video:voice:mux -- eip-8024
+```
+
+Skip synth/plan to record with manual timing (no `voice/manifest.json`).
+
+Implementation modules (under `video/src/voice/`):
+
+| Module | Responsibility |
+|--------|----------------|
+| `loadEnv.ts` | Load `video/.env` |
+| `elevenlabs.ts` | API client (`with-timestamps`) |
+| `synthesize.ts` | Segment loop, write mp3 + raw alignments |
+| `concatAudio.ts` | ffmpeg concat segments → `full.mp3` |
+| `alignBeats.ts` | Build `manifest.json` beat → start/end ms |
+| `mergeTiming.ts` | Apply manifest to playbook steps |
+| `mux.ts` | ffmpeg: copy video, encode AAC, `-shortest` |
+
+---
+
+## Lead-in trim and audio sync
+
+Recording trims black/hidden lead-in from the `.webm` (see `trimLeadIn.ts`). Audio must
+start at the **same** timeline origin as trimmed video.
+
+Options (pick one in implementation):
+
+1. **Anchor on title beat** — narration segments exclude pre-title silence; manifest
+   `startMs` is relative to first title frame (after trim). Simplest.
+2. **Prepend silence** — mux step adds `trimOffsetMs` silence to audio to match ffmpeg trim.
+3. **Record trim offset** — `recordVideo` writes `output/trim-meta.json`; mux reads it.
+
+Recommend **(1)** for v1: first segment is `hook` title speech; video timeline zero = title
+card visible; no voice before that.
+
+---
+
+## Procedural workflow (agent + human)
+
+Use this checklist for each new exploration short.
+
+### Phase A — Story (mostly unchanged)
+
+1. Define beats in `playbook.json` — overlay ids, actions, focus, climax fields.
+2. Write visual copy in `content.json` (overlays, annotations, highlightSets).
+3. Define `zones.json` focus areas.
+4. Run `npm run video:storyboard -- <id>` — validate structure **without** voice.
+
+Rough target length: ~45–60 s total voice (YouTube Shorts).
+
+### Phase B — Narration script
+
+1. Add `narration.json` — one segment per spoken beat.
+2. Write for **ear**, not screen: conversational, present tense, short sentences.
+3. Eleven v3: optional inline tags (`[excited]`, `[slowly]`) sparingly on climax beat.
+4. Read aloud yourself once — aim ~130–150 wpm equivalent.
+
+### Phase C — Synthesize
+
+1. Ensure `video/.env` is set.
+2. `npm run video:voice:synth -- <id>`
+3. Listen to `voice/full.mp3` — re-run after script edits (cache segments by text hash to save credits).
+
+### Phase D — Timing plan
+
+1. `npm run video:voice:plan -- <id>` — prints voice-aligned storyboard:
+   ```
+   00:00  hook      voice 4.2s  (overlay)
+   00:04  context   voice 3.8s  → hide → wait 0.6s
+   00:08  opcodes   voice 5.1s  → selectExample
+   …
+   ```
+2. Refine: if stack-grow speech is longer than 9 steps can fill, either shorten script or
+   slow step interval / reduce step count.
+3. Climax beat: ensure `climaxInterval` + highlight holds fit inside segment + gap.
+
+### Phase E — Record + verify
+
+1. `npm run website:build && npm run video:record -- <id> --preview`
+2. Scrub silent video against `voice/full.mp3` in a player (manual sync check).
+3. Fix timing via narration edits or `voice/plan overrides` (optional small manual offsets in manifest).
+
+### Phase F — Mux + publish
+
+1. `npm run video:voice:mux -- <id>` → `output/<id>-<timestamp>-final.mp4`
+2. Verify frame 0 thumbnail (title band) and audio start.
+3. Full-res record + mux when satisfied.
+
+---
+
+## Implementation order (suggested)
+
+| Step | Deliverable |
+|------|-------------|
+| 1 | `narration.json` schema + EIP-8024 sample script |
+| 2 | `voice/synthesize` CLI + segment mp3 + alignment JSON |
+| 3 | `concatAudio` + `manifest.json` beat timestamps |
+| 4 | `mergeTiming` integrated into `playbookRunner` / storyboard |
+| 5 | Record eip-8024 preview with voice-derived timing |
+| 6 | `mux` CLI + docs update in video-pipeline.md |
+| 7 | Optional: word-level captions from alignment (v2) |
+
+---
+
+## Testing
+
+- Unit tests: substring → ms lookup, merge timing math, manifest validation against playbook beat ids.
+- No ElevenLabs calls in CI — fixture alignment JSON from real API response.
+- Manual: preview record + mux for one project before merging pipeline defaults.
+
+---
+
+## Agent instructions
+
+When the user asks to add voice to a video project:
+
+1. Read this doc + existing `playbook.json` / `content.json`.
+2. Draft `narration.json` segments for beats that should be spoken.
+3. Run synth → plan → storyboard; report total duration and per-beat ms.
+4. Adjust narration length if derived step intervals fall below ~280 ms or total exceeds ~60 s.
+5. Record preview, mux, ask user to listen on phone.
+6. Do **not** commit `video/.env` or `voice/` artifacts.
+
+---
+
+## Related
+
+- [Video pipeline](/contributing/video-pipeline) — recording, overlays, trim
+- [Authoring a video short](/contributing/video-authoring) — beats, pacing, climax
+- `video/src/loadEnv.ts` — env loading for ElevenLabs
+- `video/.env.example` — credential template
diff --git a/docs/guide/architecture.md b/docs/guide/architecture.md
index 1071bc9..59111df 100644
--- a/docs/guide/architecture.md
+++ b/docs/guide/architecture.md
@@ -145,3 +145,15 @@ The project uses a hybrid testing approach:
 - **E2E tests** (Cypress) as lean smoke tests for critical navigation flows and page-level integration
 
 Unit tests live alongside their components in `__tests__/` folders. E2E tests are consolidated in `cypress/e2e/`.
+
+## Video pipeline (short-form)
+
+Vertical exploration videos for YouTube Shorts, Reels, and X are recorded via an
+isolated Playwright package in `video/` (same pattern as `og/` for social preview images).
+
+- **Website overlay shell** — `src/video/`, activated with `?fyp-video=1`
+- **Content & playbooks** — `video/projects/<id>/` (JSON, separate from the site)
+- **Deep-linking** — `?example=<key>` pre-selects example presets on all explorations
+
+See [Video pipeline](/contributing/video-pipeline) for the workflow and
+[Authoring a video short](/contributing/video-authoring) for how to write a project.
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index 1dc1b67..6624c37 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -28,6 +28,8 @@ at contributors and developers who want to understand or extend the project.
 - [Styling & Design](https://docs.feelyourprotocol.org/contributing/styling.html): The exploration design system and class conventions
 - [Code Conventions](https://docs.feelyourprotocol.org/contributing/code-conventions.html): Coding standards and test commands
 - [Third-Party Libraries](https://docs.feelyourprotocol.org/contributing/third-party-libraries.html): How new library dependencies are evaluated and added
+- [Video Pipeline](https://docs.feelyourprotocol.org/contributing/video-pipeline.html): Short-form exploration videos — architecture, overlays, recording
+- [Authoring a Video Short](https://docs.feelyourprotocol.org/contributing/video-authoring.html): How to plan, write, and record exploration shorts
 
 ## Related
 
diff --git a/docs/special-actions/ice-cream-week.md b/docs/special-actions/ice-cream-week.md
index a259537..f54ef98 100644
--- a/docs/special-actions/ice-cream-week.md
+++ b/docs/special-actions/ice-cream-week.md
@@ -2,8 +2,8 @@
 
 Temporary home-page gag (see [Special Actions overview](/special-actions/)): a meme ice cream stand where visitors buy a scoop with **$FYP on Base** and receive a **soulbound NFT** receipt.
 
-::: warning Summer gag, real on-chain flow
-Playful sandbox — not financial advice, not a product roadmap. **IceCreamStand** is deployed on Base; wallet integration on the home page is the remaining step. Code lives in `src/ice-cream/` and stays in the repo after the stand comes down; only the home integration is removed.
+::: info Archived on home (July 2026)
+The stand is **off the home page**. **IceCreamStand** remains on Base; `public/ice-cream/` metadata URLs stay live for soulbound receipts. Code lives in `src/ice-cream/` for reference and possible reuse.
 :::
 
 ## Scope
@@ -46,10 +46,10 @@ src/ice-cream/
 ├── purchasePort.ts          # IceCreamPurchasePort — viem later
 ├── memes.ts                 # vendor + NFT image pairs
 ├── assets/                  # vendor WebP + nft/ PNG masters
-└── __tests__/               # remove folder with feature if desired
+└── __tests__/               # module + IceCreamHomeSection.spec.ts (keep when archived)
 ```
 
-**Home integration (single point):**
+**Home integration (single point — currently removed):**
 
 ```vue
 import { IceCreamHomeSection } from '@/ice-cream'
@@ -57,7 +57,9 @@ import { IceCreamHomeSection } from '@/ice-cream'
 <IceCreamHomeSection />
 ```
 
-To end Ice Cream Week: delete the import and `<IceCreamHomeSection />` line in `HomeView.vue`. Optionally remove `describe('Ice Cream Week')` from `HomeView.spec.ts`.
+To **activate:** add the import and `<IceCreamHomeSection />` in `HomeView.vue` (above Latest).
+
+To **deactivate:** remove those two lines only. Keep `src/ice-cream/` and its tests. Do **not** add special-action assertions to `HomeView.spec.ts` — home placement is covered by `IceCreamHomeSection.spec.ts`. See [Special Actions lifecycle](/special-actions/#lifecycle).
 
 ## Purchase flow (phases)
 
diff --git a/docs/special-actions/index.md b/docs/special-actions/index.md
index acf0726..47bfcbb 100644
--- a/docs/special-actions/index.md
+++ b/docs/special-actions/index.md
@@ -6,8 +6,17 @@ Short-lived or playful features on the main site — summer gags, one-off events
 These pages document how we built and operate specific actions. Add a new page under `docs/special-actions/` and link it here when another action ships.
 :::
 
+## Lifecycle
+
+| Phase | Home page | Tests |
+| ----- | --------- | ----- |
+| **Active** | Import the action’s `*HomeSection` in `HomeView.vue` | Module tests in `src/<action>/__tests__/` (always) |
+| **Archived** | Remove import + component from `HomeView.vue` | Same module tests — **do not** delete; **do not** add special-action blocks to `HomeView.spec.ts` |
+
+**Test convention:** `HomeView.spec.ts` covers permanent home content only. Each special action keeps its own tests under `src/<action>/__tests__/`, including a `*HomeSection.spec.ts` for the home section wrapper. When you deactivate, remove home wiring only — the module test suite stays green and documents how to re-enable.
+
 ## Active & archived
 
 | Action | Status | Doc |
 | ------ | ------ | --- |
-| Ice Cream Week | Active (home page) | [Ice Cream Week](./ice-cream-week) |
+| Ice Cream Week | Archived (home removed July 2026; contract + metadata live) | [Ice Cream Week](./ice-cream-week) |
diff --git a/package.json b/package.json
index a72cfec..263099f 100644
--- a/package.json
+++ b/package.json
@@ -33,6 +33,17 @@
     "social:preview": "vite preview --config vite.social.config.ts",
     "capture:social": "run-s social:build capture:social:run",
     "capture:social:run": "npm run capture:social:run --prefix og --",
+    "video:setup": "npm run setup --prefix video",
+    "video:check": "npm run check --prefix video",
+    "video:preflight": "npm run preflight --prefix video",
+    "video:record": "npm run record --prefix video --",
+    "video:storyboard": "npm run storyboard --prefix video --",
+    "video:voice:synth": "npm run voice:synth --prefix video --",
+    "video:voice:plan": "npm run voice:plan --prefix video --",
+    "video:voice:mux": "npm run voice:mux --prefix video --",
+    "video:generate": "npm run website:build && npm run generate --prefix video --",
+    "video:generate:preview": "npm run website:build && npm run generate --prefix video -- --preview",
+    "video:render": "npm run video:generate --",
     "website:preview": "vite preview --outDir dist/website",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
diff --git a/src/App.vue b/src/App.vue
index d858151..8c95732 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref, watch } from 'vue'
+import { computed, onUnmounted, ref, watch } from 'vue'
 import { RouterLink, RouterView, useRoute, useRouter } from 'vue-router'
 import { Listbox, ListboxButton, ListboxOption, ListboxOptions } from '@headlessui/vue'
 import { ChevronUpDownIcon } from '@heroicons/vue/20/solid'
@@ -7,9 +7,12 @@ import { ChevronUpDownIcon } from '@heroicons/vue/20/solid'
 import { EXPLORATIONS } from '@/explorations/REGISTRY'
 import { FYP_X_URL, ROADMAP_HOME } from '@/libs/roadmapUrls'
 import logoUrl from '@/logo.png'
+import { useVideoMode } from '@/video/useVideoMode'
+import VideoShell from '@/video/VideoShell.vue'
 
 const router = useRouter()
 const route = useRoute()
+const isVideoMode = useVideoMode()
 const selectedRoute = ref(route.path.includes('eip-') ? route.path : '')
 
 const selectedLabel = computed(() => {
@@ -34,138 +37,155 @@ watch(
     }
   },
 )
+
+watch(
+  isVideoMode,
+  (active) => {
+    document.documentElement.classList.toggle('fyp-video-capture', active)
+  },
+  { immediate: true },
+)
+
+onUnmounted(() => {
+  document.documentElement.classList.remove('fyp-video-capture', 'fyp-video-band-active')
+})
 </script>
 
 <template>
-  <header class="mt-3 mb-4">
-    <div class="flex flex-col gap-2 sm:grid sm:grid-cols-2">
-      <div class="site-title sm:col-start-1 sm:row-start-1">
-        <RouterLink
-          to="/"
-          class="inline-flex items-center gap-2.5 md:gap-3 text-2xl md:text-4xl font-bold tracking-wider whitespace-nowrap no-underline"
+  <div :class="isVideoMode ? 'fyp-video-mode min-h-dvh bg-black' : ''">
+    <header v-if="!isVideoMode" class="mt-3 mb-4">
+      <div class="flex flex-col gap-2 sm:grid sm:grid-cols-2">
+        <div class="site-title sm:col-start-1 sm:row-start-1">
+          <RouterLink
+            to="/"
+            class="inline-flex items-center gap-2.5 md:gap-3 text-2xl md:text-4xl font-bold tracking-wider whitespace-nowrap no-underline"
+          >
+            <img
+              :src="logoUrl"
+              alt=""
+              class="h-[1em] w-auto shrink-0"
+              width="108"
+              height="128"
+              fetchpriority="high"
+            />
+            <span class="bg-gradient-to-r from-purple-600 to-cyan-500 bg-clip-text text-transparent"
+              >Feel Your Protocol</span
+            >
+          </RouterLink>
+        </div>
+        <p
+          class="flex items-baseline text-sm md:text-xl text-slate-500 tracking-wide sm:col-span-2 sm:row-start-2"
         >
-          <img
-            :src="logoUrl"
-            alt=""
-            class="h-[1em] w-auto shrink-0"
-            width="108"
-            height="128"
-            fetchpriority="high"
-          />
-          <span class="bg-gradient-to-r from-purple-600 to-cyan-500 bg-clip-text text-transparent"
-            >Feel Your Protocol</span
+          <span class="shrink-0">Interactive Ethereum Protocol Explorations</span>
+          <span class="protocol-dots hidden sm:inline flex-1 overflow-hidden whitespace-nowrap"
+            >· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+            · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+            · · · · · · · · · · · ·</span
           >
-        </RouterLink>
-      </div>
-      <p
-        class="flex items-baseline text-sm md:text-xl text-slate-500 tracking-wide sm:col-span-2 sm:row-start-2"
-      >
-        <span class="shrink-0">Interactive Ethereum Protocol Explorations</span>
-        <span class="protocol-dots hidden sm:inline flex-1 overflow-hidden whitespace-nowrap"
-          >· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
-          · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
-          · · · · · · · · · ·</span
+        </p>
+        <nav
+          class="font-mono text-sm sm:col-start-2 sm:row-start-1 sm:text-right flex sm:justify-end items-center"
         >
-      </p>
-      <nav
-        class="font-mono text-sm sm:col-start-2 sm:row-start-1 sm:text-right flex sm:justify-end items-center"
-      >
-        <Listbox v-model="selectedRoute" @update:model-value="navigate">
-          <div class="relative inline-block w-full sm:w-auto">
-            <ListboxButton
-              class="inline-flex items-center justify-between gap-2 w-full sm:w-auto sm:max-w-md text-sm sm:ml-6 border border-slate-400 bg-white rounded-md text-slate-500 px-3 py-2 min-h-11 cursor-pointer text-left"
-              id="exploration-navi"
-            >
-              <span class="min-w-0 line-clamp-2">{{ selectedLabel }}</span>
-              <ChevronUpDownIcon class="size-3.5 opacity-50" />
-            </ListboxButton>
+          <Listbox v-model="selectedRoute" @update:model-value="navigate">
+            <div class="relative inline-block w-full sm:w-auto">
+              <ListboxButton
+                class="inline-flex items-center justify-between gap-2 w-full sm:w-auto sm:max-w-md text-sm sm:ml-6 border border-slate-400 bg-white rounded-md text-slate-500 px-3 py-2 min-h-11 cursor-pointer text-left"
+                id="exploration-navi"
+              >
+                <span class="min-w-0 line-clamp-2">{{ selectedLabel }}</span>
+                <ChevronUpDownIcon class="size-3.5 opacity-50" />
+              </ListboxButton>
 
-            <transition
-              enter-active-class="transition duration-100 ease-out"
-              enter-from-class="opacity-0 scale-95"
-              enter-to-class="opacity-100 scale-100"
-              leave-active-class="transition duration-75 ease-in"
-              leave-from-class="opacity-100 scale-100"
-              leave-to-class="opacity-0 scale-95"
-            >
-              <ListboxOptions
-                class="absolute right-0 z-20 mt-1 w-max max-h-60 overflow-auto rounded-md border border-slate-400 bg-white text-sm shadow-md focus:outline-none"
+              <transition
+                enter-active-class="transition duration-100 ease-out"
+                enter-from-class="opacity-0 scale-95"
+                enter-to-class="opacity-100 scale-100"
+                leave-active-class="transition duration-75 ease-in"
+                leave-from-class="opacity-100 scale-100"
+                leave-to-class="opacity-0 scale-95"
               >
-                <ListboxOption value="" v-slot="{ active, selected }" as="template">
-                  <li
-                    :class="[
-                      'cursor-pointer whitespace-nowrap px-3 py-2 select-none text-slate-500',
-                      active ? 'bg-slate-50 text-slate-700' : '',
-                      selected ? 'font-bold text-slate-700' : '',
-                    ]"
-                  >
-                    All Explorations
-                  </li>
-                </ListboxOption>
-                <ListboxOption
-                  v-for="exploration in Object.values(EXPLORATIONS)"
-                  :key="exploration.id"
-                  :value="exploration.path"
-                  v-slot="{ active, selected }"
-                  as="template"
+                <ListboxOptions
+                  class="absolute right-0 z-20 mt-1 w-max max-h-60 overflow-auto rounded-md border border-slate-400 bg-white text-sm shadow-md focus:outline-none"
                 >
-                  <li
-                    :class="[
-                      'cursor-pointer text-left max-w-xs sm:max-w-md px-3 py-2 select-none text-slate-500',
-                      active ? 'bg-slate-50 text-slate-700' : '',
-                      selected ? 'font-bold text-slate-700' : '',
-                    ]"
+                  <ListboxOption value="" v-slot="{ active, selected }" as="template">
+                    <li
+                      :class="[
+                        'cursor-pointer whitespace-nowrap px-3 py-2 select-none text-slate-500',
+                        active ? 'bg-slate-50 text-slate-700' : '',
+                        selected ? 'font-bold text-slate-700' : '',
+                      ]"
+                    >
+                      All Explorations
+                    </li>
+                  </ListboxOption>
+                  <ListboxOption
+                    v-for="exploration in Object.values(EXPLORATIONS)"
+                    :key="exploration.id"
+                    :value="exploration.path"
+                    v-slot="{ active, selected }"
+                    as="template"
                   >
-                    {{ exploration.title }}
-                  </li>
-                </ListboxOption>
-              </ListboxOptions>
-            </transition>
-          </div>
-        </Listbox>
-      </nav>
-    </div>
-  </header>
+                    <li
+                      :class="[
+                        'cursor-pointer text-left max-w-xs sm:max-w-md px-3 py-2 select-none text-slate-500',
+                        active ? 'bg-slate-50 text-slate-700' : '',
+                        selected ? 'font-bold text-slate-700' : '',
+                      ]"
+                    >
+                      {{ exploration.title }}
+                    </li>
+                  </ListboxOption>
+                </ListboxOptions>
+              </transition>
+            </div>
+          </Listbox>
+        </nav>
+      </div>
+    </header>
 
-  <aside
-    class="mb-4 rounded-lg border border-purple-200/80 bg-gradient-to-r from-purple-50/90 to-cyan-50/70 px-4 py-3 shadow-sm"
-  >
-    <p class="font-mono text-xs leading-relaxed text-slate-700 sm:text-sm">
-      <span class="font-bold text-purple-700">Phase 3</span>
-      — we're designing a deterministic API &amp; MCP server for the future Ethereum protocol
-      (upcoming forks &amp; EIPs) for AI agents.
-      <a
-        :href="ROADMAP_HOME"
-        target="_blank"
-        rel="noopener"
-        class="ml-1 font-semibold text-purple-700 underline decoration-purple-300 underline-offset-2 hover:text-purple-900"
-        >Read the roadmap ↗</a
-      >
-    </p>
-  </aside>
+    <aside
+      v-if="!isVideoMode"
+      class="mb-4 rounded-lg border border-purple-200/80 bg-gradient-to-r from-purple-50/90 to-cyan-50/70 px-4 py-3 shadow-sm"
+    >
+      <p class="font-mono text-xs leading-relaxed text-slate-700 sm:text-sm">
+        <span class="font-bold text-purple-700">Phase 3</span>
+        — we're designing a deterministic API &amp; MCP server for the future Ethereum protocol
+        (upcoming forks &amp; EIPs) for AI agents.
+        <a
+          :href="ROADMAP_HOME"
+          target="_blank"
+          rel="noopener"
+          class="ml-1 font-semibold text-purple-700 underline decoration-purple-300 underline-offset-2 hover:text-purple-900"
+          >Read the roadmap ↗</a
+        >
+      </p>
+    </aside>
+
+    <RouterView :key="route.fullPath" class="grid grid-cols-1" />
 
-  <RouterView :key="route.fullPath" class="grid grid-cols-1" />
+    <VideoShell v-if="isVideoMode" />
 
-  <footer class="grid grid-cols-1 sm:grid-cols-2 gap-2 pt-3 mt-10 mb-2">
-    <h3 class="font-mono text-xs text-slate-500">
-      <span class="text-purple-500">◆</span> Made with ❤️ and pure dedication by
-      <a href="https://x.com/HolgerD77" target="_blank" rel="noopener">HolgerD77</a>
-      <span class="text-purple-500 mx-2">◆</span>
-      <RouterLink to="/imprint">Imprint</RouterLink>
-    </h3>
+    <footer v-if="!isVideoMode" class="grid grid-cols-1 sm:grid-cols-2 gap-2 pt-3 mt-10 mb-2">
+      <h3 class="font-mono text-xs text-slate-500">
+        <span class="text-purple-500">◆</span> Made with ❤️ and pure dedication by
+        <a href="https://x.com/HolgerD77" target="_blank" rel="noopener">HolgerD77</a>
+        <span class="text-purple-500 mx-2">◆</span>
+        <RouterLink to="/imprint">Imprint</RouterLink>
+      </h3>
 
-    <h3 class="font-mono text-xs text-slate-500 sm:text-right">
-      <a :href="ROADMAP_HOME" target="_blank" rel="noopener">Roadmap</a>
-      <span class="text-purple-500 mx-2">◆</span>
-      <a href="https://community-token.feelyourprotocol.org/" target="_blank" rel="noopener"
-        >Community Token</a
-      >
-      <span class="text-purple-500 mx-2">◆</span>
-      <a :href="FYP_X_URL" target="_blank" rel="noopener">X</a>
-      <span class="text-purple-500 mx-2">◆</span>
-      <a href="https://github.com/feelyourprotocol/website" target="_blank" rel="noopener"
-        >GitHub</a
-      >
-    </h3>
-  </footer>
+      <h3 class="font-mono text-xs text-slate-500 sm:text-right">
+        <a :href="ROADMAP_HOME" target="_blank" rel="noopener">Roadmap</a>
+        <span class="text-purple-500 mx-2">◆</span>
+        <a href="https://community-token.feelyourprotocol.org/" target="_blank" rel="noopener"
+          >Community Token</a
+        >
+        <span class="text-purple-500 mx-2">◆</span>
+        <a :href="FYP_X_URL" target="_blank" rel="noopener">X</a>
+        <span class="text-purple-500 mx-2">◆</span>
+        <a href="https://github.com/feelyourprotocol/website" target="_blank" rel="noopener"
+          >GitHub</a
+        >
+      </h3>
+    </footer>
+  </div>
 </template>
diff --git a/src/components/CompanionSheet.vue b/src/components/CompanionSheet.vue
index 0510547..ed8593f 100644
--- a/src/components/CompanionSheet.vue
+++ b/src/components/CompanionSheet.vue
@@ -1,10 +1,22 @@
 <script setup lang="ts">
 import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 
-const PEEK_PX = 56
+import { COMPANION_EXPAND_EVENT, type CompanionExpandMode } from '@/video/companionSheetEvents'
+
 const HALF_RATIO = 0.5
 const FULL_RATIO = 0.92
 
+function videoCaptureScale(): number {
+  if (typeof document === 'undefined' || typeof window === 'undefined') return 1
+  if (!document.documentElement.classList.contains('fyp-video-capture')) return 1
+  if (window.innerWidth <= 540) return 1
+  return window.innerWidth / 540
+}
+
+function peekPx(): number {
+  return Math.round(56 * videoCaptureScale())
+}
+
 export type CompanionSnap = 'peek' | 'half' | 'full'
 
 const props = defineProps<{
@@ -23,7 +35,7 @@ const prefersReducedMotion = ref(false)
 
 function snapHeightPx(target: CompanionSnap): number {
   const vh = viewportHeight.value
-  if (target === 'peek') return PEEK_PX
+  if (target === 'peek') return peekPx()
   if (target === 'half') return Math.round(vh * HALF_RATIO)
   return Math.round(vh * FULL_RATIO)
 }
@@ -36,7 +48,7 @@ const sheetHeightPx = computed(() => {
 function nearestSnap(heightPx: number): CompanionSnap {
   const vh = viewportHeight.value
   const candidates: [CompanionSnap, number][] = [
-    ['peek', PEEK_PX],
+    ['peek', peekPx()],
     ['half', Math.round(vh * HALF_RATIO)],
     ['full', Math.round(vh * FULL_RATIO)],
   ]
@@ -56,6 +68,16 @@ function expandToHalf() {
   if (snap.value === 'peek') snap.value = 'half'
 }
 
+function expandToFull() {
+  snap.value = 'full'
+}
+
+function onCompanionExpand(event: Event) {
+  const mode = (event as CustomEvent<{ mode: CompanionExpandMode }>).detail?.mode
+  if (mode === 'full') expandToFull()
+  else if (mode === 'half') expandToHalf()
+}
+
 let dragStartY = 0
 let dragStartHeight = 0
 
@@ -71,7 +93,7 @@ function onHandlePointerMove(event: PointerEvent) {
   if (!dragging.value) return
   const delta = dragStartY - event.clientY
   const vh = viewportHeight.value
-  const min = PEEK_PX
+  const min = peekPx()
   const max = Math.round(vh * FULL_RATIO)
   dragHeightPx.value = Math.min(max, Math.max(min, dragStartHeight + delta))
 }
@@ -91,6 +113,12 @@ function onViewportChange() {
 }
 
 function isMobileSheet(): boolean {
+  if (
+    typeof document !== 'undefined' &&
+    document.documentElement.classList.contains('fyp-video-capture')
+  ) {
+    return true
+  }
   return typeof window.matchMedia === 'function' && window.matchMedia('(max-width: 767px)').matches
 }
 
@@ -130,23 +158,26 @@ onMounted(() => {
     window.matchMedia('(prefers-reduced-motion: reduce)').matches
   if (prefersReducedMotion.value) snap.value = 'half'
   window.addEventListener('resize', onViewportChange)
+  window.addEventListener(COMPANION_EXPAND_EVENT, onCompanionExpand)
 })
 
 onUnmounted(() => {
   window.removeEventListener('resize', onViewportChange)
+  window.removeEventListener(COMPANION_EXPAND_EVENT, onCompanionExpand)
 })
 
-defineExpose({ snap, expandToHalf })
+defineExpose({ snap, expandToHalf, expandToFull })
 </script>
 
 <template>
   <div
     class="companion-sheet flex flex-col min-h-0 max-md:bg-white max-md:border-t max-md:border-slate-200 max-md:shadow-[0_-8px_30px_rgba(15,23,42,0.12)] max-md:rounded-t-xl max-md:overflow-hidden md:contents"
+    data-testid="companion-sheet"
     :class="[
       pulsing ? 'companion-sheet-pulse' : '',
       dragging ? '' : 'max-md:transition-[height] max-md:duration-300 max-md:ease-out',
     ]"
-    :style="{ height: `${sheetHeightPx}px`, '--companion-peek-h': `${PEEK_PX}px` }"
+    :style="{ height: `${sheetHeightPx}px`, '--companion-peek-h': `${peekPx()}px` }"
   >
     <div
       class="md:hidden shrink-0 touch-none select-none"
@@ -161,6 +192,7 @@ defineExpose({ snap, expandToHalf })
       <button
         type="button"
         class="companion-sheet-peek w-full px-3 pb-2 text-left font-mono text-xs leading-snug truncate"
+        data-testid="companion-peek"
         :class="active ? 'text-slate-700 font-semibold' : 'text-slate-400'"
         @click="expandToHalf"
       >
diff --git a/src/eComponents/bytecodeStepperEC/BytecodeStepperEC.vue b/src/eComponents/bytecodeStepperEC/BytecodeStepperEC.vue
index b6cc765..70f9a73 100644
--- a/src/eComponents/bytecodeStepperEC/BytecodeStepperEC.vue
+++ b/src/eComponents/bytecodeStepperEC/BytecodeStepperEC.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, provide, ref } from 'vue'
+import { computed, nextTick, provide, ref, watch } from 'vue'
 import type { EVM } from '@ethereumjs/evm'
 import { bytesToHex } from '@ethereumjs/util'
 
@@ -24,6 +24,8 @@ const props = defineProps<{
   examples: Examples
   exploration: Exploration
   evm: EVM
+  /** Parsed `?example=` query value — pass from exploration MyC when deep-linking. */
+  exampleQuery?: string
 }>()
 
 const topic = TOPICS[props.exploration.topic]
@@ -49,7 +51,7 @@ const {
   reset,
 } = useBytecodeStepper(props.config, props.evm)
 
-await init(props.examples)
+await init(props.examples, props.exampleQuery)
 
 const activePc = computed(() => currentSnapshot.value?.pc ?? -1)
 
@@ -123,6 +125,57 @@ function scrollPanelsToTop() {
   }
 }
 
+function scrollDisassemblyToActivePc() {
+  const panel = disassemblyPanel.value
+  if (!panel || activePc.value < 0) return
+  const row = panel.querySelector(`[data-disassembly-pc="${activePc.value}"]`)
+  if (row instanceof HTMLElement) {
+    row.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+  }
+}
+
+function scrollStackToRelevantDepths() {
+  const panel = stackPanel.value
+  if (!panel) return
+  const depth = displayedStack.value.length
+  const opcode = activeInstruction.value?.opcodeByte
+  const opName = activeInstruction.value?.name ?? ''
+
+  if (mode.value === 'finished' || mode.value === 'error' || /^STOP|RETURN|REVERT/i.test(opName)) {
+    panel.scrollTop = 0
+    return
+  }
+
+  // About to run DUPN / SWAPN / EXCHANGE — keep deep stack entries in view (depth 17 area).
+  if (opcode === 0xe6 || opcode === 0xe7 || opcode === 0xe8) {
+    panel.scrollTop = Math.max(0, panel.scrollHeight - panel.clientHeight)
+    return
+  }
+
+  if (depth >= 10) {
+    panel.scrollTop = Math.max(0, panel.scrollHeight - panel.clientHeight)
+    return
+  }
+
+  panel.scrollTop = 0
+}
+
+function scrollPanelsToExecutionFocus() {
+  scrollDisassemblyToActivePc()
+  scrollStackToRelevantDepths()
+}
+
+watch(activePc, () => {
+  void nextTick().then(scrollPanelsToExecutionFocus)
+})
+
+watch(
+  () => currentSnapshot.value?.stack.length ?? 0,
+  () => {
+    void nextTick().then(scrollStackToRelevantDepths)
+  },
+)
+
 async function onExampleChange() {
   await selectExample(props.examples)
   scrollPanelsToTop()
@@ -164,16 +217,19 @@ function formatStackWord(word: bigint): string {
 
           <div class="flex flex-wrap gap-2 mb-4 items-center">
             <ActionButtonUIC
+              test-id="bytecode-run"
               text="Run"
               tooltip="Execute bytecode to completion"
               :onClick="runAll"
             />
             <ActionButtonUIC
+              test-id="bytecode-step"
               text="Step"
               tooltip="Execute one opcode at a time"
               :onClick="stepOnce"
             />
             <ActionButtonUIC
+              test-id="bytecode-reset"
               text="Reset"
               tooltip="Clear execution state (keeps bytecode)"
               :onClick="onReset"
@@ -196,6 +252,7 @@ function formatStackWord(word: bigint): string {
               <h4 class="font-mono text-xs font-bold mb-2 text-slate-700">Disassembly</h4>
               <div
                 ref="disassemblyPanel"
+                data-testid="bytecode-disassembly"
                 class="font-mono text-xs bg-slate-50 border border-slate-200 rounded-md p-2 max-h-64 overflow-y-auto"
               >
                 <div
@@ -209,6 +266,8 @@ function formatStackWord(word: bigint): string {
                 <div
                   v-for="row in instructions"
                   :key="row.pc"
+                  :data-disassembly-pc="row.pc"
+                  :data-disassembly-active="row.pc === activePc ? 'true' : undefined"
                   :class="[
                     'grid grid-cols-[2.5rem_1fr_1fr] gap-x-2 py-0.5 px-1 rounded items-baseline',
                     row.pc === activePc ? 'bg-purple-100' : '',
@@ -231,6 +290,8 @@ function formatStackWord(word: bigint): string {
                   </span>
                   <span
                     :class="row.pc === activePc ? 'text-purple-900 font-bold' : 'text-slate-800'"
+                    :data-disassembly-opcode="row.name ? '' : undefined"
+                    :data-disassembly-mnemonic="row.name || undefined"
                   >
                     {{ row.name }}
                   </span>
@@ -250,6 +311,7 @@ function formatStackWord(word: bigint): string {
               </h4>
               <div
                 ref="stackPanel"
+                data-testid="bytecode-stack"
                 class="font-mono text-xs bg-slate-50 border border-slate-200 rounded-md p-2 min-h-[6rem] max-h-40 overflow-y-auto"
               >
                 <div
@@ -262,6 +324,7 @@ function formatStackWord(word: bigint): string {
                 <div
                   v-for="item in displayedStack"
                   :key="item.depth"
+                  :data-stack-depth="item.depth"
                   class="grid grid-cols-[2.5rem_1fr] gap-x-2 py-0.5 break-all items-baseline"
                 >
                   <span
@@ -269,7 +332,7 @@ function formatStackWord(word: bigint): string {
                   >
                     {{ item.depth }}
                   </span>
-                  <span>[{{ formatStackWord(item.word) }}]</span>
+                  <span data-stack-value>[{{ formatStackWord(item.word) }}]</span>
                 </div>
                 <p v-if="displayedStack.length === 0" class="text-slate-400">(empty)</p>
               </div>
diff --git a/src/eComponents/bytecodeStepperEC/__tests__/useBytecodeStepper.spec.ts b/src/eComponents/bytecodeStepperEC/__tests__/useBytecodeStepper.spec.ts
index 66c8ba3..b39c838 100644
--- a/src/eComponents/bytecodeStepperEC/__tests__/useBytecodeStepper.spec.ts
+++ b/src/eComponents/bytecodeStepperEC/__tests__/useBytecodeStepper.spec.ts
@@ -1,10 +1,4 @@
 import { describe, expect, it, vi } from 'vitest'
-
-vi.mock('vue-router', () => ({
-  useRoute: () => ({ query: {} }),
-  useRouter: () => ({ resolve: vi.fn(() => ({ href: '' })) }),
-}))
-
 import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
 import { createEVM } from '@ethereumjs/evm'
 
@@ -178,4 +172,24 @@ describe('useBytecodeStepper', () => {
     )
     expect(state.mode.value).toBe('stepping')
   })
+
+  it('loads example from ?example= query on init', async () => {
+    const evm = await createEvm()
+    const state = useBytecodeStepper(config, evm)
+
+    await state.init(examples, 'push-stop')
+
+    expect(state.bytecodeHex.value).toBe('60016000')
+    expect(state.example.value).toBe('push-stop')
+  })
+
+  it('falls back to default when ?example= is unknown', async () => {
+    const evm = await createEvm()
+    const state = useBytecodeStepper(config, evm)
+
+    await state.init(examples, 'not-real')
+
+    expect(state.bytecodeHex.value).toBe('600160020100')
+    expect(state.example.value).toBe('push-add')
+  })
 })
diff --git a/src/eComponents/bytecodeStepperEC/useBytecodeStepper.ts b/src/eComponents/bytecodeStepperEC/useBytecodeStepper.ts
index d955548..805de00 100644
--- a/src/eComponents/bytecodeStepperEC/useBytecodeStepper.ts
+++ b/src/eComponents/bytecodeStepperEC/useBytecodeStepper.ts
@@ -3,6 +3,7 @@ import type { EVM, ExecResult } from '@ethereumjs/evm'
 import { hexToBytes } from '@ethereumjs/util'
 
 import type { Examples } from '@/explorations/REGISTRY'
+import { resolveInitialExample } from '@/libs/exampleFromQuery'
 
 import { isValidByteInputForm } from '../precompileInterfaceEC/utils'
 import { disassembleBytecode } from './disassemble'
@@ -105,8 +106,8 @@ export function useBytecodeStepper(config: BytecodeStepperConfig, evm: EVM) {
     await rearm()
   }
 
-  async function init(examples: Examples) {
-    example.value = config.defaultExample
+  async function init(examples: Examples, queryExample?: string) {
+    example.value = resolveInitialExample(examples, config.defaultExample, queryExample)
     await selectExample(examples)
   }
 
diff --git a/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue b/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
index 4579374..8b8aa5d 100644
--- a/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
+++ b/src/eComponents/precompileInterfaceEC/PrecompileInterfaceEC.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts" generic="T">
+import { useRoute } from 'vue-router'
 import type { PrefixedHexString } from '@ethereumjs/util'
 
 import ExamplesUIC from '@/eComponents/ui/ExamplesUIC.vue'
@@ -8,6 +9,7 @@ import PoweredByC from '@/explorations/PoweredByC.vue'
 import type { Examples } from '@/explorations/REGISTRY'
 import type { Exploration } from '@/explorations/REGISTRY'
 import { TOPICS } from '@/explorations/TOPICS'
+import { parseExampleQueryParam } from '@/libs/exampleFromQuery'
 
 import PrecompileValueInputEC from './PrecompileValueInputEC.vue'
 import type { PrecompileConfig } from './types'
@@ -25,6 +27,7 @@ defineSlots<{
 }>()
 
 const topic = TOPICS[props.exploration.topic]
+const route = useRoute()
 
 const {
   data,
@@ -41,7 +44,10 @@ const {
   init,
 } = usePrecompileState(props.config, props.examples, props.run)
 
-await init()
+await init({
+  queryExample: parseExampleQueryParam(route.query?.example),
+  routeQuery: route.query,
+})
 </script>
 
 <template>
diff --git a/src/eComponents/precompileInterfaceEC/__tests__/usePrecompileState.spec.ts b/src/eComponents/precompileInterfaceEC/__tests__/usePrecompileState.spec.ts
index df57ec4..50bd208 100644
--- a/src/eComponents/precompileInterfaceEC/__tests__/usePrecompileState.spec.ts
+++ b/src/eComponents/precompileInterfaceEC/__tests__/usePrecompileState.spec.ts
@@ -1,10 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
 
-vi.mock('vue-router', () => ({
-  useRoute: () => ({ query: {} }),
-  useRouter: () => ({ resolve: vi.fn(() => ({ href: '' })) }),
-}))
-
 import type { Examples } from '@/explorations/REGISTRY'
 
 import type { PrecompileConfig } from '../types'
@@ -18,6 +13,7 @@ const config: PrecompileConfig = {
 
 const examples: Examples = {
   ex1: { title: 'Example 1', values: ['deadbeef'] },
+  ex2: { title: 'Example 2', values: ['cafebabe'] },
 }
 
 describe('usePrecompileState', () => {
@@ -92,4 +88,42 @@ describe('usePrecompileState', () => {
     expect(state).not.toHaveProperty('execResultPre')
     expect(state).not.toHaveProperty('execResultPost')
   })
+
+  it('loads example from ?example= query on init', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const state = usePrecompileState(config, examples, run)
+
+    await state.init({ queryExample: 'ex2' })
+
+    expect(state.example.value).toBe('ex2')
+    expect(run).toHaveBeenCalledWith('0xcafebabe')
+  })
+
+  it('prefers ?example= over field url params on init', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const state = usePrecompileState(config, examples, run)
+
+    await state.init({ queryExample: 'ex2', routeQuery: { a: 'deadbeef' } })
+
+    expect(run).toHaveBeenCalledWith('0xcafebabe')
+  })
+
+  it('falls back to default when ?example= is unknown', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const state = usePrecompileState(config, examples, run)
+
+    await state.init({ queryExample: 'missing' })
+
+    expect(state.example.value).toBe('ex1')
+    expect(run).toHaveBeenCalledWith('0xdeadbeef')
+  })
+
+  it('loads field url params when ?example= is absent', async () => {
+    const run = vi.fn().mockResolvedValue(undefined)
+    const state = usePrecompileState(config, examples, run)
+
+    await state.init({ routeQuery: { a: 'aabbccdd' } })
+
+    expect(run).toHaveBeenCalledWith('0xaabbccdd')
+  })
 })
diff --git a/src/eComponents/precompileInterfaceEC/usePrecompileState.ts b/src/eComponents/precompileInterfaceEC/usePrecompileState.ts
index 3a0e155..6fe75a4 100644
--- a/src/eComponents/precompileInterfaceEC/usePrecompileState.ts
+++ b/src/eComponents/precompileInterfaceEC/usePrecompileState.ts
@@ -1,12 +1,20 @@
 import { computed, ref, type ShallowRef, shallowRef } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
+import { useRouter } from 'vue-router'
 import type { PrefixedHexString } from '@ethereumjs/util'
 
 import type { Examples } from '@/explorations/REGISTRY'
+import { parseExampleQueryParam, resolveInitialExample } from '@/libs/exampleFromQuery'
 
 import type { PrecompileConfig } from './types'
 import { dataToValueInput, isValidByteInputForm, valueToDataInput } from './utils'
 
+export interface PrecompileInitOptions {
+  /** Value from `?example=` (parsed or raw string from route). */
+  queryExample?: string
+  /** Current route query — used for field-level share URL params on init. */
+  routeQuery?: Record<string, unknown>
+}
+
 function createState(config: PrecompileConfig) {
   return {
     data: ref(''),
@@ -28,9 +36,6 @@ export function usePrecompileState<T = unknown>(
   const { data, hexVals, bigIntVals, lengthsMask, byteLengths, example } = createState(config)
   const result: ShallowRef<T | undefined> = shallowRef()
 
-  const router = useRouter()
-  const route = useRoute()
-
   const editableIndices = config.values.map((v, i) => (v.urlParam ? i : -1)).filter((i) => i !== -1)
 
   const inputValues = computed(() =>
@@ -73,6 +78,7 @@ export function usePrecompileState<T = unknown>(
   }
 
   function shareURL() {
+    const router = useRouter()
     const query: Record<string, string> = {}
     for (const i of editableIndices) {
       query[config.values[i].urlParam!] = hexVals.value[i]
@@ -93,14 +99,22 @@ export function usePrecompileState<T = unknown>(
 
   // --- Initialization ---
 
-  async function init() {
+  async function init(options: PrecompileInitOptions = {}) {
+    const routeQuery = options.routeQuery ?? {}
+    const resolvedExample = parseExampleQueryParam(options.queryExample ?? routeQuery.example)
+    if (resolvedExample !== undefined) {
+      example.value = resolveInitialExample(examples, config.defaultExample, resolvedExample)
+      await selectExample()
+      return
+    }
+
     const urlParams = editableIndices.map((i) => config.values[i].urlParam!)
-    const hasAllParams = urlParams.length > 0 && urlParams.every((p) => p in route.query)
+    const hasAllParams = urlParams.length > 0 && urlParams.every((p) => p in routeQuery)
 
     if (hasAllParams) {
       try {
         for (const i of editableIndices) {
-          hexVals.value[i] = route.query[config.values[i].urlParam!]!.toString()
+          hexVals.value[i] = routeQuery[config.values[i].urlParam!]!.toString()
         }
         await values2Data()
       } catch {
diff --git a/src/eComponents/ui/ActionButtonUIC.vue b/src/eComponents/ui/ActionButtonUIC.vue
index 8826a4f..2661a9b 100644
--- a/src/eComponents/ui/ActionButtonUIC.vue
+++ b/src/eComponents/ui/ActionButtonUIC.vue
@@ -7,6 +7,7 @@ const props = defineProps<{
   text: string
   tooltip: string
   onClick: () => Promise<void>
+  testId?: string
 }>()
 
 const buttonText = ref(props.text)
@@ -29,7 +30,13 @@ async function handleClick() {
 </script>
 
 <template>
-  <button @click="handleClick" type="button" :disabled="isLoading" class="group e-action-button">
+  <button
+    @click="handleClick"
+    type="button"
+    :disabled="isLoading"
+    class="group e-action-button"
+    :data-testid="testId"
+  >
     {{ buttonText }}
     <TooltipUIC :tooltip="tooltip" />
   </button>
diff --git a/src/eComponents/ui/ExamplesUIC.vue b/src/eComponents/ui/ExamplesUIC.vue
index a2c4b8e..4398ce0 100644
--- a/src/eComponents/ui/ExamplesUIC.vue
+++ b/src/eComponents/ui/ExamplesUIC.vue
@@ -32,7 +32,7 @@ function onSelect(key: string) {
   <div class="text-right">
     <Listbox :model-value="example" @update:model-value="onSelect">
       <div class="relative inline-block">
-        <ListboxButton class="e-select inline-flex items-center gap-1">
+        <ListboxButton class="e-select inline-flex items-center gap-1" data-testid="example-select">
           {{ selectedTitle }}
           <ChevronUpDownIcon class="size-3.5 opacity-60" />
         </ListboxButton>
@@ -56,6 +56,7 @@ function onSelect(key: string) {
               as="template"
             >
               <li
+                :data-testid="`example-${key}`"
                 :class="[
                   'e-listbox-option cursor-pointer whitespace-nowrap select-none first:rounded-t-sm last:rounded-b-sm',
                   active ? 'e-listbox-option-active' : '',
diff --git a/src/explorations/ExplorationC.vue b/src/explorations/ExplorationC.vue
index a9e2cfc..db21090 100644
--- a/src/explorations/ExplorationC.vue
+++ b/src/explorations/ExplorationC.vue
@@ -29,7 +29,12 @@ const showUsage = computed(
 </script>
 
 <template>
-  <div :id="explorationId + '-c'" :style="cssVars" class="exploration-c">
+  <div
+    :id="explorationId + '-c'"
+    :style="cssVars"
+    class="exploration-c"
+    data-testid="exploration-ready"
+  >
     <div class="items-start gap-2 mb-2" :class="asPageTitle ? 'hidden md:flex' : 'flex'">
       <component
         :is="asPageTitle ? 'h1' : 'h3'"
diff --git a/src/explorations/eip-7594/MyC.vue b/src/explorations/eip-7594/MyC.vue
index 5cb2093..aef4c68 100644
--- a/src/explorations/eip-7594/MyC.vue
+++ b/src/explorations/eip-7594/MyC.vue
@@ -16,8 +16,10 @@ import ResultBoxUIC from '@/eComponents/ui/resultBox/ResultBoxUIC.vue'
 import ExplorationC from '@/explorations/ExplorationC.vue'
 import PoweredByC from '@/explorations/PoweredByC.vue'
 import { TOPICS } from '@/explorations/TOPICS'
+import { resolveInitialExample } from '@/libs/exampleFromQuery'
+import { useExplorationExampleQuery } from '@/libs/useExplorationExampleQuery'
 
-import { examples } from './examples'
+import { DEFAULT_EXAMPLE, examples } from './examples'
 import { INFO as exploration } from './info'
 
 const kzg = new microEthKZG(trustedSetup)
@@ -32,6 +34,7 @@ const errorMsg = ref('')
 const example = ref('')
 
 const topic = TOPICS[exploration.topic]
+const exampleQuery = useExplorationExampleQuery()
 const hasResult = computed(() => commitment.value !== '')
 
 function resetResults() {
@@ -71,7 +74,7 @@ async function run() {
 }
 
 async function init() {
-  example.value = 'blob1'
+  example.value = resolveInitialExample(examples, DEFAULT_EXAMPLE, exampleQuery)
   await selectExample()
 }
 
diff --git a/src/explorations/eip-7594/examples.ts b/src/explorations/eip-7594/examples.ts
index 2e51811..9f842c2 100644
--- a/src/explorations/eip-7594/examples.ts
+++ b/src/explorations/eip-7594/examples.ts
@@ -4,6 +4,8 @@ import blobBase from './data/blob_base.txt?raw'
 import blobGnosis from './data/blob_gnosis.txt?raw'
 import blobLighter from './data/blob_lighter.txt?raw'
 
+export const DEFAULT_EXAMPLE = 'blob1'
+
 export const examples: Examples = {
   blob1: {
     title: 'Base L2 Blob | Hash: 0x01ae971... | Block Nr: 23966811 | 2025-12-08',
diff --git a/src/explorations/eip-7928/MyC.vue b/src/explorations/eip-7928/MyC.vue
index 8c996eb..cc9426e 100644
--- a/src/explorations/eip-7928/MyC.vue
+++ b/src/explorations/eip-7928/MyC.vue
@@ -8,6 +8,8 @@ import ExplorationC from '@/explorations/ExplorationC.vue'
 import PoweredByC from '@/explorations/PoweredByC.vue'
 import { TOPICS } from '@/explorations/TOPICS'
 import { useCompanionStatusPublisher } from '@/libs/companionStatus'
+import { resolveInitialExample } from '@/libs/exampleFromQuery'
+import { useExplorationExampleQuery } from '@/libs/useExplorationExampleQuery'
 
 import BalExplorerPanel from './BalExplorerPanel.vue'
 import { DEFAULT_SCENARIO_ID, exampleMeta, examples } from './examples'
@@ -19,6 +21,7 @@ import type { ScenarioRunResult } from './scenarios/types'
 import { buildTriggerGroups } from './transitions'
 
 const topic = TOPICS[exploration.topic]
+const exampleQuery = useExplorationExampleQuery()
 
 const example = ref('')
 const errorMsg = ref('')
@@ -78,7 +81,7 @@ async function runBlock(): Promise<void> {
 }
 
 async function init() {
-  example.value = DEFAULT_SCENARIO_ID
+  example.value = resolveInitialExample(examples, DEFAULT_SCENARIO_ID, exampleQuery)
 }
 
 watch(
@@ -129,6 +132,7 @@ await init()
         <div class="flex items-center gap-2">
           <ExamplesUIC v-model="example" :examples="examples" :change="selectExample" />
           <ActionButtonUIC
+            test-id="run-block"
             text="Run block"
             tooltip="Execute block on Amsterdam VM and generate BAL"
             :onClick="runBlock"
diff --git a/src/explorations/eip-8024/MyC.vue b/src/explorations/eip-8024/MyC.vue
index 68946c1..98daed2 100644
--- a/src/explorations/eip-8024/MyC.vue
+++ b/src/explorations/eip-8024/MyC.vue
@@ -3,6 +3,7 @@ import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
 import { createEVM } from '@ethereumjs/evm'
 
 import BytecodeStepperEC from '@/eComponents/bytecodeStepperEC/BytecodeStepperEC.vue'
+import { useExplorationExampleQuery } from '@/libs/useExplorationExampleQuery'
 
 import { config } from './config'
 import { examples } from './examples'
@@ -11,10 +12,17 @@ import { INFO as exploration } from './info'
 
 const common = new Common({ chain: Mainnet, hardfork: Hardfork.Amsterdam })
 const evm = await createEVM({ common })
+const exampleQuery = useExplorationExampleQuery()
 </script>
 
 <template>
-  <BytecodeStepperEC :config="config" :examples="examples" :exploration="exploration" :evm="evm">
+  <BytecodeStepperEC
+    :config="config"
+    :examples="examples"
+    :exploration="exploration"
+    :evm="evm"
+    :example-query="exampleQuery"
+  >
     <template #below>
       <Teleport to="#exploration-right-panel">
         <ImmediateQuoVadis />
diff --git a/src/ice-cream/__tests__/IceCreamHomeSection.spec.ts b/src/ice-cream/__tests__/IceCreamHomeSection.spec.ts
new file mode 100644
index 0000000..36c3c4a
--- /dev/null
+++ b/src/ice-cream/__tests__/IceCreamHomeSection.spec.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+
+import IceCreamHomeSection from '../IceCreamHomeSection.vue'
+
+/**
+ * Home placement tests for this special action — keep here, not in HomeView.spec.ts.
+ * HomeView only tests permanent content; see docs/special-actions/index.md.
+ */
+describe('IceCreamHomeSection', () => {
+  it('renders the section label and stand widget', () => {
+    const wrapper = mount(IceCreamHomeSection)
+
+    expect(wrapper.find('[data-ice-cream-week]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('Ice Cream')
+    expect(wrapper.find('[data-ice-cream-stand]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('Buy Ice Cream')
+  })
+})
diff --git a/src/libs/__tests__/exampleFromQuery.explorations.spec.ts b/src/libs/__tests__/exampleFromQuery.explorations.spec.ts
new file mode 100644
index 0000000..ae022a7
--- /dev/null
+++ b/src/libs/__tests__/exampleFromQuery.explorations.spec.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_EXAMPLE as eip7594Default,
+  examples as eip7594Examples,
+} from '@/explorations/eip-7594/examples'
+import { config as eip7883Config } from '@/explorations/eip-7883/config'
+import { examples as eip7883Examples } from '@/explorations/eip-7883/examples'
+import {
+  DEFAULT_SCENARIO_ID as eip7928Default,
+  examples as eip7928Examples,
+} from '@/explorations/eip-7928/examples'
+import { config as eip7951Config } from '@/explorations/eip-7951/config'
+import { examples as eip7951Examples } from '@/explorations/eip-7951/examples'
+import { config as eip8024Config } from '@/explorations/eip-8024/config'
+import { examples as eip8024Examples } from '@/explorations/eip-8024/examples'
+import { resolveInitialExample } from '@/libs/exampleFromQuery'
+
+/** Every live exploration and its default example key. */
+const EXPLORATION_EXAMPLE_SETS = [
+  { id: 'eip-7594', defaultKey: eip7594Default, examples: eip7594Examples },
+  { id: 'eip-7883', defaultKey: eip7883Config.defaultExample, examples: eip7883Examples },
+  { id: 'eip-7928', defaultKey: eip7928Default, examples: eip7928Examples },
+  { id: 'eip-7951', defaultKey: eip7951Config.defaultExample, examples: eip7951Examples },
+  { id: 'eip-8024', defaultKey: eip8024Config.defaultExample, examples: eip8024Examples },
+] as const
+
+describe('?example= query param across explorations', () => {
+  for (const { id, defaultKey, examples } of EXPLORATION_EXAMPLE_SETS) {
+    describe(`exploration ${id}`, () => {
+      it('default example key exists in examples', () => {
+        expect(examples[defaultKey]).toBeDefined()
+      })
+
+      it('loads default when query is absent', () => {
+        expect(resolveInitialExample(examples, defaultKey)).toBe(defaultKey)
+      })
+
+      it('loads each example key from ?example= query', () => {
+        for (const key of Object.keys(examples)) {
+          expect(resolveInitialExample(examples, defaultKey, key)).toBe(key)
+        }
+      })
+
+      it('ignores invalid ?example= and falls back to default', () => {
+        expect(resolveInitialExample(examples, defaultKey, '__invalid__')).toBe(defaultKey)
+      })
+    })
+  }
+})
diff --git a/src/libs/__tests__/exampleFromQuery.spec.ts b/src/libs/__tests__/exampleFromQuery.spec.ts
new file mode 100644
index 0000000..5d7d54d
--- /dev/null
+++ b/src/libs/__tests__/exampleFromQuery.spec.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  EXAMPLE_QUERY_PARAM,
+  parseExampleQueryParam,
+  resolveInitialExample,
+} from '../exampleFromQuery'
+
+const examples = {
+  dupn: { title: 'DUPN', values: ['aa'] },
+  swapn: { title: 'SWAPN', values: ['bb'] },
+}
+
+describe('parseExampleQueryParam', () => {
+  it('returns undefined for missing or empty values', () => {
+    expect(parseExampleQueryParam(undefined)).toBeUndefined()
+    expect(parseExampleQueryParam('')).toBeUndefined()
+    expect(parseExampleQueryParam('   ')).toBeUndefined()
+  })
+
+  it('returns the string for valid example keys', () => {
+    expect(parseExampleQueryParam('dupn')).toBe('dupn')
+    expect(parseExampleQueryParam('invalid-dupn')).toBe('invalid-dupn')
+  })
+
+  it('does not coerce non-string query values', () => {
+    expect(parseExampleQueryParam(['dupn'])).toBeUndefined()
+    expect(parseExampleQueryParam(1)).toBeUndefined()
+  })
+})
+
+describe('resolveInitialExample', () => {
+  it('uses defaultExample when query is absent', () => {
+    expect(resolveInitialExample(examples, 'dupn')).toBe('dupn')
+  })
+
+  it('uses query example when it exists in examples', () => {
+    expect(resolveInitialExample(examples, 'dupn', 'swapn')).toBe('swapn')
+  })
+
+  it('falls back to defaultExample when query example is unknown', () => {
+    expect(resolveInitialExample(examples, 'dupn', 'not-a-key')).toBe('dupn')
+  })
+
+  it('falls back to first key when defaultExample is also invalid', () => {
+    expect(resolveInitialExample(examples, 'missing-default', 'also-missing')).toBe('dupn')
+  })
+})
+
+describe('EXAMPLE_QUERY_PARAM', () => {
+  it('is the documented query key', () => {
+    expect(EXAMPLE_QUERY_PARAM).toBe('example')
+  })
+})
diff --git a/src/libs/exampleFromQuery.ts b/src/libs/exampleFromQuery.ts
new file mode 100644
index 0000000..151a312
--- /dev/null
+++ b/src/libs/exampleFromQuery.ts
@@ -0,0 +1,30 @@
+import type { Examples } from '@/explorations/REGISTRY'
+
+/** URL query key for deep-linking to a specific exploration example preset. */
+export const EXAMPLE_QUERY_PARAM = 'example'
+
+/**
+ * Parse the `?example=` query value from vue-router's `route.query`.
+ * Returns `undefined` when absent or not a non-empty string.
+ */
+export function parseExampleQueryParam(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  return value
+}
+
+/**
+ * Resolve which example key to load on exploration init.
+ *
+ * - Uses `queryExample` when it matches a key in `examples`.
+ * - Falls back to `defaultExample` when the query is missing or invalid.
+ */
+export function resolveInitialExample(
+  examples: Examples,
+  defaultExample: string,
+  queryExample?: string,
+): string {
+  if (queryExample !== undefined && queryExample in examples) {
+    return queryExample
+  }
+  return defaultExample in examples ? defaultExample : (Object.keys(examples)[0] ?? '')
+}
diff --git a/src/libs/useExplorationExampleQuery.ts b/src/libs/useExplorationExampleQuery.ts
new file mode 100644
index 0000000..bca54e9
--- /dev/null
+++ b/src/libs/useExplorationExampleQuery.ts
@@ -0,0 +1,9 @@
+import { useRoute } from 'vue-router'
+
+import { parseExampleQueryParam } from '@/libs/exampleFromQuery'
+
+/** Read `?example=` from the current route for exploration deep-linking. */
+export function useExplorationExampleQuery(): string | undefined {
+  const route = useRoute()
+  return parseExampleQueryParam(route.query?.example)
+}
diff --git a/src/main.css b/src/main.css
index 9eb736c..60a7511 100644
--- a/src/main.css
+++ b/src/main.css
@@ -275,3 +275,189 @@ body {
     transition: none !important;
   }
 }
+
+/* --- Video capture mode (?fyp-video=1) --- */
+html.fyp-video-capture {
+  /* 540×960 preview — scale 1 (layout tuned for this reference size). */
+  --video-capture-scale: 1;
+  --video-safe-top: 56px;
+  --video-safe-bottom: 120px;
+  --video-safe-left: 32px;
+  --video-safe-right: 48px;
+  --video-top-banner-inset: 0px;
+  --video-top-banner-max-h: 184px;
+  --video-focus-gap: 12px;
+  --video-focus-scroll-margin: calc(
+    var(--video-safe-top) + var(--video-top-banner-max-h) + var(--video-focus-gap)
+  );
+}
+
+html.fyp-video-capture,
+html.fyp-video-capture body {
+  margin: 0 !important;
+  padding: 0 !important;
+  max-width: none !important;
+  width: 100% !important;
+  background: #000 !important;
+}
+
+html.fyp-video-capture [data-testid='example-select'] {
+  scroll-margin-top: var(--video-focus-scroll-margin);
+}
+
+html.fyp-video-capture body.container {
+  max-width: none !important;
+  padding: 0 !important;
+  background: #000 !important;
+}
+
+html.fyp-video-capture #app {
+  width: 100%;
+  max-width: none;
+  padding: 0;
+  margin: 0;
+  background: #000;
+}
+
+.fyp-video-mode .fyp-video-exploration {
+  grid-template-columns: 1fr !important;
+  gap: 0 !important;
+  width: 100%;
+  max-width: none;
+  padding: 0 !important;
+  margin: 0 !important;
+}
+
+.fyp-video-mode .fyp-video-exploration > div:first-child {
+  padding-bottom: var(--companion-peek-h, 56px);
+}
+
+.fyp-video-mode .exploration-c h1,
+.fyp-video-mode .exploration-c .hidden.md\:flex,
+.fyp-video-mode .exploration-c [class*='usage'],
+.fyp-video-mode .exploration-right-panel-host .max-md\:hidden,
+.fyp-video-mode .exploration-c > .items-start.gap-2,
+.fyp-video-mode .exploration-c > .font-mono {
+  display: none !important;
+}
+
+.fyp-video-mode .exploration-c {
+  border: none !important;
+  border-radius: 0 !important;
+}
+
+html.fyp-video-capture:not(.fyp-video-band-active) .exploration-right-panel-host {
+  visibility: hidden;
+}
+
+html.fyp-video-band-active .fyp-video-mode .fyp-video-exploration {
+  visibility: visible;
+}
+
+html.fyp-video-band-active .exploration-right-panel-host {
+  visibility: visible;
+}
+
+/* 1080×1920 full-res capture — scale fixed sizes from 540 reference. */
+@media (min-width: 541px) {
+  html.fyp-video-capture {
+    --video-capture-scale: calc(100vw / 540);
+    --video-safe-top: calc(56px * var(--video-capture-scale));
+    --video-safe-bottom: calc(120px * var(--video-capture-scale));
+    --video-safe-left: calc(32px * var(--video-capture-scale));
+    --video-safe-right: calc(48px * var(--video-capture-scale));
+    --video-top-banner-inset: 0px;
+    --video-top-banner-max-h: calc(184px * var(--video-capture-scale));
+    --video-focus-gap: calc(12px * var(--video-capture-scale));
+    height: 100vh;
+    overflow-x: hidden;
+  }
+
+  html.fyp-video-capture #app {
+    height: 100vh;
+    min-height: 100vh;
+  }
+
+  .fyp-video-mode {
+    height: 100vh;
+    min-height: 100vh;
+    width: 100%;
+    background: #000;
+  }
+
+  .fyp-video-mode .fyp-video-exploration {
+    height: 100vh;
+    min-height: 100vh;
+  }
+
+  html.fyp-video-capture .fyp-video-mode .lg\:grid-cols-2 {
+    grid-template-columns: repeat(1, minmax(0, 1fr)) !important;
+  }
+
+  html.fyp-video-capture .fyp-video-mode .grid.lg\:grid-cols-2 {
+    grid-template-columns: repeat(1, minmax(0, 1fr)) !important;
+  }
+
+  .fyp-video-mode .exploration-c {
+    padding-left: calc(0.5rem * var(--video-capture-scale));
+    padding-right: calc(0.5rem * var(--video-capture-scale));
+    font-size: calc(0.75rem * var(--video-capture-scale));
+  }
+
+  html.fyp-video-capture .exploration-right-panel-host {
+    position: fixed !important;
+    inset-inline: 0 !important;
+    bottom: var(--video-safe-bottom) !important;
+    top: auto !important;
+    z-index: 40 !important;
+    align-self: auto !important;
+    padding-left: var(--video-safe-left);
+    padding-right: var(--video-safe-right);
+    box-sizing: border-box;
+  }
+
+  html.fyp-video-capture .companion-sheet {
+    display: flex !important;
+    flex-direction: column !important;
+    min-height: 0 !important;
+    max-height: none !important;
+    background: #0a0a0a !important;
+    border-top: 1px solid rgb(38 38 38) !important;
+    border-radius: 0.75rem 0.75rem 0 0 !important;
+    box-shadow: 0 -8px 30px rgba(0, 0, 0, 0.45) !important;
+    overflow: hidden !important;
+  }
+
+  html.fyp-video-capture .companion-sheet-peek {
+    color: rgb(163 163 163) !important;
+  }
+
+  html.fyp-video-capture .companion-sheet .bg-slate-300 {
+    background-color: rgb(64 64 64) !important;
+  }
+
+  html.fyp-video-capture [data-testid='bytecode-disassembly'] {
+    max-height: min(36vh, calc(240px * var(--video-capture-scale))) !important;
+  }
+
+  html.fyp-video-capture [data-testid='bytecode-stack'] {
+    max-height: min(30vh, calc(200px * var(--video-capture-scale))) !important;
+  }
+
+  html.fyp-video-capture .fyp-video-mode textarea {
+    min-height: calc(3.5rem * var(--video-capture-scale));
+    font-size: calc(0.75rem * var(--video-capture-scale));
+  }
+
+  html.fyp-video-capture .companion-sheet > .flex-1 {
+    display: flex !important;
+    flex-direction: column !important;
+    flex: 1 1 auto !important;
+    min-height: 0 !important;
+    overflow-y: auto !important;
+  }
+
+  html.fyp-video-capture .companion-sheet > .shrink-0.touch-none {
+    display: block !important;
+  }
+}
diff --git a/src/video/VideoOverlay.vue b/src/video/VideoOverlay.vue
new file mode 100644
index 0000000..3a044c2
--- /dev/null
+++ b/src/video/VideoOverlay.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import VideoListFlashOverlay from './overlays/VideoListFlashOverlay.vue'
+import VideoOutroCard from './overlays/VideoOutroCard.vue'
+import VideoPunchOverlay from './overlays/VideoPunchOverlay.vue'
+import VideoSplitOverlay from './overlays/VideoSplitOverlay.vue'
+import VideoTitleCard from './overlays/VideoTitleCard.vue'
+import type { VideoOverlayDefinition, VideoOverlayPlacement } from './types'
+
+const props = defineProps<{
+  overlay: VideoOverlayDefinition
+  placement?: VideoOverlayPlacement
+}>()
+
+const resolvedType = computed(() => {
+  const t = props.overlay.type
+  if (t === 'title') return 'title-card'
+  if (t === 'outro') return 'outro-card'
+  if (t === 'highlight' || t === 'banner') return 'punch'
+  if (t === 'body' || t === 'callout') return props.overlay.segments?.length ? 'split' : 'split'
+  if (t === 'list') return 'list-flash'
+  return t
+})
+</script>
+
+<template>
+  <VideoTitleCard v-if="resolvedType === 'title-card'" :overlay="overlay" />
+  <VideoOutroCard v-else-if="resolvedType === 'outro-card'" :overlay="overlay" />
+  <VideoPunchOverlay
+    v-else-if="resolvedType === 'punch'"
+    :overlay="overlay"
+    :placement="placement"
+  />
+  <VideoSplitOverlay
+    v-else-if="resolvedType === 'split'"
+    :overlay="overlay"
+    :placement="placement"
+  />
+  <VideoListFlashOverlay
+    v-else-if="resolvedType === 'list-flash'"
+    :overlay="overlay"
+    :placement="placement"
+  />
+</template>
diff --git a/src/video/VideoShell.vue b/src/video/VideoShell.vue
new file mode 100644
index 0000000..71058a6
--- /dev/null
+++ b/src/video/VideoShell.vue
@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import './video.css'
+import { computed, onMounted, onUnmounted, ref, shallowRef, watch } from 'vue'
+
+import VideoAnnotation from './overlays/VideoAnnotation.vue'
+import VideoHighlights from './overlays/VideoHighlights.vue'
+import type {
+  ActiveVideoAnnotation,
+  ActiveVideoHighlightSet,
+  ActiveVideoOverlay,
+  ShowOverlayOptions,
+} from './types'
+import {
+  installVideoBridge,
+  readVideoConfigFromWindow,
+  resolveActiveAnnotation,
+  resolveActiveHighlightSet,
+  resolveActiveOverlay,
+} from './videoBridge'
+import VideoOverlay from './VideoOverlay.vue'
+
+const activeOverlay = shallowRef<ActiveVideoOverlay | null>(null)
+const activeAnnotation = shallowRef<ActiveVideoAnnotation | null>(null)
+const activeHighlightSet = shallowRef<ActiveVideoHighlightSet | null>(null)
+const config = ref(readVideoConfigFromWindow())
+
+const themeVars = computed(() => {
+  const theme = config.value?.theme
+  if (!theme) return {}
+  return { '--video-accent': theme.accent }
+})
+
+const isFullScreenCard = computed(() => {
+  const type = activeOverlay.value?.definition.type
+  return type === 'title-card' || type === 'title' || type === 'outro-card' || type === 'outro'
+})
+
+const showGuideLayers = computed(() => !isFullScreenCard.value)
+
+function showOverlay(id: string, options?: ShowOverlayOptions) {
+  activeOverlay.value = resolveActiveOverlay(config.value, id, options)
+}
+
+function hideOverlay() {
+  activeOverlay.value = null
+}
+
+function showAnnotation(id: string) {
+  activeAnnotation.value = resolveActiveAnnotation(config.value, id)
+}
+
+function hideAnnotation() {
+  activeAnnotation.value = null
+}
+
+function showHighlightSet(id: string) {
+  activeHighlightSet.value = resolveActiveHighlightSet(config.value, id)
+}
+
+function hideHighlights() {
+  activeHighlightSet.value = null
+}
+
+function isReady() {
+  return document.querySelector('[data-testid="exploration-ready"]') !== null
+}
+
+let uninstallBridge: (() => void) | undefined
+
+watch(isFullScreenCard, (full) => {
+  document.documentElement.classList.toggle('fyp-video-band-active', full)
+  const type = activeOverlay.value?.definition.type
+  if (full && (type === 'title-card' || type === 'title')) {
+    window.scrollTo(0, 0)
+  }
+})
+
+onMounted(() => {
+  config.value = readVideoConfigFromWindow()
+  uninstallBridge = installVideoBridge({
+    onShowOverlay: showOverlay,
+    onHideOverlay: hideOverlay,
+    onShowAnnotation: showAnnotation,
+    onHideAnnotation: hideAnnotation,
+    onShowHighlightSet: showHighlightSet,
+    onHideHighlights: hideHighlights,
+    isReady,
+  })
+})
+
+onUnmounted(() => {
+  document.documentElement.classList.remove('fyp-video-band-active')
+  uninstallBridge?.()
+})
+</script>
+
+<template>
+  <div
+    class="video-shell pointer-events-none fixed inset-0 z-50"
+    data-testid="video-shell"
+    aria-hidden="true"
+    :style="themeVars"
+  >
+    <VideoOverlay v-if="activeOverlay && isFullScreenCard" :overlay="activeOverlay.definition" />
+    <div v-else-if="activeOverlay" class="video-float-layer">
+      <VideoOverlay :overlay="activeOverlay.definition" :placement="activeOverlay.placement" />
+    </div>
+    <VideoHighlights
+      v-if="showGuideLayers && activeHighlightSet"
+      :set-id="activeHighlightSet.id"
+      :marks="activeHighlightSet.marks"
+      :focus-areas="config?.focusAreas"
+    />
+    <VideoAnnotation
+      v-if="showGuideLayers && activeAnnotation"
+      :annotation="activeAnnotation!.definition"
+      :focus-areas="config?.focusAreas"
+    />
+  </div>
+</template>
diff --git a/src/video/__tests__/splitText.spec.ts b/src/video/__tests__/splitText.spec.ts
new file mode 100644
index 0000000..4461dcc
--- /dev/null
+++ b/src/video/__tests__/splitText.spec.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { autoSplitText } from '../splitText'
+
+describe('autoSplitText', () => {
+  it('keeps short phrases in one hero segment', () => {
+    const segs = autoSplitText('DUPN')
+    expect(segs).toHaveLength(1)
+    expect(segs[0]?.emphasis).toBe(true)
+  })
+
+  it('splits long sentences into staggered a/b slots', () => {
+    const segs = autoSplitText('17 pushes — the stack is getting DEEP')
+    expect(segs).toHaveLength(2)
+    expect(segs[0]?.slot).toBe('a')
+    expect(segs[1]?.slot).toBe('b')
+    expect(segs[1]?.emphasis).toBe(true)
+  })
+})
diff --git a/src/video/__tests__/useVideoMode.spec.ts b/src/video/__tests__/useVideoMode.spec.ts
new file mode 100644
index 0000000..fe0734d
--- /dev/null
+++ b/src/video/__tests__/useVideoMode.spec.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+
+import { FYP_VIDEO_QUERY_PARAM, isVideoModeQuery } from '../useVideoMode'
+
+describe('isVideoModeQuery', () => {
+  it('activates for fyp-video=1, true, or empty string', () => {
+    expect(isVideoModeQuery({ [FYP_VIDEO_QUERY_PARAM]: '1' })).toBe(true)
+    expect(isVideoModeQuery({ [FYP_VIDEO_QUERY_PARAM]: 'true' })).toBe(true)
+    expect(isVideoModeQuery({ [FYP_VIDEO_QUERY_PARAM]: '' })).toBe(true)
+  })
+
+  it('is inactive when param is absent or other values', () => {
+    expect(isVideoModeQuery({})).toBe(false)
+    expect(isVideoModeQuery({ [FYP_VIDEO_QUERY_PARAM]: '0' })).toBe(false)
+    expect(isVideoModeQuery({ [FYP_VIDEO_QUERY_PARAM]: 'false' })).toBe(false)
+    expect(isVideoModeQuery({ example: 'dupn' })).toBe(false)
+  })
+})
+
+describe('FYP_VIDEO_QUERY_PARAM', () => {
+  it('is the documented query key', () => {
+    expect(FYP_VIDEO_QUERY_PARAM).toBe('fyp-video')
+  })
+})
diff --git a/src/video/__tests__/videoBridge.spec.ts b/src/video/__tests__/videoBridge.spec.ts
new file mode 100644
index 0000000..c00b976
--- /dev/null
+++ b/src/video/__tests__/videoBridge.spec.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { VideoContentConfig } from '../types'
+import {
+  createVideoBridge,
+  resolveActiveHighlightSet,
+  resolveActiveOverlay,
+  type VideoBridgeHandlers,
+} from '../videoBridge'
+
+const sampleConfig: VideoContentConfig = {
+  explorationId: 'eip-8024',
+  overlays: {
+    hook: {
+      id: 'hook',
+      type: 'title',
+      lines: ['EIP-8024'],
+      question: 'Stack too deep?',
+    },
+  },
+  highlightSets: {
+    'dupn-windup': {
+      id: 'dupn-windup',
+      marks: [{ target: 'stack-depth-17' }],
+    },
+  },
+}
+
+describe('resolveActiveOverlay', () => {
+  it('returns null when config or id is missing', () => {
+    expect(resolveActiveOverlay(undefined, 'hook')).toBeNull()
+    expect(resolveActiveOverlay(sampleConfig, null)).toBeNull()
+  })
+
+  it('returns null for unknown overlay id', () => {
+    expect(resolveActiveOverlay(sampleConfig, 'missing')).toBeNull()
+  })
+
+  it('returns active overlay for known id', () => {
+    const active = resolveActiveOverlay(sampleConfig, 'hook')
+    expect(active?.id).toBe('hook')
+    expect(active?.definition.type).toBe('title')
+  })
+})
+
+describe('resolveActiveHighlightSet', () => {
+  it('returns null when config or id is missing', () => {
+    expect(resolveActiveHighlightSet(undefined, 'dupn-windup')).toBeNull()
+    expect(resolveActiveHighlightSet(sampleConfig, null)).toBeNull()
+  })
+
+  it('returns active highlight set for known id', () => {
+    const active = resolveActiveHighlightSet(sampleConfig, 'dupn-windup')
+    expect(active?.id).toBe('dupn-windup')
+    expect(active?.marks).toHaveLength(1)
+  })
+})
+
+describe('createVideoBridge', () => {
+  it('delegates show/hide to handlers and reports ready state', async () => {
+    const handlers: VideoBridgeHandlers = {
+      onShowOverlay: vi.fn(),
+      onHideOverlay: vi.fn(),
+      onShowAnnotation: vi.fn(),
+      onHideAnnotation: vi.fn(),
+      onShowHighlightSet: vi.fn(),
+      onHideHighlights: vi.fn(),
+      isReady: vi.fn(() => true),
+    }
+    const bridge = createVideoBridge(handlers)
+
+    await bridge.showOverlay('hook', { placement: 'top-banner' })
+    expect(handlers.onShowOverlay).toHaveBeenCalledWith('hook', { placement: 'top-banner' })
+
+    await bridge.hideOverlay()
+    expect(handlers.onHideOverlay).toHaveBeenCalled()
+
+    await bridge.showAnnotation('guide-stack')
+    expect(handlers.onShowAnnotation).toHaveBeenCalledWith('guide-stack')
+
+    await bridge.hideAnnotation()
+    expect(handlers.onHideAnnotation).toHaveBeenCalled()
+
+    await bridge.showHighlightSet('dupn-windup')
+    expect(handlers.onShowHighlightSet).toHaveBeenCalledWith('dupn-windup')
+
+    await bridge.hideHighlights()
+    expect(handlers.onHideHighlights).toHaveBeenCalled()
+
+    expect(bridge.ready()).toBe(true)
+  })
+
+  it('wait resolves after the requested delay', async () => {
+    vi.useFakeTimers()
+    const bridge = createVideoBridge({
+      onShowOverlay: vi.fn(),
+      onHideOverlay: vi.fn(),
+      onShowAnnotation: vi.fn(),
+      onHideAnnotation: vi.fn(),
+      onShowHighlightSet: vi.fn(),
+      onHideHighlights: vi.fn(),
+      isReady: () => true,
+    })
+
+    const pending = bridge.wait(500)
+    vi.advanceTimersByTime(500)
+    await expect(pending).resolves.toBeUndefined()
+    vi.useRealTimers()
+  })
+})
diff --git a/src/video/annotationTarget.ts b/src/video/annotationTarget.ts
new file mode 100644
index 0000000..2a90606
--- /dev/null
+++ b/src/video/annotationTarget.ts
@@ -0,0 +1,82 @@
+import type { VideoFocusAreaRef } from './types'
+
+/** Resolve a zone key, live target alias, or raw CSS selector. */
+export function resolveTargetSelector(
+  target: string,
+  focusAreas?: Record<string, VideoFocusAreaRef>,
+): string {
+  if (target === 'disassembly-active') return '[data-disassembly-active="true"]'
+  if (target === 'disassembly-active-opcode') {
+    return '[data-disassembly-active="true"] [data-disassembly-opcode]'
+  }
+  if (target === 'disassembly-dupn') {
+    return '[data-disassembly-opcode][data-disassembly-mnemonic*="DUPN"]'
+  }
+  if (target === 'stack-top') return '[data-stack-depth="1"]'
+  if (target === 'stack-top-value') return '[data-stack-depth="1"] [data-stack-value]'
+  const depthValueMatch = /^stack-depth-(\d+)-value$/.exec(target)
+  if (depthValueMatch) {
+    return `[data-stack-depth="${depthValueMatch[1]}"] [data-stack-value]`
+  }
+  const depthMatch = /^stack-depth-(\d+)$/.exec(target)
+  if (depthMatch) return `[data-stack-depth="${depthMatch[1]}"]`
+
+  const fromZone = focusAreas?.[target]?.selector
+  if (fromZone) return fromZone
+  if (target.startsWith('[') || target.startsWith('.') || target.startsWith('#')) return target
+  return `[data-testid="${target}"]`
+}
+
+export type AnnotationCalloutSide = 'top' | 'bottom' | 'left' | 'right'
+
+export function pickCalloutSide(
+  rect: DOMRect,
+  viewportH: number,
+  preferred?: AnnotationCalloutSide | 'auto',
+): AnnotationCalloutSide {
+  if (preferred && preferred !== 'auto') return preferred
+
+  const spaceAbove = rect.top
+  const spaceBelow = viewportH - rect.bottom
+  const spaceLeft = rect.left
+  const spaceRight = window.innerWidth - rect.right
+
+  if (rect.top > viewportH * 0.55) return 'top'
+  if (rect.bottom < viewportH * 0.35) return 'bottom'
+
+  const maxVertical = Math.max(spaceAbove, spaceBelow)
+  const maxHorizontal = Math.max(spaceLeft, spaceRight)
+  if (maxHorizontal > maxVertical + 40) {
+    return spaceRight >= spaceLeft ? 'right' : 'left'
+  }
+  return spaceBelow >= spaceAbove ? 'bottom' : 'top'
+}
+
+const TOP_BANNER_SELECTORS = [
+  '.video-float-layer .video-banner--top-banner',
+  '.video-float-layer .video-punch--top-banner',
+]
+
+/** Story overlays at the top — annotations must not draw over these. */
+export function collectTopBannerRects(root: ParentNode = document): DOMRect[] {
+  const rects: DOMRect[] = []
+  for (const sel of TOP_BANNER_SELECTORS) {
+    for (const el of root.querySelectorAll(sel)) {
+      const rect = el.getBoundingClientRect()
+      if (rect.width > 0 && rect.height > 0) rects.push(rect)
+    }
+  }
+  return rects
+}
+
+export function targetOverlapsTopBanner(
+  target: DOMRect,
+  bannerRects: DOMRect[],
+  gapPx = 12,
+): boolean {
+  for (const banner of bannerRects) {
+    const hOverlap = target.left < banner.right && target.right > banner.left
+    if (hOverlap && target.top < banner.bottom + gapPx) return true
+  }
+  return false
+}
diff --git a/src/video/companionSheetEvents.ts b/src/video/companionSheetEvents.ts
new file mode 100644
index 0000000..dd7bdcf
--- /dev/null
+++ b/src/video/companionSheetEvents.ts
@@ -0,0 +1,7 @@
+export const COMPANION_EXPAND_EVENT = 'fyp:companion-expand'
+
+export type CompanionExpandMode = 'half' | 'full'
+
+export function dispatchCompanionExpand(mode: CompanionExpandMode): void {
+  window.dispatchEvent(new CustomEvent(COMPANION_EXPAND_EVENT, { detail: { mode } }))
+}
diff --git a/src/video/overlays/VideoAnnotation.vue b/src/video/overlays/VideoAnnotation.vue
new file mode 100644
index 0000000..831bf33
--- /dev/null
+++ b/src/video/overlays/VideoAnnotation.vue
@@ -0,0 +1,147 @@
+<script setup lang="ts">
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
+
+import {
+  collectTopBannerRects,
+  pickCalloutSide,
+  resolveTargetSelector,
+  targetOverlapsTopBanner,
+} from '../annotationTarget'
+import type { VideoAnnotationDefinition, VideoFocusAreaRef } from '../types'
+
+const props = defineProps<{
+  annotation: VideoAnnotationDefinition
+  focusAreas?: Record<string, VideoFocusAreaRef>
+}>()
+
+const targetRect = ref<DOMRect | null>(null)
+const calloutSide = ref<'top' | 'bottom' | 'left' | 'right'>('bottom')
+const suppressedByBanner = ref(false)
+
+const selector = computed(() => resolveTargetSelector(props.annotation.target, props.focusAreas))
+
+function measure() {
+  const el = document.querySelector(selector.value)
+  if (!el) {
+    targetRect.value = null
+    return
+  }
+  const rect = el.getBoundingClientRect()
+  if (rect.width <= 0 && rect.height <= 0) {
+    targetRect.value = null
+    return
+  }
+  targetRect.value = rect
+  calloutSide.value = pickCalloutSide(rect, window.innerHeight, props.annotation.side)
+  suppressedByBanner.value = targetOverlapsTopBanner(rect, collectTopBannerRects())
+}
+
+const visible = computed(() => targetRect.value !== null && !suppressedByBanner.value)
+
+let observer: ResizeObserver | undefined
+let raf = 0
+
+function scheduleMeasure() {
+  cancelAnimationFrame(raf)
+  raf = requestAnimationFrame(measure)
+}
+
+watch(selector, () => {
+  observer?.disconnect()
+  observer = new ResizeObserver(scheduleMeasure)
+  const el = document.querySelector(selector.value)
+  if (el) observer.observe(el)
+  scheduleMeasure()
+})
+
+let overlayObserver: MutationObserver | undefined
+
+onMounted(() => {
+  scheduleMeasure()
+  window.addEventListener('scroll', scheduleMeasure, { passive: true, capture: true })
+  window.addEventListener('resize', scheduleMeasure, { passive: true })
+  observer = new ResizeObserver(scheduleMeasure)
+  const el = document.querySelector(selector.value)
+  if (el) observer.observe(el)
+
+  const floatLayer = document.querySelector('.video-float-layer')
+  if (floatLayer) {
+    overlayObserver = new MutationObserver(scheduleMeasure)
+    overlayObserver.observe(floatLayer, { childList: true, subtree: true, attributes: true })
+  }
+})
+
+onUnmounted(() => {
+  cancelAnimationFrame(raf)
+  observer?.disconnect()
+  overlayObserver?.disconnect()
+  window.removeEventListener('scroll', scheduleMeasure, true)
+  window.removeEventListener('resize', scheduleMeasure)
+})
+
+const highlightStyle = computed(() => {
+  const r = targetRect.value
+  if (!r) return { display: 'none' }
+  return {
+    top: `${r.top}px`,
+    left: `${r.left}px`,
+    width: `${r.width}px`,
+    height: `${r.height}px`,
+  }
+})
+
+const CALLOUT_GAP = 10
+
+const calloutStyle = computed(() => {
+  const r = targetRect.value
+  if (!r) return { display: 'none' }
+  const side = calloutSide.value
+  if (side === 'bottom') {
+    return {
+      top: `${r.bottom + CALLOUT_GAP}px`,
+      left: `${r.left + r.width / 2}px`,
+      transform: 'translateX(-50%)',
+    }
+  }
+  if (side === 'top') {
+    return {
+      top: `${r.top - CALLOUT_GAP}px`,
+      left: `${r.left + r.width / 2}px`,
+      transform: 'translate(-50%, -100%)',
+    }
+  }
+  if (side === 'right') {
+    return {
+      top: `${r.top + r.height / 2}px`,
+      left: `${r.right + CALLOUT_GAP}px`,
+      transform: 'translateY(-50%)',
+    }
+  }
+  return {
+    top: `${r.top + r.height / 2}px`,
+    left: `${r.left - CALLOUT_GAP}px`,
+    transform: 'translate(-100%, -50%)',
+  }
+})
+</script>
+
+<template>
+  <div class="video-annotation-layer" :data-testid="`video-annotation-${annotation.id}`">
+    <div
+      v-if="visible"
+      class="video-annotation-highlight"
+      :style="highlightStyle"
+      aria-hidden="true"
+    />
+    <div
+      v-if="visible"
+      class="video-annotation-callout"
+      :class="`video-annotation-callout--${calloutSide}`"
+      :style="calloutStyle"
+    >
+      <span class="video-annotation-callout__arrow" aria-hidden="true" />
+      <p class="video-annotation-callout__label">{{ annotation.label }}</p>
+      <p v-if="annotation.hint" class="video-annotation-callout__hint">{{ annotation.hint }}</p>
+    </div>
+  </div>
+</template>
diff --git a/src/video/overlays/VideoBandShell.vue b/src/video/overlays/VideoBandShell.vue
new file mode 100644
index 0000000..bdc65e5
--- /dev/null
+++ b/src/video/overlays/VideoBandShell.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+defineProps<{
+  testId: string
+  contentClass?: string
+}>()
+</script>
+
+<template>
+  <div class="video-card-band">
+    <div class="video-card-band__peek video-card-band__peek--top" aria-hidden="true" />
+    <div class="video-card-band__content" :class="contentClass" :data-testid="testId">
+      <slot />
+    </div>
+    <div class="video-card-band__peek video-card-band__peek--bottom" aria-hidden="true" />
+  </div>
+</template>
diff --git a/src/video/overlays/VideoHighlightMark.vue b/src/video/overlays/VideoHighlightMark.vue
new file mode 100644
index 0000000..28b85b0
--- /dev/null
+++ b/src/video/overlays/VideoHighlightMark.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { computed, toRef } from 'vue'
+
+import { resolveTargetSelector } from '../annotationTarget'
+import type { VideoFocusAreaRef, VideoHighlightMarkDefinition } from '../types'
+import { useTargetRect } from '../useTargetRect'
+
+const props = defineProps<{
+  mark: VideoHighlightMarkDefinition
+  focusAreas?: Record<string, VideoFocusAreaRef>
+  index?: number
+}>()
+
+const selector = computed(() => resolveTargetSelector(props.mark.target, props.focusAreas))
+
+const targetRect = useTargetRect(toRef(selector))
+
+const markStyle = computed(() => {
+  const r = targetRect.value
+  if (!r) return { display: 'none' }
+  const padX = props.mark.padX ?? props.mark.pad ?? 10
+  const padY = props.mark.padY ?? props.mark.pad ?? 12
+  return {
+    top: `${r.top - padY}px`,
+    left: `${r.left - padX}px`,
+    width: `${r.width + padX * 2}px`,
+    height: `${r.height + padY * 2}px`,
+  }
+})
+</script>
+
+<template>
+  <div v-if="targetRect" class="video-highlight-mark" :style="markStyle" aria-hidden="true" />
+</template>
diff --git a/src/video/overlays/VideoHighlights.vue b/src/video/overlays/VideoHighlights.vue
new file mode 100644
index 0000000..6dffc6f
--- /dev/null
+++ b/src/video/overlays/VideoHighlights.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import type { VideoFocusAreaRef, VideoHighlightMarkDefinition } from '../types'
+import VideoHighlightMark from './VideoHighlightMark.vue'
+
+defineProps<{
+  setId: string
+  marks: VideoHighlightMarkDefinition[]
+  focusAreas?: Record<string, VideoFocusAreaRef>
+}>()
+</script>
+
+<template>
+  <div class="video-highlight-layer" :data-testid="`video-highlights-${setId}`">
+    <VideoHighlightMark
+      v-for="(mark, i) in marks"
+      :key="`${mark.target}-${i}`"
+      :mark="mark"
+      :index="i"
+      :focus-areas="focusAreas"
+    />
+  </div>
+</template>
diff --git a/src/video/overlays/VideoListFlashOverlay.vue b/src/video/overlays/VideoListFlashOverlay.vue
new file mode 100644
index 0000000..abea1a8
--- /dev/null
+++ b/src/video/overlays/VideoListFlashOverlay.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import type { VideoOverlayDefinition, VideoOverlayPlacement } from '../types'
+
+const props = defineProps<{
+  overlay: VideoOverlayDefinition
+  placement?: VideoOverlayPlacement
+}>()
+
+const effectivePlacement = computed(
+  () => props.placement ?? props.overlay.placement ?? 'top-banner',
+)
+
+const bannerClass = computed(() =>
+  effectivePlacement.value === 'bottom-banner'
+    ? 'video-banner--bottom-banner'
+    : 'video-banner--top-banner',
+)
+</script>
+
+<template>
+  <div class="video-banner video-banner--list" :class="bannerClass">
+    <p v-if="overlay.headline" class="video-banner__line video-banner__line--accent">
+      {{ overlay.headline }}
+    </p>
+    <p
+      v-for="(item, i) in overlay.items"
+      :key="i"
+      class="video-banner__line video-banner__line--sub"
+    >
+      {{ item }}
+    </p>
+  </div>
+</template>
diff --git a/src/video/overlays/VideoOutroCard.vue b/src/video/overlays/VideoOutroCard.vue
new file mode 100644
index 0000000..5f3a08b
--- /dev/null
+++ b/src/video/overlays/VideoOutroCard.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import type { VideoOutroCta, VideoOverlayDefinition } from '../types'
+import VideoBandShell from './VideoBandShell.vue'
+
+const props = defineProps<{
+  overlay: VideoOverlayDefinition
+}>()
+
+const ctas = computed((): VideoOutroCta[] => {
+  if (props.overlay.ctas?.length) return props.overlay.ctas
+  const legacy: VideoOutroCta[] = []
+  if (props.overlay.secondary) {
+    legacy.push({
+      label: 'READ ABOUT THE EIP',
+      url: props.overlay.secondary.toUpperCase(),
+      variant: 'secondary',
+    })
+  }
+  if (props.overlay.primary && props.overlay.cta) {
+    legacy.push({
+      label: props.overlay.primary.toUpperCase(),
+      url: props.overlay.cta.toUpperCase(),
+      variant: 'primary',
+    })
+  }
+  return legacy
+})
+</script>
+
+<template>
+  <VideoBandShell test-id="video-outro-card" content-class="video-card-band__content--outro">
+    <p v-if="overlay.closing" class="video-card-band__closing">{{ overlay.closing }}</p>
+
+    <div v-if="ctas.length" class="video-card-band__ctas">
+      <div
+        v-for="(cta, i) in ctas"
+        :key="i"
+        class="video-card-band__cta"
+        :class="cta.variant === 'secondary' ? 'video-card-band__cta--secondary' : ''"
+      >
+        <p class="video-card-band__cta-label">{{ cta.label }}</p>
+        <p class="video-card-band__cta-url">{{ cta.url }}</p>
+      </div>
+    </div>
+  </VideoBandShell>
+</template>
diff --git a/src/video/overlays/VideoPunchOverlay.vue b/src/video/overlays/VideoPunchOverlay.vue
new file mode 100644
index 0000000..b0f5007
--- /dev/null
+++ b/src/video/overlays/VideoPunchOverlay.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import type { VideoOverlayDefinition, VideoOverlayPlacement } from '../types'
+
+const props = defineProps<{
+  overlay: VideoOverlayDefinition
+  placement?: VideoOverlayPlacement
+}>()
+
+const positionClass = computed(() => {
+  const p = props.placement ?? props.overlay.placement ?? props.overlay.position ?? 'top'
+  if (p === 'top-banner') return 'video-punch--top-banner'
+  if (p === 'bottom-banner') return 'video-punch--bottom-banner'
+  return `video-punch--${p === 'top' || p === 'center' || p === 'bottom' ? p : 'top'}`
+})
+</script>
+
+<template>
+  <div class="video-punch" :class="positionClass">
+    <p class="video-punch__text" :class="overlay.invert ? 'video-punch__text--white' : ''">
+      {{ overlay.text }}
+    </p>
+    <p v-if="overlay.sub" class="video-punch__sub">{{ overlay.sub }}</p>
+  </div>
+</template>
diff --git a/src/video/overlays/VideoSplitOverlay.vue b/src/video/overlays/VideoSplitOverlay.vue
new file mode 100644
index 0000000..eb15bde
--- /dev/null
+++ b/src/video/overlays/VideoSplitOverlay.vue
@@ -0,0 +1,77 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import { autoSplitText } from '../splitText'
+import type { VideoOverlayDefinition, VideoOverlayPlacement } from '../types'
+
+const props = defineProps<{
+  overlay: VideoOverlayDefinition
+  placement?: VideoOverlayPlacement
+}>()
+
+const SLOT_ORDER: Array<'a' | 'b' | 'c'> = ['a', 'b', 'c']
+
+function sizeClass(
+  size: NonNullable<typeof props.overlay.segments>[number]['size'] = 'lg',
+): string {
+  if (size === 'hero') return 'video-split__text--hero'
+  if (size === 'xl') return 'video-split__text--xl'
+  if (size === 'md') return 'video-banner__line--sub'
+  return 'video-split__text--lg'
+}
+
+const effectivePlacement = computed(
+  () => props.placement ?? props.overlay.placement ?? 'top-banner',
+)
+
+const useBannerLayout = computed(() => {
+  if (props.overlay.layout === 'scatter') return false
+  if (props.overlay.layout === 'banner') return true
+  const p = effectivePlacement.value
+  return p === 'top-banner' || p === 'bottom-banner'
+})
+
+const segments = computed(() => {
+  if (props.overlay.segments?.length) return props.overlay.segments
+  if (props.overlay.text) return autoSplitText(props.overlay.text)
+  return []
+})
+
+const bannerClass = computed(() =>
+  effectivePlacement.value === 'bottom-banner'
+    ? 'video-banner--bottom-banner'
+    : 'video-banner--top-banner',
+)
+</script>
+
+<template>
+  <div v-if="useBannerLayout" class="video-banner" :class="bannerClass" data-testid="video-banner">
+    <p
+      v-for="(seg, i) in segments"
+      :key="i"
+      class="video-banner__line"
+      :class="[
+        sizeClass(seg.size),
+        seg.emphasis ? 'video-banner__line--accent' : '',
+        i > 0 ? 'video-banner__line--sub' : '',
+      ]"
+    >
+      {{ seg.text }}
+    </p>
+  </div>
+  <div v-else class="video-split">
+    <div
+      v-for="(seg, i) in segments"
+      :key="i"
+      class="video-split__part"
+      :class="`video-split__part--${seg.slot ?? SLOT_ORDER[i] ?? 'a'}`"
+    >
+      <p
+        class="video-split__text"
+        :class="[sizeClass(seg.size), seg.emphasis ? 'video-split__text--accent' : '']"
+      >
+        {{ seg.text }}
+      </p>
+    </div>
+  </div>
+</template>
diff --git a/src/video/overlays/VideoTitleCard.vue b/src/video/overlays/VideoTitleCard.vue
new file mode 100644
index 0000000..ed9f91f
--- /dev/null
+++ b/src/video/overlays/VideoTitleCard.vue
@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import type { VideoOverlayDefinition } from '../types'
+import VideoBandShell from './VideoBandShell.vue'
+
+defineProps<{
+  overlay: VideoOverlayDefinition
+}>()
+</script>
+
+<template>
+  <VideoBandShell test-id="video-title-card">
+    <p v-if="overlay.eyebrow" class="video-card-band__eyebrow">{{ overlay.eyebrow }}</p>
+    <h1 v-if="overlay.title" class="video-card-band__title">{{ overlay.title }}</h1>
+    <p v-else-if="overlay.lines?.[0]" class="video-card-band__title">{{ overlay.lines[0] }}</p>
+
+    <p v-if="overlay.subtitle" class="video-card-band__subtitle">{{ overlay.subtitle }}</p>
+    <p v-else-if="overlay.lines?.[1]" class="video-card-band__subtitle">{{ overlay.lines[1] }}</p>
+
+    <div v-if="overlay.hook?.length" class="video-card-band__hook">
+      <p
+        v-for="(line, i) in overlay.hook"
+        :key="i"
+        class="video-card-band__hook-line"
+        :class="i === overlay.hook!.length - 1 ? 'video-card-band__hook-line--accent' : ''"
+      >
+        {{ line }}
+      </p>
+    </div>
+    <p
+      v-else-if="overlay.question"
+      class="video-card-band__hook-line video-card-band__hook-line--accent"
+    >
+      {{ overlay.question }}
+    </p>
+  </VideoBandShell>
+</template>
diff --git a/src/video/splitText.ts b/src/video/splitText.ts
new file mode 100644
index 0000000..d715810
--- /dev/null
+++ b/src/video/splitText.ts
@@ -0,0 +1,15 @@
+import type { VideoTextSegment } from './types'
+
+/** Split long copy into staggered upper-left / lower-right segments. */
+export function autoSplitText(text: string): VideoTextSegment[] {
+  const trimmed = text.trim()
+  const words = trimmed.split(/\s+/)
+  if (words.length <= 3) {
+    return [{ text: trimmed, size: 'xl', emphasis: true, slot: 'a' }]
+  }
+  const mid = Math.ceil(words.length / 2)
+  return [
+    { text: words.slice(0, mid).join(' '), size: 'lg', slot: 'a' },
+    { text: words.slice(mid).join(' '), size: 'hero', emphasis: true, slot: 'b' },
+  ]
+}
diff --git a/src/video/types.ts b/src/video/types.ts
new file mode 100644
index 0000000..c6cd48c
--- /dev/null
+++ b/src/video/types.ts
@@ -0,0 +1,139 @@
+export type VideoOverlayType =
+  | 'title-card'
+  | 'outro-card'
+  | 'punch'
+  | 'split'
+  | 'callout'
+  | 'list-flash'
+  | 'banner'
+  /** @deprecated use title-card / punch / split */
+  | 'title'
+  | 'body'
+  | 'highlight'
+  | 'list'
+  | 'outro'
+
+/** Where floating overlays sit so they avoid the focus area on screen. */
+export type VideoOverlayPlacement = 'top-banner' | 'bottom-banner' | 'top' | 'center' | 'bottom'
+
+export interface VideoTheme {
+  bg: string
+  text: string
+  accent: string
+  badgeBg?: string
+}
+
+export type VideoSegmentSize = 'md' | 'lg' | 'xl' | 'hero'
+
+export interface VideoTextSegment {
+  text: string
+  size?: VideoSegmentSize
+  /** Accent color + display font */
+  emphasis?: boolean
+  /** Stagger slot: a = upper-left, b = mid-right, c = lower-left */
+  slot?: 'a' | 'b' | 'c'
+}
+
+export interface VideoOutroCta {
+  label: string
+  url: string
+  /** Secondary CTAs render ~⅓ smaller (e.g. Forkcast vs FYP). */
+  variant?: 'primary' | 'secondary'
+}
+
+export interface VideoFocusAreaRef {
+  selector: string
+}
+
+export type AnnotationCalloutSide = 'top' | 'bottom' | 'left' | 'right'
+
+/** UI guide callout — points at an exploration region (parallel to story overlays). */
+export interface VideoAnnotationDefinition {
+  id: string
+  /** Zone key from focusAreas or raw CSS selector */
+  target: string
+  label: string
+  hint?: string
+  side?: AnnotationCalloutSide | 'auto'
+}
+
+/** Climax mark — translucent area box over a text cell or UI element. */
+export interface VideoHighlightMarkDefinition {
+  target: string
+  /** Uniform padding (px) when padX / padY omitted. */
+  pad?: number
+  padX?: number
+  padY?: number
+  /** @deprecated No longer used. */
+  tilt?: number
+  /** @deprecated Labels removed — marker-only highlights. */
+  label?: string
+}
+
+export interface VideoHighlightSetDefinition {
+  id: string
+  marks: VideoHighlightMarkDefinition[]
+}
+
+export interface VideoOverlayDefinition {
+  type: VideoOverlayType
+  id: string
+  duration?: number
+  /** Default placement when playbook step does not override */
+  placement?: VideoOverlayPlacement
+  /** banner / compact split — single bar instead of scattered boxes */
+  layout?: 'banner' | 'scatter'
+  /** title-card */
+  eyebrow?: string
+  title?: string
+  subtitle?: string
+  hook?: string[]
+  /** punch / banner */
+  text?: string
+  sub?: string
+  position?: 'top' | 'center' | 'bottom'
+  invert?: boolean
+  /** split / callout — explicit segments (preferred) */
+  segments?: VideoTextSegment[]
+  /** list-flash */
+  headline?: string
+  items?: string[]
+  /** outro-card */
+  closing?: string
+  ctas?: VideoOutroCta[]
+  primary?: string
+  cta?: string
+  secondary?: string
+  /** legacy */
+  lines?: string[]
+  question?: string
+}
+
+export interface VideoContentConfig {
+  explorationId: string
+  theme?: VideoTheme
+  overlays: Record<string, VideoOverlayDefinition>
+  annotations?: Record<string, VideoAnnotationDefinition>
+  highlightSets?: Record<string, VideoHighlightSetDefinition>
+  focusAreas?: Record<string, VideoFocusAreaRef>
+}
+
+export interface ActiveVideoHighlightSet {
+  id: string
+  marks: VideoHighlightMarkDefinition[]
+}
+
+export interface ActiveVideoAnnotation {
+  id: string
+  definition: VideoAnnotationDefinition
+}
+
+export interface ActiveVideoOverlay {
+  id: string
+  definition: VideoOverlayDefinition
+  placement?: VideoOverlayPlacement
+}
+
+export interface ShowOverlayOptions {
+  placement?: VideoOverlayPlacement
+}
diff --git a/src/video/useTargetRect.ts b/src/video/useTargetRect.ts
new file mode 100644
index 0000000..34adef0
--- /dev/null
+++ b/src/video/useTargetRect.ts
@@ -0,0 +1,52 @@
+import { onMounted, onUnmounted, type Ref, ref, watch } from 'vue'
+
+export function useTargetRect(selector: Ref<string>): Ref<DOMRect | null> {
+  const targetRect = ref<DOMRect | null>(null)
+  let observer: ResizeObserver | undefined
+  let raf = 0
+
+  function measure() {
+    const el = document.querySelector(selector.value)
+    if (!el) {
+      targetRect.value = null
+      return
+    }
+    const rect = el.getBoundingClientRect()
+    if (rect.width <= 0 && rect.height <= 0) {
+      targetRect.value = null
+      return
+    }
+    targetRect.value = rect
+  }
+
+  function scheduleMeasure() {
+    cancelAnimationFrame(raf)
+    raf = requestAnimationFrame(measure)
+  }
+
+  function attachObserver() {
+    observer?.disconnect()
+    observer = new ResizeObserver(scheduleMeasure)
+    const el = document.querySelector(selector.value)
+    if (el) observer.observe(el)
+    scheduleMeasure()
+  }
+
+  watch(selector, attachObserver)
+
+  onMounted(() => {
+    scheduleMeasure()
+    window.addEventListener('scroll', scheduleMeasure, { passive: true, capture: true })
+    window.addEventListener('resize', scheduleMeasure, { passive: true })
+    attachObserver()
+  })
+
+  onUnmounted(() => {
+    cancelAnimationFrame(raf)
+    observer?.disconnect()
+    window.removeEventListener('scroll', scheduleMeasure, true)
+    window.removeEventListener('resize', scheduleMeasure)
+  })
+
+  return targetRect
+}
diff --git a/src/video/useVideoMode.ts b/src/video/useVideoMode.ts
new file mode 100644
index 0000000..b60e48e
--- /dev/null
+++ b/src/video/useVideoMode.ts
@@ -0,0 +1,15 @@
+import { computed, type ComputedRef } from 'vue'
+import { useRoute } from 'vue-router'
+
+/** URL query key that activates the video overlay shell (no site chrome). */
+export const FYP_VIDEO_QUERY_PARAM = 'fyp-video'
+
+export function isVideoModeQuery(query: Record<string, unknown>): boolean {
+  const value = query[FYP_VIDEO_QUERY_PARAM]
+  return value === '1' || value === 'true' || value === ''
+}
+
+export function useVideoMode(): ComputedRef<boolean> {
+  const route = useRoute()
+  return computed(() => isVideoModeQuery(route.query as Record<string, unknown>))
+}
diff --git a/src/video/video.css b/src/video/video.css
new file mode 100644
index 0000000..25b0fd1
--- /dev/null
+++ b/src/video/video.css
@@ -0,0 +1,777 @@
+/* Video capture overlays — separate visual language from the main site. */
+@import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Barlow+Condensed:ital,wght@0,700;0,800;0,900;1,700&display=block');
+
+.video-shell {
+  --video-accent: #a855f7;
+  --video-display: 'Bebas Neue', 'Arial Black', Impact, sans-serif;
+  --video-condensed: 'Barlow Condensed', 'Arial Narrow', sans-serif;
+  /* Banner inset/max-height scale via html.fyp-video-capture --video-capture-scale */
+  --video-top-banner-inset: calc(36px * var(--video-capture-scale, 1));
+  --video-top-banner-max-h: calc(168px * var(--video-capture-scale, 1));
+  --video-focus-gap: calc(12px * var(--video-capture-scale, 1));
+  /* --video-safe-* live on html.fyp-video-capture only (must not reset here — overlays inherit from html) */
+}
+
+/* --- Title / outro band cards (middle 3/5 black, top+bottom peek at live UI) --- */
+.video-card-band {
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  display: grid;
+  grid-template-rows: 1fr 3fr 1fr;
+  pointer-events: none;
+  animation: video-flash-in 0.55s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.video-card-band__peek {
+  background: transparent;
+}
+
+.video-card-band__content {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: stretch;
+  background: #000;
+  padding: 1.25rem 1.25rem 1rem;
+  overflow: hidden;
+}
+
+.video-card-band__content--outro {
+  justify-content: center;
+  gap: 0.5rem;
+}
+
+.video-card-band__eyebrow {
+  font-family: var(--video-condensed);
+  font-weight: 800;
+  font-size: clamp(0.85rem, 3.5vw, 1.1rem);
+  letter-spacing: 0.35em;
+  text-transform: uppercase;
+  color: var(--video-accent);
+  margin-bottom: 0.75rem;
+}
+
+.video-card-band__title {
+  font-family: var(--video-display);
+  font-size: clamp(3.2rem, 14vw, 5.5rem);
+  line-height: 0.92;
+  letter-spacing: 0.02em;
+  color: #fff;
+  text-transform: uppercase;
+}
+
+.video-card-band__subtitle {
+  font-family: var(--video-display);
+  font-size: clamp(1.8rem, 8vw, 3rem);
+  line-height: 0.95;
+  letter-spacing: 0.06em;
+  color: var(--video-accent);
+  margin-top: 0.35rem;
+  text-transform: uppercase;
+  white-space: pre-line;
+}
+
+.video-card-band__hook {
+  margin-top: 1.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.video-card-band__hook-line {
+  font-family: var(--video-condensed);
+  font-weight: 900;
+  font-size: clamp(1.4rem, 6vw, 2.25rem);
+  line-height: 1.05;
+  text-transform: uppercase;
+  color: #fff;
+}
+
+.video-card-band__hook-line--accent {
+  color: var(--video-accent);
+  font-size: clamp(1.9rem, 8.5vw, 3.2rem);
+  font-style: italic;
+}
+
+.video-card-band__closing {
+  font-family: var(--video-condensed);
+  font-weight: 700;
+  font-style: italic;
+  font-size: clamp(1rem, 4.2vw, 1.35rem);
+  line-height: 1.25;
+  color: rgba(255, 255, 255, 0.82);
+  text-align: center;
+  margin: 0 0 1rem;
+  letter-spacing: 0.02em;
+}
+
+.video-card-band__ctas {
+  display: flex;
+  flex-direction: column;
+  gap: 1.35rem;
+  margin-top: 0.25rem;
+}
+
+.video-card-band__cta {
+  text-align: center;
+}
+
+.video-card-band__cta-label {
+  font-family: var(--video-condensed);
+  font-weight: 800;
+  font-size: clamp(0.95rem, 4vw, 1.2rem);
+  letter-spacing: 0.28em;
+  text-transform: uppercase;
+  color: rgba(255, 255, 255, 0.72);
+  margin: 0;
+}
+
+.video-card-band__cta-url {
+  font-family: var(--video-display);
+  font-size: clamp(1.85rem, 8vw, 2.85rem);
+  line-height: 1;
+  letter-spacing: 0.04em;
+  color: var(--video-accent);
+  text-transform: uppercase;
+  margin: 0.2rem 0 0;
+}
+
+.video-card-band__cta--secondary .video-card-band__cta-label {
+  font-size: clamp(0.63rem, 2.65vw, 0.8rem);
+  letter-spacing: 0.22em;
+}
+
+.video-card-band__cta--secondary .video-card-band__cta-url {
+  font-size: clamp(1.23rem, 5.35vw, 1.9rem);
+}
+
+/* --- UI annotation callouts (parallel guide layer) --- */
+.video-annotation-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 57;
+  pointer-events: none;
+}
+
+.video-annotation-highlight {
+  position: fixed;
+  box-sizing: border-box;
+  border: 2px solid var(--video-accent);
+  border-radius: 0.45rem;
+  box-shadow:
+    0 0 0 2px rgba(0, 0, 0, 0.55),
+    0 0 18px rgba(168, 85, 247, 0.45);
+  animation: video-annotation-pulse 1.6s ease-in-out infinite;
+}
+
+.video-annotation-callout {
+  position: fixed;
+  z-index: 1;
+  max-width: min(78vw, 280px);
+  padding: 0.45rem 0.65rem 0.5rem;
+  background: rgba(0, 0, 0, 0.88);
+  border: 1px solid rgba(168, 85, 247, 0.65);
+  border-radius: 0.4rem;
+  animation: video-annotation-in 0.35s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.video-annotation-callout__label {
+  font-family: var(--video-condensed);
+  font-weight: 900;
+  font-size: clamp(0.95rem, 4vw, 1.15rem);
+  line-height: 1.05;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #fff;
+  margin: 0;
+}
+
+.video-annotation-callout__hint {
+  font-family: var(--video-condensed);
+  font-weight: 700;
+  font-size: clamp(0.78rem, 3.2vw, 0.92rem);
+  line-height: 1.15;
+  color: rgba(255, 255, 255, 0.72);
+  margin: 0.2rem 0 0;
+}
+
+.video-annotation-callout__arrow {
+  position: absolute;
+  width: 0;
+  height: 0;
+  border: 7px solid transparent;
+}
+
+.video-annotation-callout--bottom .video-annotation-callout__arrow {
+  top: -14px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-bottom-color: rgba(168, 85, 247, 0.65);
+}
+
+.video-annotation-callout--top .video-annotation-callout__arrow {
+  bottom: -14px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-top-color: rgba(168, 85, 247, 0.65);
+}
+
+.video-annotation-callout--right .video-annotation-callout__arrow {
+  left: -14px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-right-color: rgba(168, 85, 247, 0.65);
+}
+
+.video-annotation-callout--left .video-annotation-callout__arrow {
+  right: -14px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-left-color: rgba(168, 85, 247, 0.65);
+}
+
+@keyframes video-annotation-pulse {
+  0%,
+  100% {
+    box-shadow:
+      0 0 0 2px rgba(0, 0, 0, 0.55),
+      0 0 14px rgba(168, 85, 247, 0.35);
+  }
+  50% {
+    box-shadow:
+      0 0 0 2px rgba(0, 0, 0, 0.55),
+      0 0 22px rgba(168, 85, 247, 0.65);
+  }
+}
+
+@keyframes video-annotation-in {
+  from {
+    opacity: 0;
+    transform: translateX(-50%) translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(-50%) translateY(0);
+  }
+}
+
+.video-annotation-callout--top.video-annotation-callout {
+  animation-name: video-annotation-in-top;
+}
+
+.video-annotation-callout--left.video-annotation-callout,
+.video-annotation-callout--right.video-annotation-callout {
+  animation-name: video-annotation-in-side;
+}
+
+@keyframes video-annotation-in-top {
+  from {
+    opacity: 0;
+    transform: translate(-50%, calc(-100% + 6px));
+  }
+  to {
+    opacity: 1;
+    transform: translate(-50%, -100%);
+  }
+}
+
+@keyframes video-annotation-in-side {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* --- Climax highlight marks (translucent area boxes over text cells) --- */
+.video-highlight-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 58;
+  pointer-events: none;
+}
+
+.video-highlight-mark {
+  position: fixed;
+  box-sizing: border-box;
+  border: none;
+  border-radius: 0;
+  background: rgba(255, 236, 0, 0.16);
+  box-shadow: inset 0 0 0 1px rgba(255, 210, 0, 0.28);
+  pointer-events: none;
+}
+
+/* --- Floating black bars (in-exploration overlays) --- */
+.video-float-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 55;
+  pointer-events: none;
+}
+
+.video-punch {
+  position: absolute;
+  left: 0;
+  right: 0;
+  padding: 0.85rem 1rem;
+  background: #000;
+  animation: video-slide-up 0.45s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.video-punch--top {
+  top: 12%;
+}
+
+.video-punch--center {
+  top: 50%;
+  transform: translateY(-50%);
+}
+
+.video-punch--bottom {
+  bottom: 18%;
+}
+
+.video-punch--top-banner {
+  top: var(--video-top-banner-inset);
+  bottom: auto;
+  transform: none;
+  max-height: var(--video-top-banner-max-h);
+  overflow: hidden;
+}
+
+.video-punch--bottom-banner {
+  top: auto;
+  bottom: calc(var(--companion-peek-h, 56px) + 4%);
+  transform: none;
+  max-height: 18vh;
+  overflow: hidden;
+}
+
+.video-punch--top-banner .video-punch__text,
+.video-punch--bottom-banner .video-punch__text {
+  font-size: clamp(1.35rem, 5.5vw, 2rem);
+  line-height: 1;
+}
+
+.video-punch--top-banner .video-punch__sub,
+.video-punch--bottom-banner .video-punch__sub {
+  font-size: clamp(0.85rem, 3.5vw, 1.1rem);
+  margin-top: 0.25rem;
+}
+
+/* --- Compact banner (story beats — keeps focus area clear) --- */
+.video-banner {
+  position: absolute;
+  left: 0;
+  right: 0;
+  z-index: 56;
+  background: #000;
+  padding: 0.6rem 1rem;
+  pointer-events: none;
+}
+
+.video-banner--top-banner {
+  top: var(--video-top-banner-inset);
+  max-height: var(--video-top-banner-max-h);
+  overflow: hidden;
+}
+
+.video-banner--bottom-banner {
+  bottom: calc(var(--companion-peek-h, 56px) + 4%);
+}
+
+.video-banner__line {
+  font-family: var(--video-condensed);
+  font-weight: 900;
+  font-size: clamp(1.1rem, 4.8vw, 1.45rem);
+  line-height: 1.1;
+  text-transform: uppercase;
+  color: #fff;
+  margin: 0;
+}
+
+.video-banner__line--accent {
+  font-family: var(--video-display);
+  font-size: clamp(1.35rem, 5.5vw, 2rem);
+  color: var(--video-accent);
+  letter-spacing: 0.03em;
+}
+
+.video-banner__line--sub {
+  font-weight: 800;
+  font-size: clamp(0.9rem, 3.8vw, 1.15rem);
+  color: rgba(255, 255, 255, 0.88);
+  margin-top: 0.2rem;
+}
+
+.video-banner--list .video-banner__line--sub {
+  margin-top: 0.1rem;
+  line-height: 1.05;
+  font-size: clamp(0.78rem, 3.2vw, 0.98rem);
+}
+
+.video-banner--list .video-banner__line--accent {
+  font-size: clamp(1.8rem, 8vw, 2.8rem);
+  line-height: 1;
+  margin-bottom: 0.15rem;
+}
+
+.video-punch__text {
+  font-family: var(--video-display);
+  font-size: clamp(2.4rem, 11vw, 4.2rem);
+  line-height: 0.95;
+  letter-spacing: 0.03em;
+  color: var(--video-accent);
+  text-transform: uppercase;
+}
+
+.video-punch__text--white {
+  color: #fff;
+}
+
+.video-punch__sub {
+  font-family: var(--video-condensed);
+  font-weight: 800;
+  font-size: clamp(1rem, 4.5vw, 1.5rem);
+  color: rgba(255, 255, 255, 0.85);
+  margin-top: 0.35rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+/* --- Staggered split read flow --- */
+.video-split {
+  position: absolute;
+  inset: 0;
+}
+
+.video-split__part {
+  position: absolute;
+  background: #000;
+  padding: 0.75rem 1rem;
+  max-width: 88%;
+  animation: video-split-in 0.5s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.video-split__part--a {
+  top: 10%;
+  left: 4%;
+  animation-delay: 0s;
+}
+
+.video-split__part--b {
+  top: 22%;
+  right: 4%;
+  left: auto;
+  animation-delay: 0.12s;
+}
+
+.video-split__part--c {
+  bottom: 28%;
+  left: 6%;
+  animation-delay: 0.24s;
+}
+
+.video-split__text {
+  font-family: var(--video-condensed);
+  font-weight: 900;
+  line-height: 1.05;
+  text-transform: uppercase;
+  color: #fff;
+}
+
+.video-split__text--lg {
+  font-size: clamp(1.5rem, 6.5vw, 2.4rem);
+}
+
+.video-split__text--xl {
+  font-size: clamp(1.9rem, 8.5vw, 3rem);
+}
+
+.video-split__text--hero {
+  font-family: var(--video-display);
+  font-size: clamp(2.8rem, 13vw, 5rem);
+  color: var(--video-accent);
+  letter-spacing: 0.02em;
+}
+
+.video-split__text--accent {
+  color: var(--video-accent);
+}
+
+/* --- Flash list --- */
+.video-list-flash {
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: 11%;
+  padding: 0 0.5rem;
+}
+
+.video-list-flash__head {
+  background: #000;
+  padding: 0.65rem 1rem;
+  margin-bottom: 0.5rem;
+  animation: video-slide-up 0.4s ease-out both;
+}
+
+.video-list-flash__head-text {
+  font-family: var(--video-display);
+  font-size: clamp(1.8rem, 8vw, 2.8rem);
+  color: var(--video-accent);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.video-list-flash__item {
+  background: #000;
+  padding: 0.5rem 1rem;
+  margin-bottom: 0.35rem;
+  animation: video-slide-up 0.4s ease-out both;
+}
+
+.video-list-flash__item-text {
+  font-family: var(--video-condensed);
+  font-weight: 800;
+  font-size: clamp(1.05rem, 4.5vw, 1.45rem);
+  color: #fff;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+}
+
+@keyframes video-flash-in {
+  from {
+    opacity: 0;
+    transform: scale(1.04);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@keyframes video-slide-up {
+  from {
+    opacity: 0;
+    transform: translateY(28px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes video-split-in {
+  from {
+    opacity: 0;
+    transform: translateX(-20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.video-split__part--b.video-split__part {
+  animation-name: video-split-in-right;
+}
+
+@keyframes video-split-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* --- YouTube Shorts safe zone (capture only) ---
+   Backgrounds (black bars) stay edge-to-edge; readable content sits inset.
+   Reference: 540×960 preview; scales at 1080 via --video-capture-scale. */
+html.fyp-video-capture {
+  --video-safe-top: 56px;
+  --video-safe-bottom: 120px;
+  --video-safe-left: 32px;
+  --video-safe-right: 48px;
+  --video-top-banner-inset: 0px;
+  --video-top-banner-max-h: 184px;
+  /* Ribbon text rhythm (540×960 ref; scales via --video-capture-scale on html) */
+  --video-ribbon-clear-top: calc(var(--video-safe-top) * 0.6);
+  --video-ribbon-pad-top: calc(8px * var(--video-capture-scale, 1));
+  --video-ribbon-pad-bottom: calc(20px * var(--video-capture-scale, 1));
+  --video-focus-scroll-margin: calc(
+    var(--video-safe-top) + var(--video-top-banner-max-h) + var(--video-focus-gap)
+  );
+}
+
+html.fyp-video-capture .video-banner,
+html.fyp-video-capture .video-punch {
+  /* Full-bleed black bar; text sits below Shorts chrome with balanced inner padding */
+  padding-top: calc(var(--video-ribbon-clear-top) + var(--video-ribbon-pad-top));
+  padding-bottom: var(--video-ribbon-pad-bottom);
+  padding-left: 0;
+  padding-right: 0;
+  box-sizing: border-box;
+}
+
+/* Readable copy inset — matches exploration horizontal safe zone */
+html.fyp-video-capture .video-banner__line,
+html.fyp-video-capture .video-punch__text,
+html.fyp-video-capture .video-punch__sub {
+  padding-left: var(--video-safe-left);
+  padding-right: var(--video-safe-right);
+  box-sizing: border-box;
+}
+
+html.fyp-video-capture .video-banner--bottom-banner,
+html.fyp-video-capture .video-punch--bottom-banner {
+  padding-top: var(--video-ribbon-pad-top);
+  padding-bottom: calc(var(--video-ribbon-pad-bottom) + var(--video-safe-bottom));
+}
+
+html.fyp-video-capture .video-card-band__content {
+  padding-top: 1.25rem;
+  padding-bottom: 1rem;
+  padding-left: var(--video-safe-left);
+  padding-right: var(--video-safe-right);
+  box-sizing: border-box;
+}
+
+html.fyp-video-capture .video-split__part {
+  padding-left: calc(0.75rem + var(--video-safe-left));
+  padding-right: calc(0.75rem + var(--video-safe-right));
+  max-width: calc(100% - var(--video-safe-left) - var(--video-safe-right));
+}
+
+html.fyp-video-capture .video-split__part--a {
+  left: var(--video-safe-left);
+  max-width: calc(88% - var(--video-safe-left) - var(--video-safe-right));
+}
+
+html.fyp-video-capture .video-split__part--b {
+  right: var(--video-safe-right);
+  left: auto;
+  max-width: calc(88% - var(--video-safe-left) - var(--video-safe-right));
+}
+
+html.fyp-video-capture .fyp-video-mode .exploration-c {
+  padding-left: var(--video-safe-left);
+  padding-right: var(--video-safe-right);
+  box-sizing: border-box;
+}
+
+html.fyp-video-capture .fyp-video-mode .fyp-video-exploration > div:first-child {
+  padding-bottom: calc(var(--companion-peek-h, 56px) + var(--video-safe-bottom));
+}
+
+html.fyp-video-capture .video-annotation-callout {
+  max-width: calc(100vw - var(--video-safe-left) - var(--video-safe-right) - 16px);
+}
+
+/* Recording: no entrance animations — first frame must match final overlay look. */
+html.fyp-video-capture .video-shell {
+  width: 100%;
+  height: 100vh;
+  min-height: 100vh;
+}
+
+html.fyp-video-capture .video-card-band,
+html.fyp-video-capture .video-punch,
+html.fyp-video-capture .video-banner,
+html.fyp-video-capture .video-split__part,
+html.fyp-video-capture .video-list-flash__head,
+html.fyp-video-capture .video-list-flash__item,
+html.fyp-video-capture .video-annotation-highlight,
+html.fyp-video-capture .video-annotation-callout,
+html.fyp-video-capture .video-highlight-mark {
+  animation: none !important;
+  opacity: 1 !important;
+}
+
+html.fyp-video-capture .video-card-band {
+  width: 100%;
+  height: 100vh;
+  min-height: 100vh;
+}
+
+/* Full-res only: scale hero/banner type from 540 reference (preview keeps vw clamps above). */
+@media (min-width: 541px) {
+  html.fyp-video-capture
+    .video-card-band__content:not(.video-card-band__content--outro)
+    .video-card-band__title {
+    font-size: clamp(
+      calc(3.8rem * var(--video-capture-scale, 1)),
+      16.5vw,
+      calc(6.5rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture
+    .video-card-band__content:not(.video-card-band__content--outro)
+    .video-card-band__subtitle {
+    font-size: clamp(
+      calc(2.2rem * var(--video-capture-scale, 1)),
+      10vw,
+      calc(3.6rem * var(--video-capture-scale, 1))
+    );
+    line-height: 0.95;
+  }
+
+  html.fyp-video-capture
+    .video-card-band__content:not(.video-card-band__content--outro)
+    .video-card-band__hook-line {
+    font-size: clamp(
+      calc(1.55rem * var(--video-capture-scale, 1)),
+      6.8vw,
+      calc(2.55rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture
+    .video-card-band__content:not(.video-card-band__content--outro)
+    .video-card-band__hook-line--accent {
+    font-size: clamp(
+      calc(2.15rem * var(--video-capture-scale, 1)),
+      9.5vw,
+      calc(3.6rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture .video-punch--top-banner .video-punch__text,
+  html.fyp-video-capture .video-banner__line--accent {
+    font-size: clamp(
+      calc(1.35rem * var(--video-capture-scale, 1)),
+      5.5vw,
+      calc(2rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture .video-banner--list .video-banner__line--accent {
+    font-size: clamp(
+      calc(1.8rem * var(--video-capture-scale, 1)),
+      8vw,
+      calc(2.8rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture .video-punch--top-banner .video-punch__sub,
+  html.fyp-video-capture .video-banner__line--sub {
+    font-size: clamp(
+      calc(0.85rem * var(--video-capture-scale, 1)),
+      3.5vw,
+      calc(1.1rem * var(--video-capture-scale, 1))
+    );
+  }
+
+  html.fyp-video-capture .video-banner--list .video-banner__line--sub {
+    font-size: clamp(
+      calc(0.78rem * var(--video-capture-scale, 1)),
+      3.2vw,
+      calc(0.98rem * var(--video-capture-scale, 1))
+    );
+  }
+}
diff --git a/src/video/videoBridge.ts b/src/video/videoBridge.ts
new file mode 100644
index 0000000..2d63fd0
--- /dev/null
+++ b/src/video/videoBridge.ts
@@ -0,0 +1,131 @@
+import { type CompanionExpandMode, dispatchCompanionExpand } from './companionSheetEvents'
+import type {
+  ActiveVideoAnnotation,
+  ActiveVideoHighlightSet,
+  ActiveVideoOverlay,
+  ShowOverlayOptions,
+  VideoContentConfig,
+  VideoOverlayPlacement,
+} from './types'
+
+export interface FypVideoBridge {
+  showOverlay(id: string, options?: ShowOverlayOptions): Promise<void>
+  hideOverlay(): Promise<void>
+  showAnnotation(id: string): Promise<void>
+  hideAnnotation(): Promise<void>
+  showHighlightSet(id: string): Promise<void>
+  hideHighlights(): Promise<void>
+  expandCompanion(mode: CompanionExpandMode): Promise<void>
+  wait(ms: number): Promise<void>
+  ready(): boolean
+}
+
+declare global {
+  interface Window {
+    __FYP_VIDEO__?: FypVideoBridge
+    __FYP_VIDEO_CONFIG__?: VideoContentConfig
+  }
+}
+
+export interface VideoBridgeHandlers {
+  onShowOverlay: (id: string, options?: ShowOverlayOptions) => void
+  onHideOverlay: () => void
+  onShowAnnotation: (id: string) => void
+  onHideAnnotation: () => void
+  onShowHighlightSet: (id: string) => void
+  onHideHighlights: () => void
+  isReady: () => boolean
+}
+
+export function createVideoBridge(handlers: VideoBridgeHandlers): FypVideoBridge {
+  return {
+    showOverlay(id: string, options?: ShowOverlayOptions) {
+      handlers.onShowOverlay(id, options)
+      return Promise.resolve()
+    },
+    hideOverlay() {
+      handlers.onHideOverlay()
+      return Promise.resolve()
+    },
+    showAnnotation(id: string) {
+      handlers.onShowAnnotation(id)
+      return Promise.resolve()
+    },
+    hideAnnotation() {
+      handlers.onHideAnnotation()
+      return Promise.resolve()
+    },
+    showHighlightSet(id: string) {
+      handlers.onShowHighlightSet(id)
+      return Promise.resolve()
+    },
+    hideHighlights() {
+      handlers.onHideHighlights()
+      return Promise.resolve()
+    },
+    expandCompanion(mode: CompanionExpandMode) {
+      dispatchCompanionExpand(mode)
+      return Promise.resolve()
+    },
+    wait(ms: number) {
+      return new Promise((resolve) => window.setTimeout(resolve, ms))
+    },
+    ready() {
+      return handlers.isReady()
+    },
+  }
+}
+
+export function installVideoBridge(handlers: VideoBridgeHandlers): () => void {
+  const bridge = createVideoBridge(handlers)
+  window.__FYP_VIDEO__ = bridge
+  return () => {
+    delete window.__FYP_VIDEO__
+  }
+}
+
+export function readVideoConfigFromWindow(): VideoContentConfig | undefined {
+  return window.__FYP_VIDEO_CONFIG__
+}
+
+const FULLSCREEN_TYPES = new Set(['title-card', 'outro-card', 'title', 'outro'])
+
+export function defaultPlacementForOverlay(
+  type: string | undefined,
+): VideoOverlayPlacement | undefined {
+  if (!type || FULLSCREEN_TYPES.has(type)) return undefined
+  return 'top-banner'
+}
+
+export function resolveActiveOverlay(
+  config: VideoContentConfig | undefined,
+  overlayId: string | null,
+  options?: ShowOverlayOptions,
+): ActiveVideoOverlay | null {
+  if (!config || overlayId === null) return null
+  const definition = config.overlays[overlayId]
+  if (!definition) return null
+  const placement =
+    options?.placement ?? definition.placement ?? defaultPlacementForOverlay(definition.type)
+  return { id: overlayId, definition, placement }
+}
+
+export function resolveActiveAnnotation(
+  config: VideoContentConfig | undefined,
+  annotationId: string | null,
+): ActiveVideoAnnotation | null {
+  if (!config || annotationId === null) return null
+  const definition = config.annotations?.[annotationId]
+  if (!definition) return null
+  return { id: annotationId, definition }
+}
+
+export function resolveActiveHighlightSet(
+  config: VideoContentConfig | undefined,
+  setId: string | null,
+): ActiveVideoHighlightSet | null {
+  if (!config || setId === null) return null
+  const definition = config.highlightSets?.[setId]
+  if (!definition) return null
+  return { id: setId, marks: definition.marks }
+}
diff --git a/src/views/ExplorationView.vue b/src/views/ExplorationView.vue
index dcd5a31..5bb4658 100644
--- a/src/views/ExplorationView.vue
+++ b/src/views/ExplorationView.vue
@@ -8,10 +8,12 @@ import { EXPLORATIONS } from '@/explorations/REGISTRY'
 import { TOPIC_COLORS, TOPICS } from '@/explorations/TOPICS'
 import { provideCompanionStatus } from '@/libs/companionStatus'
 import { getBreadcrumbsForPath } from '@/libs/pageSeo'
+import { useVideoMode } from '@/video/useVideoMode'
 
 import TopicIntroView from './TopicIntroView.vue'
 
 const route = useRoute()
+const isVideoMode = useVideoMode()
 const explorationId = route.name as string
 const exploration = EXPLORATIONS[explorationId]
 const topic = TOPICS[exploration.topic]
@@ -36,13 +38,14 @@ const ExplorationComponent = defineAsyncComponent(
 </script>
 
 <template>
-  <BreadcrumbNav :items="breadcrumbs" />
-  <div class="grid md:grid-cols-2 gap-4">
+  <BreadcrumbNav v-if="!isVideoMode" :items="breadcrumbs" />
+  <div class="grid md:grid-cols-2 gap-4" :class="isVideoMode ? 'fyp-video-exploration' : ''">
     <div :class="exploration.rightPanel ? 'max-md:pb-[var(--companion-peek-h)]' : ''">
       <Suspense>
         <ExplorationComponent />
         <template #fallback>
-          <div class="flex justify-center pt-32">
+          <div v-if="isVideoMode" class="min-h-[50dvh]" aria-hidden="true" />
+          <div v-else class="flex justify-center pt-32">
             <span class="font-mono font-bold text-lg animate-pulse" :class="cc.text"
               >Loading...</span
             >
diff --git a/src/views/HomeView.vue b/src/views/HomeView.vue
index 4dbe55c..c79236d 100644
--- a/src/views/HomeView.vue
+++ b/src/views/HomeView.vue
@@ -3,7 +3,6 @@ import SectionLabel from '@/components/SectionLabel.vue'
 import ExplorationC from '@/explorations/ExplorationC.vue'
 import { EXPLORATIONS, getRandomTopicExplorationImage } from '@/explorations/REGISTRY'
 import { TOPICS } from '@/explorations/TOPICS'
-import { IceCreamHomeSection } from '@/ice-cream'
 import { COMMUNITY_TOKEN_HOME } from '@/libs/communityToken'
 import { DOCS_HOME } from '@/libs/docsUrls'
 import { ROADMAP_HOME } from '@/libs/roadmapUrls'
@@ -30,8 +29,6 @@ for (const topicId of activeTopicIds) {
     <h1 class="sr-only">Feel Your Protocol — Interactive Ethereum Protocol Explorations</h1>
     <div class="grid md:grid-cols-2 gap-4 items-start">
       <div class="flex flex-col gap-4">
-        <IceCreamHomeSection />
-
         <section>
           <SectionLabel>Latest</SectionLabel>
 
diff --git a/src/views/__tests__/AppLayout.spec.ts b/src/views/__tests__/AppLayout.spec.ts
index 9dd535f..1aa0cfc 100644
--- a/src/views/__tests__/AppLayout.spec.ts
+++ b/src/views/__tests__/AppLayout.spec.ts
@@ -119,4 +119,23 @@ describe('App layout', () => {
       expect(xLink.exists()).toBe(true)
     })
   })
+
+  describe('Video mode', () => {
+    it('hides header, roadmap banner, and footer when ?fyp-video=1', async () => {
+      const router = makeRouter()
+      await router.push('/?fyp-video=1')
+      await router.isReady()
+      const wrapper = mount(App, {
+        global: {
+          plugins: [router],
+          stubs: { RouterLink: RouterLinkStub },
+        },
+      })
+      await flushPromises()
+
+      expect(wrapper.find('header').exists()).toBe(false)
+      expect(wrapper.find('footer').exists()).toBe(false)
+      expect(wrapper.find('[data-testid="video-shell"]').exists()).toBe(true)
+    })
+  })
 })
diff --git a/src/views/__tests__/HomeView.spec.ts b/src/views/__tests__/HomeView.spec.ts
index e437867..f0608f5 100644
--- a/src/views/__tests__/HomeView.spec.ts
+++ b/src/views/__tests__/HomeView.spec.ts
@@ -105,23 +105,6 @@ describe('HomeView', () => {
     })
   })
 
-  describe('Ice Cream Week', () => {
-    it('renders the ice cream stand above Latest', () => {
-      expect(wrapper.text()).toContain('Ice Cream')
-      expect(wrapper.find('[data-ice-cream-week]').exists()).toBe(true)
-      expect(wrapper.text()).toContain('Buy Ice Cream')
-    })
-
-    it('lists Latest after the ice cream section in the DOM', () => {
-      const ice = wrapper.find('[data-ice-cream-week]').element
-      const latestLabel = wrapper.findAll('span').find((s) => s.text() === 'Latest')
-      expect(latestLabel).toBeDefined()
-      expect(
-        ice.compareDocumentPosition(latestLabel!.element) & Node.DOCUMENT_POSITION_FOLLOWING,
-      ).toBeTruthy()
-    })
-  })
-
   describe('Featured explorations', () => {
     const featured = ['eip-7928', 'eip-8024', 'eip-7883', 'eip-7594', 'eip-7951']
     const latest = featured.slice(0, 2)
diff --git a/video/.env.example b/video/.env.example
new file mode 100644
index 0000000..c907730
--- /dev/null
+++ b/video/.env.example
@@ -0,0 +1,10 @@
+# Copy to .env in this directory — never commit .env
+#
+#   cp .env.example .env
+#
+# ElevenLabs: https://elevenlabs.io/app/settings/api-keys
+
+ELEVENLABS_API_KEY=
+ELEVENLABS_VOICE_ID=
+# Defaults to eleven_v3
+# ELEVENLABS_MODEL_ID=eleven_v3
diff --git a/video/.gitignore b/video/.gitignore
new file mode 100644
index 0000000..f822679
--- /dev/null
+++ b/video/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+.chromium-ready.json
+.env
+output/
+projects/*/voice/
diff --git a/video/README.md b/video/README.md
new file mode 100644
index 0000000..d0f1c6b
--- /dev/null
+++ b/video/README.md
@@ -0,0 +1,111 @@
+# fyp-video — short-form exploration video pipeline
+
+Records vertical 9:16 videos (YouTube Shorts, Instagram Reels, X) from live Feel
+Your Protocol explorations. Text overlays are rendered in the browser; Playwright
+records the viewport while a Node playbook drives timing and interactions.
+
+This is an **isolated package** (sibling to `og/`): own `package.json`, own
+`node_modules`. CI never installs Playwright.
+
+## One-time setup
+
+If you already ran `npm run og:setup`, Chromium is shared — you only need:
+
+```bash
+npm run video:setup    # npm install in video/
+npm run video:check    # verify Chromium launch
+```
+
+Otherwise run `npm run og:setup` once from `website/` (covers both pipelines).
+
+## Usage
+
+```bash
+npm run website:build
+
+# Final output (video + voice) — use these for upload / review with audio:
+npm run video:generate:preview -- eip-8024   # 540×960 *-final.mp4
+npm run video:generate -- eip-8024           # 1080×1920 *-final.mp4 (2× upscale, same layout)
+
+# Silent intermediate only (no audio) — always 540×960 capture:
+npm run video:record -- eip-8024 --preview --no-voice
+
+npm run video:record -- eip-8024 --dry-run   # inspect playbook steps
+```
+
+Output: `video/projects/<id>/output/<id>-<timestamp>-final.mp4` (upload) and `.webm` (silent intermediate).
+
+Step-by-step voice tooling: `video:voice:synth`, `video:voice:plan`, `video:voice:mux`. See `docs/contributing/video-voice.md`.
+
+Output: `video/projects/<id>/output/<id>-<timestamp>.webm`
+
+## Website integration
+
+Open any exploration in video mode:
+
+```
+/eip-8024-stack-opcodes-dupn-swapn-exchange?fyp-video=1&example=dupn
+```
+
+| Query param | Purpose |
+|-------------|---------|
+| `fyp-video=1` | Hide site chrome; show overlay shell |
+| `example=<key>` | Pre-select an example preset (all explorations) |
+
+Playwright automation selectors (stable `data-testid`):
+
+| Selector | Element |
+|----------|---------|
+| `[data-testid="exploration-ready"]` | Exploration widget loaded |
+| `[data-testid="example-select"]` | Example dropdown trigger |
+| `[data-testid="example-<key>"]` | Example list item |
+| `[data-testid="bytecode-step"]` | Bytecode stepper Step button |
+| `[data-testid="bytecode-run"]` | Run button |
+| `[data-testid="run-block"]` | EIP-7928 Run block button |
+| `[data-testid="companion-sheet"]` | Mobile companion panel |
+| `[data-testid="companion-peek"]` | Companion peek bar (tap to expand) |
+| `[data-testid="video-shell"]` | Overlay layer root |
+
+Inject overlay copy before navigation (Phase 2 playbook runner):
+
+```typescript
+await page.addInitScript((config) => {
+  window.__FYP_VIDEO_CONFIG__ = config
+}, contentYamlParsed)
+```
+
+Drive overlays from Playwright:
+
+```typescript
+await page.evaluate(() => window.__FYP_VIDEO__!.showOverlay('hook'))
+```
+
+## Project layout
+
+```
+video/
+├── projects/
+│   └── eip-8024/
+│       ├── content.json      # overlay copy
+│       ├── playbook.json     # sequential steps + timing
+│       └── output/           # rendered .webm (gitignored)
+└── src/
+    ├── record-cli.ts
+    ├── recordVideo.ts
+    ├── playbookRunner.ts
+    ├── loadProject.ts
+    └── formats.ts
+```
+
+## Agent rules
+
+Same Playwright rules as OG images — see `.cursor/rules/video-playwright.mdc`.
+**Never** run `video:setup` or `playwright install` unless the user explicitly asks.
+
+Run record/preflight with `required_permissions: ["all"]`.
+
+## See also
+
+- `docs/contributing/video-pipeline.md` — full architecture and workflow
+- `docs/contributing/video-authoring.md` — how to author a short (beats, pacing, recording)
+- `og/README.md` — shared Chromium bootstrap pattern
diff --git a/video/package-lock.json b/video/package-lock.json
new file mode 100644
index 0000000..840cf91
--- /dev/null
+++ b/video/package-lock.json
@@ -0,0 +1,62 @@
+{
+  "name": "fyp-video",
+  "version": "0.0.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "fyp-video",
+      "version": "0.0.1",
+      "dependencies": {
+        "playwright": "^1.61.1"
+      },
+      "engines": {
+        "node": ">=22.6.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.1.tgz",
+      "integrity": "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.61.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz",
+      "integrity": "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}
diff --git a/video/package.json b/video/package.json
new file mode 100644
index 0000000..8698cc6
--- /dev/null
+++ b/video/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "fyp-video",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "Isolated Playwright pipeline for recording Feel Your Protocol short-form exploration videos. Kept out of the main website package.json so CI never installs Playwright.",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "scripts": {
+    "setup": "npm install && npx playwright install chromium",
+    "check": "node --experimental-strip-types src/check-cli.ts",
+    "preflight": "node --experimental-strip-types src/preflight-cli.ts",
+    "record": "node --experimental-strip-types src/record-cli.ts",
+    "storyboard": "node --experimental-strip-types src/storyboard-cli.ts",
+    "voice:synth": "node --experimental-strip-types src/voice/synth-cli.ts",
+    "voice:plan": "node --experimental-strip-types src/voice/plan-cli.ts",
+    "voice:mux": "node --experimental-strip-types src/voice/mux-cli.ts",
+    "generate": "node --experimental-strip-types src/generate-cli.ts",
+    "render": "npm run generate"
+  },
+  "dependencies": {
+    "playwright": "^1.61.1"
+  }
+}
diff --git a/video/projects/eip-8024/README.md b/video/projects/eip-8024/README.md
new file mode 100644
index 0000000..017b5bc
--- /dev/null
+++ b/video/projects/eip-8024/README.md
@@ -0,0 +1,14 @@
+# EIP-8024 — Stack opcodes short
+
+First Feel Your Protocol short-form video. Overlay copy in `content.json`, timeline in `playbook.json`, voice in `narration.json`.
+
+```bash
+# from website/
+npm run video:generate:preview -- eip-8024   # final *-final.mp4 (540×960, with voice)
+npm run video:generate -- eip-8024           # final *-final.mp4 (1080×1920, with voice)
+npm run video:record -- eip-8024 --preview --no-voice   # silent .webm only
+npm run video:record -- eip-8024 --dry-run
+```
+
+Upload: `output/eip-8024-<timestamp>-final.mp4`  
+Silent intermediate: `output/eip-8024-<timestamp>.webm` (no audio)
diff --git a/video/projects/eip-8024/content.json b/video/projects/eip-8024/content.json
new file mode 100644
index 0000000..277043f
--- /dev/null
+++ b/video/projects/eip-8024/content.json
@@ -0,0 +1,123 @@
+{
+  "meta": {
+    "exploration": "eip-8024",
+    "defaultExample": "dupn"
+  },
+  "overlays": {
+    "title-card": {
+      "type": "title-card",
+      "eyebrow": "Ethereum · Glamsterdam",
+      "title": "EIP-8024",
+      "subtitle": "DUPN · SWAPN ·\nEXCHANGE",
+      "hook": ["Solidity stack too deep!", "GONE SOON…"]
+    },
+    "glamsterdam": {
+      "type": "punch",
+      "layout": "banner",
+      "placement": "top-banner",
+      "text": "GLAMSTERDAM",
+      "sub": "Three opcodes extend the EVM stack",
+      "invert": true
+    },
+    "three-opcodes": {
+      "type": "list-flash",
+      "placement": "top-banner",
+      "headline": "3 NEW OPCODES",
+      "items": ["DUPN — copy deep", "SWAPN — swap deep", "EXCHANGE — two depths"]
+    },
+    "stack-cue": {
+      "type": "split",
+      "layout": "banner",
+      "placement": "top-banner",
+      "segments": [
+        { "text": "17 pushes first", "size": "lg" },
+        { "text": "Watch the stack grow ↓", "size": "md", "emphasis": false }
+      ]
+    },
+    "dupn-cue": {
+      "type": "punch",
+      "layout": "banner",
+      "placement": "top-banner",
+      "text": "ONE OPCODE",
+      "sub": "Copies item at depth 17 — watch the stack",
+      "invert": true
+    },
+    "calculator-tease": {
+      "type": "punch",
+      "layout": "banner",
+      "placement": "top-banner",
+      "text": "MAGIC BYTE?",
+      "sub": "Calculator in the panel below ↓",
+      "invert": false
+    },
+    "old-limit-cue": {
+      "type": "split",
+      "layout": "banner",
+      "placement": "top-banner",
+      "segments": [
+        { "text": "Classic DUP: depth 16 max", "size": "lg" },
+        { "text": "You just copied depth 17", "size": "lg", "emphasis": true }
+      ]
+    },
+    "outro-card": {
+      "type": "outro-card",
+      "closing": "EIP-8024 is part of the Glamsterdam hardfork.",
+      "ctas": [
+        {
+          "label": "READ ABOUT THE EIP",
+          "url": "FORKCAST.ORG",
+          "variant": "secondary"
+        },
+        {
+          "label": "TRY IT YOURSELF",
+          "url": "FEELYOURPROTOCOL.ORG",
+          "variant": "primary"
+        }
+      ]
+    }
+  },
+  "annotations": {
+    "guide-example": {
+      "target": "example-select",
+      "label": "Example presets",
+      "hint": "Switch scenarios here"
+    },
+    "guide-step": {
+      "target": "step-controls",
+      "label": "Step button",
+      "hint": "One opcode per click"
+    },
+    "guide-stack": {
+      "target": "stack",
+      "label": "Live stack",
+      "hint": "Watch depth grow",
+      "side": "top"
+    },
+    "guide-disassembly": {
+      "target": "disassembly",
+      "label": "Active opcode",
+      "hint": "Highlighted row = now",
+      "side": "bottom"
+    },
+    "guide-companion": {
+      "target": "companion",
+      "label": "Companion panel",
+      "hint": "Calculator decodes the immediate",
+      "side": "top"
+    }
+  },
+  "highlightSets": {
+    "dupn-windup": {
+      "marks": [
+        { "target": "disassembly-active-opcode", "padX": 12, "padY": 10 },
+        { "target": "stack-depth-17-value", "padX": 12, "padY": 10 }
+      ]
+    },
+    "dupn-payoff": {
+      "marks": [
+        { "target": "disassembly-dupn", "padX": 14, "padY": 12 },
+        { "target": "stack-top-value", "padX": 14, "padY": 12 }
+      ]
+    }
+  }
+}
diff --git a/video/projects/eip-8024/narration.json b/video/projects/eip-8024/narration.json
new file mode 100644
index 0000000..a566d75
--- /dev/null
+++ b/video/projects/eip-8024/narration.json
@@ -0,0 +1,37 @@
+{
+  "segmentGapMs": 350,
+  "segments": [
+    {
+      "beat": "hook",
+      "text": "EIP-8024. Three new stack opcodes. Glamsterdam is coming."
+    },
+    {
+      "beat": "context",
+      "text": "Solidity developers know this one — stack too deep."
+    },
+    {
+      "beat": "opcodes",
+      "text": "DUPN, SWAPN, and EXCHANGE let the EVM reach deeper into the stack."
+    },
+    {
+      "beat": "stack-grow",
+      "text": "Watch the stack grow — seventeen values pushed."
+    },
+    {
+      "beat": "dupn-hit",
+      "text": "Now DUPN copies from depth seventeen. No compiler gymnastics."
+    },
+    {
+      "beat": "calculator",
+      "text": "Peek at the companion — a magic-byte calculator for these opcodes."
+    },
+    {
+      "beat": "recap",
+      "text": "Classic DUP stops at depth sixteen. You just copied depth seventeen."
+    },
+    {
+      "beat": "outro",
+      "text": "Read the EIP on Forkcast. Explore it on Feel Your Protocol."
+    }
+  ]
+}
diff --git a/video/projects/eip-8024/playbook.json b/video/projects/eip-8024/playbook.json
new file mode 100644
index 0000000..0422d18
--- /dev/null
+++ b/video/projects/eip-8024/playbook.json
@@ -0,0 +1,84 @@
+{
+  "format": "shorts",
+  "exploration": "eip-8024",
+  "defaultExample": "dupn",
+  "steps": [
+    {
+      "beat": "hook",
+      "overlay": "title-card",
+      "wait": 4500
+    },
+    {
+      "beat": "context",
+      "overlay": "glamsterdam",
+      "annotate": "guide-example",
+      "placement": "top-banner",
+      "focus": "example-select",
+      "cue": 3400,
+      "hideOverlay": true,
+      "wait": 600
+    },
+    {
+      "beat": "opcodes",
+      "overlay": "three-opcodes",
+      "placement": "top-banner",
+      "focus": "example-select",
+      "cue": 4200,
+      "selectExample": "dupn",
+      "wait": 1200
+    },
+    {
+      "beat": "stack-grow",
+      "overlay": "stack-cue",
+      "annotate": "guide-stack",
+      "placement": "top-banner",
+      "focus": "stack",
+      "cue": 3000,
+      "step": { "count": 9, "interval": 360 },
+      "wait": 1600
+    },
+    {
+      "beat": "dupn-hit",
+      "overlay": "dupn-cue",
+      "annotate": "guide-disassembly",
+      "placement": "top-banner",
+      "focus": "disassembly",
+      "cue": 3000,
+      "step": {
+        "count": 9,
+        "interval": 380,
+        "climaxFrom": 9,
+        "climaxInterval": 1050,
+        "climaxPauseMs": 550,
+        "highlightSet": "dupn-windup",
+        "highlightAfterStep": 9,
+        "highlightSetAfter": "dupn-payoff",
+        "holdAfterClimaxMs": 1500
+      },
+      "wait": 2200
+    },
+    {
+      "beat": "calculator",
+      "overlay": "calculator-tease",
+      "annotate": "guide-companion",
+      "placement": "top-banner",
+      "focus": "companion",
+      "cue": 2800,
+      "expandCompanion": "half",
+      "wait": 2400
+    },
+    {
+      "beat": "recap",
+      "overlay": "old-limit-cue",
+      "annotate": "guide-stack",
+      "placement": "top-banner",
+      "focus": "stack",
+      "wait": 4200
+    },
+    {
+      "beat": "outro",
+      "overlay": "outro-card",
+      "wait": 5000
+    }
+  ]
+}
diff --git a/video/projects/eip-8024/zones.json b/video/projects/eip-8024/zones.json
new file mode 100644
index 0000000..60451a6
--- /dev/null
+++ b/video/projects/eip-8024/zones.json
@@ -0,0 +1,46 @@
+{
+  "format": { "width": 540, "height": 960 },
+  "safeZone": {
+    "topPx": 56,
+    "bottomPx": 120,
+    "leftPx": 32,
+    "rightPx": 48,
+    "description": "YouTube Shorts — keep readable text/UI inside; black bars may bleed to edges"
+  },
+  "focusAreas": {
+    "example-select": {
+      "selector": "[data-testid=\"example-select\"]",
+      "description": "Example dropdown — opcode preset picker"
+    },
+    "step-controls": {
+      "selector": "[data-testid=\"bytecode-step\"]",
+      "description": "Run / Step / Reset row"
+    },
+    "disassembly": {
+      "selector": "[data-testid=\"bytecode-disassembly\"]",
+      "description": "Opcode list with PC highlight"
+    },
+    "stack": {
+      "selector": "[data-testid=\"bytecode-stack\"]",
+      "description": "Live stack panel"
+    },
+    "companion": {
+      "selector": "[data-testid=\"companion-sheet\"]",
+      "description": "Bottom companion — calculators & visuals"
+    }
+  },
+  "placements": {
+    "top-banner": {
+      "anchor": "top",
+      "insetPx": 0,
+      "maxHeightPx": 184,
+      "description": "Full-bleed black bar; text inset via CSS safe zone + --video-ribbon-pad-*"
+    },
+    "bottom-banner": {
+      "anchor": "bottom",
+      "insetPx": 120,
+      "maxHeightPx": 140,
+      "description": "Bar above companion — clears Shorts bottom action row"
+    }
+  }
+}
diff --git a/video/src/__tests__/alignment.spec.ts b/video/src/__tests__/alignment.spec.ts
new file mode 100644
index 0000000..b185b4e
--- /dev/null
+++ b/video/src/__tests__/alignment.spec.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { alignmentDurationMs } from '../voice/alignment.ts'
+
+describe('alignmentDurationMs', () => {
+  it('returns ms from last character end time', () => {
+    expect(
+      alignmentDurationMs({
+        characters: ['H', 'i'],
+        character_start_times_seconds: [0, 0.1],
+        character_end_times_seconds: [0.1, 0.35],
+      }),
+    ).toBe(350)
+  })
+
+  it('returns 0 for empty alignment', () => {
+    expect(alignmentDurationMs(null)).toBe(0)
+  })
+})
diff --git a/video/src/__tests__/annotationTarget.spec.ts b/video/src/__tests__/annotationTarget.spec.ts
new file mode 100644
index 0000000..74e7ed0
--- /dev/null
+++ b/video/src/__tests__/annotationTarget.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { targetOverlapsTopBanner } from '../../../src/video/annotationTarget.ts'
+import { resolveTargetSelector } from '../annotationTarget.ts'
+
+describe('resolveTargetSelector', () => {
+  const zones = {
+    stack: { selector: '[data-testid="bytecode-stack"]' },
+  }
+
+  it('resolves zone keys via focusAreas', () => {
+    expect(resolveTargetSelector('stack', zones)).toBe('[data-testid="bytecode-stack"]')
+  })
+
+  it('passes through raw selectors', () => {
+    expect(resolveTargetSelector('.foo', zones)).toBe('.foo')
+  })
+
+  it('falls back to data-testid', () => {
+    expect(resolveTargetSelector('example-select', undefined)).toBe(
+      '[data-testid="example-select"]',
+    )
+  })
+
+  it('resolves built-in climax targets', () => {
+    expect(resolveTargetSelector('disassembly-active-opcode', undefined)).toBe(
+      '[data-disassembly-active="true"] [data-disassembly-opcode]',
+    )
+    expect(resolveTargetSelector('disassembly-dupn', undefined)).toBe(
+      '[data-disassembly-opcode][data-disassembly-mnemonic*="DUPN"]',
+    )
+    expect(resolveTargetSelector('stack-top-value', undefined)).toBe(
+      '[data-stack-depth="1"] [data-stack-value]',
+    )
+    expect(resolveTargetSelector('stack-depth-17-value', undefined)).toBe(
+      '[data-stack-depth="17"] [data-stack-value]',
+    )
+  })
+})
+
+describe('targetOverlapsTopBanner', () => {
+  const banner = { top: 56, bottom: 180, left: 0, right: 540, width: 540, height: 124 } as DOMRect
+
+  it('suppresses when target sits under the banner', () => {
+    const target = { top: 120, bottom: 150, left: 32, right: 200, width: 168, height: 30 } as DOMRect
+    expect(targetOverlapsTopBanner(target, [banner])).toBe(true)
+  })
+
+  it('allows when target is below the banner', () => {
+    const target = { top: 200, bottom: 230, left: 32, right: 200, width: 168, height: 30 } as DOMRect
+    expect(targetOverlapsTopBanner(target, [banner])).toBe(false)
+  })
+})
diff --git a/video/src/__tests__/formats.spec.ts b/video/src/__tests__/formats.spec.ts
new file mode 100644
index 0000000..6f5b611
--- /dev/null
+++ b/video/src/__tests__/formats.spec.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  assertFormatViewportMatchesOutput,
+  deliverableScale,
+  VIDEO_FORMATS,
+  VIDEO_RECORD_FORMAT,
+} from '../formats.ts'
+
+describe('VIDEO_FORMATS', () => {
+  it('records at 540×960 reference for all deliverables', () => {
+    expect(VIDEO_RECORD_FORMAT.viewportWidth).toBe(540)
+    expect(VIDEO_RECORD_FORMAT.viewportHeight).toBe(960)
+  })
+
+  it('validates output as uniform integer scale of viewport', () => {
+    for (const format of Object.values(VIDEO_FORMATS)) {
+      assertFormatViewportMatchesOutput(format)
+      expect(format.width / format.height).toBeCloseTo(9 / 16, 5)
+    }
+  })
+
+  it('shorts deliverable is 2× reference', () => {
+    expect(VIDEO_FORMATS.shorts.width).toBe(1080)
+    expect(VIDEO_FORMATS.shorts.height).toBe(1920)
+    expect(deliverableScale(VIDEO_FORMATS.shorts)).toBe(2)
+    expect(VIDEO_FORMATS.shorts.viewportWidth).toBe(540)
+    expect(VIDEO_FORMATS.shorts.viewportHeight).toBe(960)
+  })
+
+  it('shorts-preview is 1× reference', () => {
+    expect(VIDEO_FORMATS['shorts-preview'].width).toBe(540)
+    expect(VIDEO_FORMATS['shorts-preview'].height).toBe(960)
+    expect(deliverableScale(VIDEO_FORMATS['shorts-preview'])).toBe(1)
+  })
+})
diff --git a/video/src/__tests__/loadProject.spec.ts b/video/src/__tests__/loadProject.spec.ts
new file mode 100644
index 0000000..2cee936
--- /dev/null
+++ b/video/src/__tests__/loadProject.spec.ts
@@ -0,0 +1,56 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { themeForExploration } from '../explorationRegistry.ts'
+import { estimatePlaybookDurationMs, loadVideoProject } from '../loadProject.ts'
+import { parseRecordCliArgs } from '../parseRecordArgs.ts'
+
+const PROJECTS_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../projects')
+
+describe('loadVideoProject eip-8024', () => {
+  it('loads content and playbook with matching exploration ids', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+
+    expect(project.content.explorationId).toBe('eip-8024')
+    expect(project.playbook.exploration).toBe('eip-8024')
+    expect(project.playbookBase.steps.length).toBe(project.playbook.steps.length)
+    expect(project.explorationPath).toContain('eip-8024')
+    expect(project.content.overlays['title-card']?.type).toBe('title-card')
+    expect(project.content.theme?.accent).toBe('#a855f7')
+  })
+
+  it('assigns overlay ids from content keys', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    expect(project.content.overlays['dupn-cue']?.id).toBe('dupn-cue')
+    expect(project.zones?.focusAreas.stack?.selector).toContain('bytecode-stack')
+  })
+
+  it('estimates a shorts-friendly duration', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const ms = estimatePlaybookDurationMs(project.playbook)
+    expect(ms).toBeGreaterThan(25_000)
+    expect(ms).toBeLessThan(90_000)
+  })
+})
+
+describe('themeForExploration', () => {
+  it('returns purple for robustness explorations', () => {
+    expect(themeForExploration('eip-8024').text).toBe('#6b21a8')
+  })
+})
+
+describe('parseRecordCliArgs', () => {
+  it('parses project id and flags', () => {
+    expect(parseRecordCliArgs(['eip-8024', '--preview', '--dry-run', '--no-voice'])).toEqual({
+      projectId: 'eip-8024',
+      preview: true,
+      dryRun: true,
+      noVoice: true,
+    })
+  })
+
+  it('throws when project id is missing', () => {
+    expect(() => parseRecordCliArgs([])).toThrow(/Missing project id/)
+  })
+})
diff --git a/video/src/__tests__/mergeTiming.spec.ts b/video/src/__tests__/mergeTiming.spec.ts
new file mode 100644
index 0000000..09df814
--- /dev/null
+++ b/video/src/__tests__/mergeTiming.spec.ts
@@ -0,0 +1,74 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { loadVideoProject } from '../loadProject.ts'
+import { mergeVoiceTiming, voiceTimingSummary } from '../voice/mergeTiming.ts'
+import type { VoiceManifest } from '../voice/types.ts'
+
+const PROJECTS_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../projects')
+
+function fixtureManifest(): VoiceManifest {
+  return {
+    version: 1,
+    generatedAt: '2026-01-01T00:00:00.000Z',
+    model: 'eleven_v3',
+    voiceId: 'test',
+    audioFile: 'voice/full.mp3',
+    segmentGapMs: 350,
+    totalDurationMs: 30_000,
+    beats: {
+      hook: { startMs: 0, endMs: 4000, durationMs: 4000, segmentFile: 'voice/segments/hook.mp3' },
+      context: { startMs: 4350, endMs: 7500, durationMs: 3150, segmentFile: 'voice/segments/context.mp3' },
+      opcodes: { startMs: 7850, endMs: 12_000, durationMs: 4150, segmentFile: 'voice/segments/opcodes.mp3' },
+      'stack-grow': {
+        startMs: 12_350,
+        endMs: 15_500,
+        durationMs: 3150,
+        segmentFile: 'voice/segments/stack-grow.mp3',
+      },
+      'dupn-hit': {
+        startMs: 15_850,
+        endMs: 19_500,
+        durationMs: 3650,
+        segmentFile: 'voice/segments/dupn-hit.mp3',
+      },
+      calculator: {
+        startMs: 19_850,
+        endMs: 23_000,
+        durationMs: 3150,
+        segmentFile: 'voice/segments/calculator.mp3',
+      },
+      recap: { startMs: 23_350, endMs: 26_500, durationMs: 3150, segmentFile: 'voice/segments/recap.mp3' },
+      outro: { startMs: 26_850, endMs: 30_000, durationMs: 3150, segmentFile: 'voice/segments/outro.mp3' },
+    },
+  }
+}
+
+describe('mergeVoiceTiming', () => {
+  it('sets card-only wait from voice duration', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const merged = mergeVoiceTiming(project.playbookBase, fixtureManifest())
+    expect(merged.steps[0]?.wait).toBe(4300)
+  })
+
+  it('sets cue from voice duration on action beats', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const merged = mergeVoiceTiming(project.playbookBase, fixtureManifest())
+    expect(merged.steps[3]?.cue).toBe(3150)
+    expect(merged.steps[3]?.step).toBeDefined()
+  })
+
+  it('produces a summary row per voiced beat', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const rows = voiceTimingSummary(project.playbookBase, fixtureManifest())
+    expect(rows.length).toBe(8)
+    expect(rows[0]?.beat).toBe('hook')
+  })
+
+  it('holds outro at least 5s for CTA cards', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const merged = mergeVoiceTiming(project.playbookBase, fixtureManifest())
+    expect(merged.steps.find((s) => s.beat === 'outro')?.wait).toBeGreaterThanOrEqual(5000)
+  })
+})
diff --git a/video/src/__tests__/parseGenerateArgs.spec.ts b/video/src/__tests__/parseGenerateArgs.spec.ts
new file mode 100644
index 0000000..52cedfa
--- /dev/null
+++ b/video/src/__tests__/parseGenerateArgs.spec.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+
+import { finalMp4Path } from '../outputPaths.ts'
+import { parseGenerateCliArgs } from '../parseGenerateArgs.ts'
+
+describe('parseGenerateCliArgs', () => {
+  it('parses project id and flags', () => {
+    expect(parseGenerateCliArgs(['eip-8024', '--preview', '--force-synth', '--skip-synth'])).toEqual({
+      projectId: 'eip-8024',
+      preview: true,
+      forceSynth: true,
+      skipSynth: true,
+    })
+  })
+
+  it('throws when project id is missing', () => {
+    expect(() => parseGenerateCliArgs([])).toThrow(/Missing project id/)
+  })
+})
+
+describe('finalMp4Path', () => {
+  it('replaces webm extension with -final.mp4', () => {
+    expect(finalMp4Path('/out/eip-8024-2026.webm')).toBe('/out/eip-8024-2026-final.mp4')
+  })
+})
diff --git a/video/src/__tests__/storyboard.spec.ts b/video/src/__tests__/storyboard.spec.ts
new file mode 100644
index 0000000..902068d
--- /dev/null
+++ b/video/src/__tests__/storyboard.spec.ts
@@ -0,0 +1,33 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { loadVideoProject } from '../loadProject.ts'
+import { buildStoryboard, validateStoryboard } from '../storyboard.ts'
+
+const PROJECTS_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../projects')
+
+describe('storyboard eip-8024', () => {
+  it('builds a cue → reveal timeline', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const timeline = buildStoryboard(project.playbook, project.content)
+
+    expect(timeline.entries.some((e) => e.phase === 'cue' && e.overlay === 'stack-cue')).toBe(true)
+    expect(timeline.entries.some((e) => e.label.includes('step ×'))).toBe(true)
+    expect(timeline.totalMs).toBeGreaterThan(30_000)
+  })
+
+  it('passes validation for focus areas and overlays', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const issues = validateStoryboard(project.playbook, project.content, project.zones)
+    expect(issues.filter((i) => i.severity === 'error')).toHaveLength(0)
+  })
+
+  it('includes guide annotations in the timeline', () => {
+    const project = loadVideoProject('eip-8024', PROJECTS_ROOT)
+    const timeline = buildStoryboard(project.playbook, project.content)
+    expect(timeline.entries.some((e) => e.phase === 'guide' && e.annotation === 'guide-stack')).toBe(
+      true,
+    )
+  })
+})
diff --git a/video/src/__tests__/trimLeadIn.spec.ts b/video/src/__tests__/trimLeadIn.spec.ts
new file mode 100644
index 0000000..bbb2707
--- /dev/null
+++ b/video/src/__tests__/trimLeadIn.spec.ts
@@ -0,0 +1,78 @@
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import {
+  findLeadInTrimSec,
+  isTitleBandFrame,
+  LEAD_IN_LUMINANCE_THRESHOLD,
+  trimVideoLeadIn,
+  verifyVideoLeadIn,
+} from '../trimLeadIn.ts'
+
+const SAMPLE_VIDEO = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '../../projects/eip-8024/output/eip-8024-2026-07-03T12-59-38.webm',
+)
+
+function withVideoCopy(fn: (copyPath: string) => void): void {
+  if (!existsSync(SAMPLE_VIDEO)) return
+  const dir = mkdtempSync(join(tmpdir(), 'fyp-trim-test-'))
+  const copy = join(dir, 'sample.webm')
+  copyFileSync(SAMPLE_VIDEO, copy)
+  try {
+    fn(copy)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+describe('trimLeadIn', () => {
+  it('rejects exploration UI frames that only match legacy bright-text heuristics', () => {
+    expect(
+      isTitleBandFrame({
+        min: 0,
+        max: 255,
+        textSpanPx: 336,
+        darkPixelRatio: 0.0002,
+        meanLuminance: 248,
+      }),
+    ).toBe(false)
+    expect(
+      isTitleBandFrame({
+        min: 0,
+        max: 255,
+        textSpanPx: 310,
+        darkPixelRatio: 0.79,
+        meanLuminance: 41,
+      }),
+    ).toBe(true)
+  })
+
+  it('findLeadInTrimSec returns 0 when frame 0 already shows the title', () => {
+    withVideoCopy((copy) => {
+      const atZero = verifyVideoLeadIn(copy)
+      if (!atZero.ok) return
+      expect(findLeadInTrimSec(copy)).toBe(0)
+    })
+  })
+
+  it('trims lead-in so frame 0 shows the title card when needed', () => {
+    withVideoCopy((copy) => {
+      const before = verifyVideoLeadIn(copy)
+      const result = trimVideoLeadIn(copy)
+      const after = verifyVideoLeadIn(copy)
+
+      expect(after.ok).toBe(true)
+      expect(after.maxLuminance).toBeGreaterThanOrEqual(LEAD_IN_LUMINANCE_THRESHOLD)
+
+      if (!before.ok) {
+        expect(result.trimmedSec).toBeGreaterThan(0)
+      } else {
+        expect(result.trimmedSec).toBe(0)
+      }
+    })
+  })
+})
diff --git a/video/src/annotationTarget.ts b/video/src/annotationTarget.ts
new file mode 100644
index 0000000..86d7ee5
--- /dev/null
+++ b/video/src/annotationTarget.ts
@@ -0,0 +1,27 @@
+import type { VideoFocusAreaRef } from './types.ts'
+
+export function resolveTargetSelector(
+  target: string,
+  focusAreas?: Record<string, VideoFocusAreaRef>,
+): string {
+  if (target === 'disassembly-active') return '[data-disassembly-active="true"]'
+  if (target === 'disassembly-active-opcode') {
+    return '[data-disassembly-active="true"] [data-disassembly-opcode]'
+  }
+  if (target === 'disassembly-dupn') {
+    return '[data-disassembly-opcode][data-disassembly-mnemonic*="DUPN"]'
+  }
+  if (target === 'stack-top') return '[data-stack-depth="1"]'
+  if (target === 'stack-top-value') return '[data-stack-depth="1"] [data-stack-value]'
+  const depthValueMatch = /^stack-depth-(\d+)-value$/.exec(target)
+  if (depthValueMatch) {
+    return `[data-stack-depth="${depthValueMatch[1]}"] [data-stack-value]`
+  }
+  const depthMatch = /^stack-depth-(\d+)$/.exec(target)
+  if (depthMatch) return `[data-stack-depth="${depthMatch[1]}"]`
+
+  const fromZone = focusAreas?.[target]?.selector
+  if (fromZone) return fromZone
+  if (target.startsWith('[') || target.startsWith('.') || target.startsWith('#')) return target
+  return `[data-testid="${target}"]`
+}
diff --git a/video/src/bootstrap-playwright-env.ts b/video/src/bootstrap-playwright-env.ts
new file mode 100644
index 0000000..1717aa3
--- /dev/null
+++ b/video/src/bootstrap-playwright-env.ts
@@ -0,0 +1,2 @@
+/** Reuse OG Playwright bootstrap (Cursor sandbox redirect). Side-effect import only. */
+import '../../og/src/bootstrap-playwright-env.ts'
diff --git a/video/src/check-cli.ts b/video/src/check-cli.ts
new file mode 100644
index 0000000..627afd0
--- /dev/null
+++ b/video/src/check-cli.ts
@@ -0,0 +1,13 @@
+import './bootstrap-playwright-env.ts'
+
+import { assertChromiumReady } from './chromium.ts'
+
+async function main(): Promise<void> {
+  await assertChromiumReady()
+  console.log('OK: Playwright Chromium is installed and launchable for video recording.')
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
diff --git a/video/src/chromium.ts b/video/src/chromium.ts
new file mode 100644
index 0000000..7718142
--- /dev/null
+++ b/video/src/chromium.ts
@@ -0,0 +1,8 @@
+import './bootstrap-playwright-env.ts'
+
+export { assertChromiumReady } from '../../og/src/check-browsers.ts'
+export {
+  type ChromiumStatusKind,
+  formatChromiumStatus,
+  inspectChromiumEnvironment,
+} from '../../og/src/chromium-status.ts'
diff --git a/video/src/explorationRegistry.ts b/video/src/explorationRegistry.ts
new file mode 100644
index 0000000..23767d4
--- /dev/null
+++ b/video/src/explorationRegistry.ts
@@ -0,0 +1,53 @@
+import type { VideoTheme } from './types.ts'
+
+export interface ExplorationMeta {
+  path: string
+  topic: keyof typeof TOPIC_THEMES
+}
+
+/** Known explorations for video projects (path + topic palette). */
+export const EXPLORATION_REGISTRY: Record<string, ExplorationMeta> = {
+  'eip-8024': {
+    path: '/eip-8024-stack-opcodes-dupn-swapn-exchange',
+    topic: 'robustness',
+  },
+  'eip-7928': {
+    path: '/eip-7928-block-level-access-lists',
+    topic: 'security',
+  },
+  'eip-7883': {
+    path: '/eip-7883-modexp-gas-cost-increase',
+    topic: 'robustness',
+  },
+  'eip-7951': {
+    path: '/eip-7951-secp256r1-precompile',
+    topic: 'interoperability',
+  },
+  'eip-7594': {
+    path: '/eip-7594-peerdas-data-availability-sampling',
+    topic: 'scaling',
+  },
+}
+
+/** Topic → overlay theme (aligned with og/src/topic-colors.ts). */
+export const TOPIC_THEMES: Record<string, VideoTheme> = {
+  scaling: { accent: '#3b82f6', bg: '#eff6ff', text: '#1e40af', badgeBg: '#dbeafe' },
+  privacy: { accent: '#22c55e', bg: '#f0fdf4', text: '#166534', badgeBg: '#dcfce7' },
+  ux: { accent: '#eab308', bg: '#fefce8', text: '#854d0e', badgeBg: '#fef9c3' },
+  security: { accent: '#ef4444', bg: '#fef2f2', text: '#991b1b', badgeBg: '#fee2e2' },
+  robustness: { accent: '#a855f7', bg: '#faf5ff', text: '#6b21a8', badgeBg: '#f3e8ff' },
+  interoperability: { accent: '#f97316', bg: '#fff7ed', text: '#9a3412', badgeBg: '#ffedd5' },
+}
+
+export function getExplorationMeta(explorationId: string): ExplorationMeta {
+  const meta = EXPLORATION_REGISTRY[explorationId]
+  if (!meta) {
+    throw new Error(`Unknown exploration id for video: ${explorationId}`)
+  }
+  return meta
+}
+
+export function themeForExploration(explorationId: string): VideoTheme {
+  const meta = getExplorationMeta(explorationId)
+  return TOPIC_THEMES[meta.topic]!
+}
diff --git a/video/src/formats.ts b/video/src/formats.ts
new file mode 100644
index 0000000..dde5c36
--- /dev/null
+++ b/video/src/formats.ts
@@ -0,0 +1,55 @@
+/** Vertical short-form presets (YouTube Shorts, Reels, X) — strict 9:16. */
+const REFERENCE_WIDTH = 540
+const REFERENCE_HEIGHT = 960
+const OUTPUT_WIDTH = 1080
+const OUTPUT_HEIGHT = 1920
+
+/**
+ * Layout is authored at 540×960 (`shorts-preview`). Full deliverables are a 2× upscale
+ * during mux — never a separate 1080px CSS viewport (that diverged from preview).
+ *
+ * Playwright records at the reference viewport; `recordVideo.size` must match it exactly.
+ */
+export const VIDEO_FORMATS = {
+  shorts: {
+    width: OUTPUT_WIDTH,
+    height: OUTPUT_HEIGHT,
+    viewportWidth: REFERENCE_WIDTH,
+    viewportHeight: REFERENCE_HEIGHT,
+    deviceScaleFactor: 1,
+  },
+  'shorts-preview': {
+    width: REFERENCE_WIDTH,
+    height: REFERENCE_HEIGHT,
+    viewportWidth: REFERENCE_WIDTH,
+    viewportHeight: REFERENCE_HEIGHT,
+    deviceScaleFactor: 1,
+  },
+} as const
+
+export type VideoFormatId = keyof typeof VIDEO_FORMATS
+
+export type VideoFormat = (typeof VIDEO_FORMATS)[VideoFormatId]
+
+/** Viewport used for Playwright capture (layout reference). */
+export const VIDEO_RECORD_FORMAT = VIDEO_FORMATS['shorts-preview']
+
+export function parseVideoFormatId(value: string | undefined): VideoFormatId {
+  if (value === 'shorts-preview') return 'shorts-preview'
+  return 'shorts'
+}
+
+/** Deliverable may be 2× reference; recording viewport is always the reference size. */
+export function assertFormatViewportMatchesOutput(format: VideoFormat): void {
+  const scaleW = format.width / format.viewportWidth
+  const scaleH = format.height / format.viewportHeight
+  if (!Number.isInteger(scaleW) || !Number.isInteger(scaleH) || scaleW !== scaleH) {
+    throw new Error(
+      `Video format ${format.width}×${format.height}: output must be an uniform integer scale of viewport (${format.viewportWidth}×${format.viewportHeight})`,
+    )
+  }
+}
+
+export function deliverableScale(format: VideoFormat): number {
+  return format.width / format.viewportWidth
+}
diff --git a/video/src/generate-cli.ts b/video/src/generate-cli.ts
new file mode 100644
index 0000000..7eae2c1
--- /dev/null
+++ b/video/src/generate-cli.ts
@@ -0,0 +1,45 @@
+import './bootstrap-playwright-env.ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { generateVideo } from './generateVideo.ts'
+import { parseGenerateCliArgs } from './parseGenerateArgs.ts'
+
+const WEBSITE_ROOT = join(import.meta.dirname, '../..')
+const DIST_DIR = join(WEBSITE_ROOT, 'dist')
+const PROJECTS_ROOT = join(import.meta.dirname, '../projects')
+
+async function main(): Promise<void> {
+  let args: ReturnType<typeof parseGenerateCliArgs>
+  try {
+    args = parseGenerateCliArgs(process.argv.slice(2))
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  }
+
+  const projectDir = join(PROJECTS_ROOT, args.projectId)
+  if (!existsSync(projectDir)) {
+    console.error(`Unknown project: ${args.projectId}`)
+    process.exit(1)
+  }
+
+  if (!existsSync(join(DIST_DIR, 'website'))) {
+    console.error('Website build not found. Run: npm run video:generate -- <project-id>')
+    console.error('(includes website:build automatically when run from website/)')
+    process.exit(1)
+  }
+
+  await generateVideo(args.projectId, {
+    preview: args.preview,
+    forceSynth: args.forceSynth,
+    skipSynth: args.skipSynth,
+    distDir: DIST_DIR,
+    projectsRoot: PROJECTS_ROOT,
+  })
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
diff --git a/video/src/generateVideo.ts b/video/src/generateVideo.ts
new file mode 100644
index 0000000..d100472
--- /dev/null
+++ b/video/src/generateVideo.ts
@@ -0,0 +1,85 @@
+import { join } from 'node:path'
+
+import { parseVideoFormatId, VIDEO_FORMATS } from './formats.ts'
+import { loadVideoEnv } from './loadEnv.ts'
+import { finalMp4Path,formatOutputBanner } from './outputPaths.ts'
+import { recordVideo } from './recordVideo.ts'
+import { muxVideoAudio } from './voice/ffmpeg.ts'
+import { loadVoiceManifest,synthesizeProjectVoice, voiceDir } from './voice/synthesize.ts'
+import type { VoiceManifest } from './voice/types.ts'
+
+export interface GenerateVideoOptions {
+  preview?: boolean
+  forceSynth?: boolean
+  skipSynth?: boolean
+  distDir: string
+  projectsRoot: string
+}
+
+export interface GenerateVideoResult {
+  projectId: string
+  /** Silent Playwright capture — intermediate only, no audio */
+  silentWebmPath: string
+  /** Upload-ready output — video + voice muxed */
+  finalPath: string
+  manifest: VoiceManifest
+}
+
+/**
+ * Generate the final short: synthesize voice → record silent webm → mux to mp4.
+ * Requires `website:build` (dist/website) unless invoked via npm run video:generate.
+ */
+export async function generateVideo(
+  projectId: string,
+  options: GenerateVideoOptions,
+): Promise<GenerateVideoResult> {
+  loadVideoEnv()
+
+  const projectDir = join(options.projectsRoot, projectId)
+
+  let manifest: VoiceManifest
+  if (options.skipSynth) {
+    const existing = loadVoiceManifest(projectDir)
+    if (!existing) {
+      throw new Error('No voice/manifest.json — run without --skip-synth first')
+    }
+    manifest = existing
+    console.log('\n── 1/3 Voice synthesis (skipped — reusing voice/) ──')
+  } else {
+    console.log('\n── 1/3 Voice synthesis ──')
+    manifest = await synthesizeProjectVoice(projectDir, { force: options.forceSynth ?? false })
+  }
+
+  console.log('\n── 2/3 Record (voice-synced, silent webm) ──')
+  const recorded = await recordVideo(projectId, {
+    preview: options.preview,
+    distDir: options.distDir,
+    projectsRoot: options.projectsRoot,
+    fromGenerate: true,
+  })
+
+  if (!recorded.outputPath) {
+    throw new Error('Recording did not produce a .webm file')
+  }
+
+  const audioPath = join(voiceDir(projectDir), 'full.mp3')
+  const finalPath = finalMp4Path(recorded.outputPath)
+
+  const formatId = parseVideoFormatId(options.preview ? 'shorts-preview' : 'shorts')
+  const deliverable = VIDEO_FORMATS[formatId]
+
+  console.log('\n── 3/3 Mux → final (video + audio) ──')
+  muxVideoAudio(recorded.outputPath, audioPath, finalPath, {
+    videoWidth: deliverable.width,
+    videoHeight: deliverable.height,
+  })
+
+  console.log(formatOutputBanner(finalPath, recorded.outputPath))
+
+  return {
+    projectId,
+    silentWebmPath: recorded.outputPath,
+    finalPath,
+    manifest,
+  }
+}
diff --git a/video/src/loadEnv.ts b/video/src/loadEnv.ts
new file mode 100644
index 0000000..7343d4f
--- /dev/null
+++ b/video/src/loadEnv.ts
@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const VIDEO_ROOT = join(import.meta.dirname, '..')
+
+/** Load `video/.env` into `process.env` (does not override existing vars). */
+export function loadVideoEnv(): void {
+  const envPath = join(VIDEO_ROOT, '.env')
+  if (!existsSync(envPath)) return
+
+  const text = readFileSync(envPath, 'utf8')
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+
+    const key = trimmed.slice(0, eq).trim()
+    let value = trimmed.slice(eq + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+
+    if (!(key in process.env)) process.env[key] = value
+  }
+}
diff --git a/video/src/loadProject.ts b/video/src/loadProject.ts
new file mode 100644
index 0000000..61e702e
--- /dev/null
+++ b/video/src/loadProject.ts
@@ -0,0 +1,139 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getExplorationMeta, themeForExploration } from './explorationRegistry.ts'
+import type {
+  ContentFile,
+  LoadedVideoProject,
+  PlaybookConfig,
+  VideoAnnotationDefinition,
+  VideoContentConfig,
+  VideoHighlightSetDefinition,
+  VideoOverlayDefinition,
+  ZonesFile,
+} from './types.ts'
+import { mergeVoiceTiming } from './voice/mergeTiming.ts'
+import { loadVoiceManifest } from './voice/synthesize.ts'
+
+function readJsonFile<T>(path: string): T {
+  const raw = readFileSync(path, 'utf8')
+  return JSON.parse(raw) as T
+}
+
+function buildContentConfig(contentFile: ContentFile, zones?: ZonesFile): VideoContentConfig {
+  const explorationId = contentFile.meta.exploration
+  const overlays: Record<string, VideoOverlayDefinition> = {}
+  const annotations: Record<string, VideoAnnotationDefinition> = {}
+  const highlightSets: Record<string, VideoHighlightSetDefinition> = {}
+
+  for (const [key, overlay] of Object.entries(contentFile.overlays)) {
+    overlays[key] = { ...overlay, id: key }
+  }
+
+  for (const [key, annotation] of Object.entries(contentFile.annotations ?? {})) {
+    annotations[key] = { ...annotation, id: key }
+  }
+
+  for (const [key, set] of Object.entries(contentFile.highlightSets ?? {})) {
+    highlightSets[key] = { ...set, id: key }
+  }
+
+  const focusAreas: Record<string, { selector: string }> = {}
+  if (zones?.focusAreas) {
+    for (const [key, area] of Object.entries(zones.focusAreas)) {
+      focusAreas[key] = { selector: area.selector }
+    }
+  }
+
+  return {
+    explorationId,
+    theme: themeForExploration(explorationId),
+    overlays,
+    annotations: Object.keys(annotations).length ? annotations : undefined,
+    highlightSets: Object.keys(highlightSets).length ? highlightSets : undefined,
+    focusAreas: Object.keys(focusAreas).length ? focusAreas : undefined,
+  }
+}
+
+function loadZones(projectDir: string): ZonesFile | undefined {
+  const zonesPath = join(projectDir, 'zones.json')
+  try {
+    return readJsonFile<ZonesFile>(zonesPath)
+  } catch {
+    return undefined
+  }
+}
+
+export function loadVideoProject(
+  projectId: string,
+  projectsRoot: string,
+  options: { useVoiceTiming?: boolean } = {},
+): LoadedVideoProject {
+  const projectDir = join(projectsRoot, projectId)
+  const contentPath = join(projectDir, 'content.json')
+  const playbookPath = join(projectDir, 'playbook.json')
+
+  const contentFile = readJsonFile<ContentFile>(contentPath)
+  const playbook = readJsonFile<PlaybookConfig>(playbookPath)
+
+  if (contentFile.meta.exploration !== playbook.exploration) {
+    throw new Error(
+      `content.json exploration (${contentFile.meta.exploration}) != playbook.json (${playbook.exploration})`,
+    )
+  }
+
+  const explorationMeta = getExplorationMeta(playbook.exploration)
+  const zones = loadZones(projectDir)
+  const voiceManifest = loadVoiceManifest(projectDir)
+  const playbookBase = playbook
+  const useVoice = options.useVoiceTiming !== false && voiceManifest !== undefined
+  const playbookResolved = useVoice ? mergeVoiceTiming(playbookBase, voiceManifest) : playbookBase
+
+  return {
+    projectId,
+    projectDir,
+    content: buildContentConfig(contentFile, zones),
+    playbook: playbookResolved,
+    playbookBase,
+    voiceManifest,
+    zones,
+    explorationPath: explorationMeta.path,
+  }
+}
+
+/** Playbook with voice timing applied when manifest exists. */
+export function resolvePlaybook(project: LoadedVideoProject): PlaybookConfig {
+  return project.playbook
+}
+
+export function estimatePlaybookDurationMs(playbook: PlaybookConfig): number {
+  let total = 0
+  for (const step of playbook.steps) {
+    const hasActions =
+      step.selectExample !== undefined ||
+      step.step !== undefined ||
+      step.scroll !== undefined ||
+      step.expandCompanion !== undefined ||
+      step.click !== undefined
+
+    const readMs = step.cue ?? (step.overlay && !hasActions ? step.wait : 0) ?? 0
+    total += readMs
+
+    if (step.step !== undefined) {
+      const action = typeof step.step === 'number' ? { count: step.step } : step.step
+      total += (action.count ?? 1) * (action.interval ?? 400)
+    }
+    if (step.selectExample) total += 800
+    if (step.scroll) total += 700
+    if (step.expandCompanion) total += 500
+
+    const holdMs =
+      step.cue !== undefined && hasActions
+        ? (step.wait ?? 0)
+        : !step.overlay
+          ? (step.wait ?? 0)
+          : 0
+    total += holdMs
+  }
+  return total
+}
diff --git a/video/src/outputPaths.ts b/video/src/outputPaths.ts
new file mode 100644
index 0000000..33cfd07
--- /dev/null
+++ b/video/src/outputPaths.ts
@@ -0,0 +1,25 @@
+import { join } from 'node:path'
+
+/** Silent Playwright capture — intermediate only. */
+export function silentWebmPath(outputDir: string, projectId: string, timestamp: string): string {
+  return join(outputDir, `${projectId}-${timestamp}.webm`)
+}
+
+/** Upload-ready muxed output — video + voice. */
+export function finalMp4Path(webmPath: string): string {
+  return webmPath.replace(/\.webm$/i, '-final.mp4')
+}
+
+export function formatOutputBanner(finalPath: string, silentPath?: string): string {
+  const lines = [
+    '',
+    '═'.repeat(72),
+    'FINAL (video + audio):',
+    `  ${finalPath}`,
+  ]
+  if (silentPath) {
+    lines.push('', 'Intermediate (silent, no audio):', `  ${silentPath}`)
+  }
+  lines.push('═'.repeat(72))
+  return lines.join('\n')
+}
diff --git a/video/src/parseGenerateArgs.ts b/video/src/parseGenerateArgs.ts
new file mode 100644
index 0000000..bad1021
--- /dev/null
+++ b/video/src/parseGenerateArgs.ts
@@ -0,0 +1,28 @@
+export interface GenerateCliArgs {
+  projectId: string
+  preview: boolean
+  forceSynth: boolean
+  /** Reuse voice/full.mp3 — skip ElevenLabs synthesis */
+  skipSynth: boolean
+}
+
+export function parseGenerateCliArgs(argv: string[]): GenerateCliArgs {
+  const positional = argv.filter((a) => !a.startsWith('-'))
+  const projectId = positional[0]
+  if (!projectId) {
+    throw new Error(
+      'Missing project id. Usage: npm run video:generate -- <project-id> [--preview] [--force-synth] [--skip-synth]',
+    )
+  }
+
+  return {
+    projectId,
+    preview: argv.includes('--preview'),
+    forceSynth: argv.includes('--force-synth'),
+    skipSynth: argv.includes('--skip-synth'),
+  }
+}
+
+/** @deprecated Use parseGenerateCliArgs */
+export const parseRenderCliArgs = parseGenerateCliArgs
+export type RenderCliArgs = GenerateCliArgs
diff --git a/video/src/parseProjectArgs.ts b/video/src/parseProjectArgs.ts
new file mode 100644
index 0000000..3fe44a4
--- /dev/null
+++ b/video/src/parseProjectArgs.ts
@@ -0,0 +1,34 @@
+export interface ProjectCliArgs {
+  projectId: string
+  flags: string[]
+}
+
+export function parseProjectArgs(argv: string[]): ProjectCliArgs {
+  const positional = argv.filter((a) => !a.startsWith('-'))
+  const projectId = positional[0]
+  if (!projectId) {
+    throw new Error('Missing project id')
+  }
+  return { projectId, flags: argv.filter((a) => a.startsWith('-')) }
+}
+
+export function parseMuxArgs(argv: string[]): {
+  projectId: string
+  input?: string
+  output?: string
+  preview?: boolean
+} {
+  const { projectId, flags } = parseProjectArgs(argv)
+  let input: string | undefined
+  let output: string | undefined
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--input') input = argv[i + 1]
+    if (argv[i] === '--output') output = argv[i + 1]
+  }
+  if (flags.includes('--help')) {
+    throw new Error(
+      'Usage: npm run voice:mux -- <project-id> [--preview] [--input path/to/video.webm] [--output path/to/out.mp4]',
+    )
+  }
+  return { projectId, input, output, preview: flags.includes('--preview') }
+}
diff --git a/video/src/parseRecordArgs.ts b/video/src/parseRecordArgs.ts
new file mode 100644
index 0000000..657c3bc
--- /dev/null
+++ b/video/src/parseRecordArgs.ts
@@ -0,0 +1,24 @@
+export interface RecordCliArgs {
+  projectId: string
+  preview: boolean
+  dryRun: boolean
+  /** Ignore voice/manifest.json — use manual cue/wait from playbook.json */
+  noVoice: boolean
+}
+
+export function parseRecordCliArgs(argv: string[]): RecordCliArgs {
+  const positional = argv.filter((a) => !a.startsWith('-'))
+  const projectId = positional[0]
+  if (!projectId) {
+    throw new Error(
+      'Missing project id. Usage: npm run record -- <project-id> [--preview] [--dry-run] [--no-voice]',
+    )
+  }
+
+  return {
+    projectId,
+    preview: argv.includes('--preview'),
+    dryRun: argv.includes('--dry-run'),
+    noVoice: argv.includes('--no-voice'),
+  }
+}
diff --git a/video/src/playbookRunner.ts b/video/src/playbookRunner.ts
new file mode 100644
index 0000000..5a28e5a
--- /dev/null
+++ b/video/src/playbookRunner.ts
@@ -0,0 +1,432 @@
+import type { Page } from 'playwright'
+
+import type {
+  PlaybookConfig,
+  PlaybookStep,
+  PlaybookStepAction,
+  VideoContentConfig,
+  VideoOverlayPlacement,
+  ZonesFile,
+} from './types.ts'
+
+export interface PlaybookRunnerOptions {
+  dryRun?: boolean
+  onStep?: (index: number, step: PlaybookStep) => void
+  skipInitialOverlay?: string
+  content?: VideoContentConfig
+  zones?: ZonesFile
+}
+
+function normalizeStepAction(step: number | PlaybookStepAction): PlaybookStepAction {
+  if (typeof step === 'number') return { count: step, interval: 400 }
+  return {
+    count: step.count ?? 1,
+    interval: step.interval ?? 400,
+    climaxFrom: step.climaxFrom,
+    climaxInterval: step.climaxInterval,
+    climaxPauseMs: step.climaxPauseMs,
+    highlightSet: step.highlightSet,
+    highlightAfterStep: step.highlightAfterStep,
+    highlightSetAfter: step.highlightSetAfter,
+    holdAfterClimaxMs: step.holdAfterClimaxMs,
+  }
+}
+
+function stepUsesHighlights(step: PlaybookStep): boolean {
+  if (step.step === undefined) return false
+  const action = normalizeStepAction(step.step)
+  return Boolean(action.highlightSet || action.highlightSetAfter)
+}
+
+function stepHasActions(step: PlaybookStep): boolean {
+  return (
+    step.selectExample !== undefined ||
+    step.step !== undefined ||
+    step.scroll !== undefined ||
+    step.expandCompanion !== undefined ||
+    step.click !== undefined
+  )
+}
+
+const FULLSCREEN_TYPES = new Set(['title-card', 'outro-card', 'title', 'outro'])
+
+function resolvePlacement(
+  step: PlaybookStep,
+  overlayId: string | undefined,
+  content?: VideoContentConfig,
+): VideoOverlayPlacement | undefined {
+  if (step.placement) return step.placement
+  if (!overlayId || !content) return 'top-banner'
+  const def = content.overlays[overlayId]
+  if (!def) return 'top-banner'
+  if (def.placement) return def.placement
+  if (FULLSCREEN_TYPES.has(def.type)) return undefined
+  return 'top-banner'
+}
+
+async function waitForStepButton(page: Page): Promise<void> {
+  const step = page.getByTestId('bytecode-step')
+  await step.waitFor({ state: 'visible', timeout: 15_000 })
+  await page.waitForFunction(
+    () => {
+      const btn = document.querySelector('[data-testid="bytecode-step"]') as HTMLButtonElement | null
+      return btn !== null && !btn.disabled
+    },
+    undefined,
+    { timeout: 15_000 },
+  )
+}
+
+export const VIDEO_FONT_STYLESHEET =
+  'https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Barlow+Condensed:ital,wght@0,700;0,800;0,900;1,700&display=block'
+
+export async function ensureVideoFontsReady(page: Page): Promise<void> {
+  await page.evaluate(async (href) => {
+    if (!document.querySelector('link[data-fyp-video-fonts]')) {
+      const link = document.createElement('link')
+      link.rel = 'stylesheet'
+      link.href = href
+      link.dataset.fypVideoFonts = '1'
+      document.head.appendChild(link)
+    }
+    await Promise.all([
+      document.fonts.load('400 1em "Bebas Neue"'),
+      document.fonts.load('800 1em "Barlow Condensed"'),
+      document.fonts.load('900 1em "Barlow Condensed"'),
+    ])
+    await document.fonts.ready
+  }, VIDEO_FONT_STYLESHEET)
+}
+
+export async function waitForVideoBridge(page: Page): Promise<void> {
+  await page.waitForFunction(
+    () => typeof window.__FYP_VIDEO__?.showOverlay === 'function',
+    undefined,
+    { timeout: 20_000 },
+  )
+}
+
+export async function showOverlay(
+  page: Page,
+  overlayId: string,
+  options: { placement?: VideoOverlayPlacement } = {},
+): Promise<void> {
+  await page.evaluate(
+    ({ id, placement }) => {
+      window.__FYP_VIDEO__!.showOverlay(id, placement ? { placement } : undefined)
+    },
+    { id: overlayId, placement: options.placement },
+  )
+  await page.evaluate(async () => {
+    await document.fonts.ready
+  })
+  await page.waitForTimeout(120)
+}
+
+async function hideOverlay(page: Page): Promise<void> {
+  await page.evaluate(() => window.__FYP_VIDEO__!.hideOverlay())
+}
+
+export async function showAnnotation(page: Page, annotationId: string): Promise<void> {
+  await page.evaluate(
+    (id) => {
+      window.__FYP_VIDEO__!.showAnnotation(id)
+    },
+    annotationId,
+  )
+  await page.waitForTimeout(120)
+}
+
+async function hideAnnotation(page: Page): Promise<void> {
+  await page.evaluate(() => window.__FYP_VIDEO__!.hideAnnotation())
+}
+
+export async function showHighlightSet(page: Page, setId: string): Promise<void> {
+  await page.evaluate((id) => window.__FYP_VIDEO__!.showHighlightSet(id), setId)
+  await page.waitForTimeout(150)
+}
+
+async function hideHighlights(page: Page): Promise<void> {
+  await page.evaluate(() => window.__FYP_VIDEO__!.hideHighlights())
+}
+
+async function scrollStackToTop(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const stack = document.querySelector('[data-testid="bytecode-stack"]') as HTMLElement | null
+    if (stack) stack.scrollTop = 0
+  })
+  await page.waitForTimeout(200)
+}
+
+export async function applyFocus(page: Page, focusKey: string, zones: ZonesFile): Promise<void> {
+  const area = zones.focusAreas[focusKey]
+  if (!area) return
+
+  const safeTop = zones.safeZone?.topPx ?? 0
+  const safeBottom = zones.safeZone?.bottomPx ?? 0
+  const topBanner = zones.placements['top-banner']
+  const reservedTop = topBanner
+    ? safeTop + topBanner.insetPx + topBanner.maxHeightPx + 12
+    : safeTop + 200
+
+  await page.evaluate(
+    ({ selector, padTop, padBottom }) => {
+      const el = document.querySelector(selector)
+      if (!el) return
+      const peek =
+        Number.parseFloat(
+          getComputedStyle(document.documentElement).getPropertyValue('--companion-peek-h'),
+        ) || 56
+      const maxY = window.innerHeight - padBottom - peek
+
+      const rect = el.getBoundingClientRect()
+      if (rect.top < padTop) {
+        el.scrollIntoView({ block: 'start', behavior: 'instant' })
+      }
+      const after = el.getBoundingClientRect()
+      if (after.bottom > maxY) {
+        el.scrollIntoView({ block: 'nearest', behavior: 'instant' })
+      }
+    },
+    { selector: area.selector, padTop: reservedTop, padBottom: safeBottom },
+  )
+  await page.waitForTimeout(350)
+}
+
+async function selectExample(page: Page, exampleKey: string): Promise<void> {
+  await page.getByTestId('example-select').click({ force: true })
+  await page.getByTestId(`example-${exampleKey}`).click({ force: true })
+  await page.waitForTimeout(400)
+  try {
+    await waitForStepButton(page)
+  } catch {
+    // Not all explorations have a step button
+  }
+}
+
+async function scrollBytecodePanels(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const dis = document.querySelector('[data-testid="bytecode-disassembly"]')
+    const activeRow = dis?.querySelector('[data-disassembly-active="true"]')
+    activeRow?.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+
+    const stack = document.querySelector('[data-testid="bytecode-stack"]') as HTMLElement | null
+    if (!stack) return
+
+    const depth = stack.querySelectorAll('[data-stack-depth]').length
+    const opName = activeRow?.querySelector(':last-child')?.textContent ?? ''
+
+    if (/^STOP|RETURN|REVERT|HALT/i.test(opName)) {
+      stack.scrollTop = 0
+      return
+    }
+    if (/DUPN|SWAPN|EXCHANGE/i.test(opName) || depth >= 10) {
+      stack.scrollTop = Math.max(0, stack.scrollHeight - stack.clientHeight)
+      return
+    }
+    stack.scrollTop = 0
+  })
+}
+
+async function clickSteps(page: Page, action: PlaybookStepAction): Promise<void> {
+  const count = action.count ?? 1
+  const interval = action.interval ?? 400
+  const climaxFrom = action.climaxFrom ?? 0
+  const climaxInterval = action.climaxInterval ?? Math.round(interval * 2.6)
+  let climaxPrimed = false
+
+  for (let i = 0; i < count; i++) {
+    const stepNum = i + 1
+    const inClimax = climaxFrom > 0 && stepNum >= climaxFrom
+
+    if (inClimax && action.highlightSet && !climaxPrimed) {
+      if (action.climaxPauseMs) await page.waitForTimeout(action.climaxPauseMs)
+      await showHighlightSet(page, action.highlightSet)
+      climaxPrimed = true
+    }
+
+    const waitMs = inClimax ? climaxInterval : interval
+
+    await waitForStepButton(page)
+    await page.getByTestId('bytecode-step').click({ force: true })
+    await page.waitForTimeout(80)
+    await scrollBytecodePanels(page)
+
+    if (action.highlightAfterStep === stepNum && action.highlightSetAfter) {
+      await scrollStackToTop(page)
+      await showHighlightSet(page, action.highlightSetAfter)
+      if (action.holdAfterClimaxMs) {
+        await page.waitForTimeout(action.holdAfterClimaxMs)
+      }
+    }
+
+    await page.waitForTimeout(Math.max(0, waitMs - 80))
+  }
+}
+
+async function scrollPage(page: Page, selector: string, y = 120): Promise<void> {
+  await page.evaluate(
+    ({ sel, amount }) => {
+      const el = document.querySelector(sel)
+      if (el) el.scrollIntoView({ block: 'center' })
+      window.scrollBy({ top: amount, behavior: 'smooth' })
+    },
+    { sel: selector, amount: y },
+  )
+  await page.waitForTimeout(700)
+}
+
+async function expandCompanion(page: Page, mode: 'half' | 'full'): Promise<void> {
+  await page.evaluate((m) => window.__FYP_VIDEO__!.expandCompanion(m), mode)
+  await page.waitForTimeout(500)
+}
+
+async function runActions(page: Page, step: PlaybookStep): Promise<void> {
+  if (step.selectExample) await selectExample(page, step.selectExample)
+  if (step.step !== undefined) await clickSteps(page, normalizeStepAction(step.step))
+  if (step.scroll) await scrollPage(page, step.scroll.selector, step.scroll.y)
+  if (step.expandCompanion) await expandCompanion(page, step.expandCompanion)
+  if (step.click) await page.getByTestId(step.click).click()
+}
+
+/**
+ * Story beat order: show overlay → focus → cue (read) → hide → reveal actions → hold.
+ */
+async function runStep(
+  page: Page,
+  step: PlaybookStep,
+  options: { skipOverlay?: boolean; content?: VideoContentConfig; zones?: ZonesFile } = {},
+): Promise<void> {
+  const hasActions = stepHasActions(step)
+
+  if (step.annotate) {
+    await showAnnotation(page, step.annotate)
+  }
+
+  if (step.overlay && !options.skipOverlay) {
+    const placement = resolvePlacement(step, step.overlay, options.content)
+    await showOverlay(page, step.overlay, { placement })
+    await page.waitForTimeout(80)
+    if (step.focus && options.zones) {
+      await applyFocus(page, step.focus, options.zones)
+    }
+  }
+
+  const readMs =
+    step.cue ??
+    (step.overlay && !hasActions ? step.wait : undefined) ??
+    0
+  if (readMs > 0) await page.waitForTimeout(readMs)
+
+  const shouldHideAfterCue =
+    step.overlay &&
+    (step.hideOverlay === true ||
+      (step.hideOverlay !== false && hasActions && step.cue !== undefined))
+
+  if (shouldHideAfterCue) {
+    await hideOverlay(page)
+  } else if (step.hideOverlay && !step.overlay) {
+    await hideOverlay(page)
+  }
+
+  await runActions(page, step)
+
+  let holdMs = 0
+  if (hasActions) {
+    holdMs = step.wait ?? 0
+  } else if (step.overlay && step.cue !== undefined) {
+    holdMs = step.wait ?? 0
+  } else if (!step.overlay) {
+    holdMs = step.wait ?? 0
+  }
+  if (holdMs > 0) await page.waitForTimeout(holdMs)
+
+  if (step.annotate) {
+    await hideAnnotation(page)
+  }
+
+  if (stepUsesHighlights(step)) {
+    await hideHighlights(page)
+  }
+}
+
+export async function showLeadInOverlay(page: Page, overlayId: string): Promise<void> {
+  await waitForVideoBridge(page)
+  await ensureVideoFontsReady(page)
+  await showOverlay(page, overlayId)
+  await page
+    .locator('[data-testid="video-title-card"], [data-testid="video-outro-card"]')
+    .first()
+    .waitFor({ state: 'visible', timeout: 10_000 })
+  await page.waitForFunction(() => {
+    const card = document.querySelector(
+      '[data-testid="video-title-card"], [data-testid="video-outro-card"]',
+    )
+    if (!card) return false
+    const { opacity } = getComputedStyle(card)
+    return Number.parseFloat(opacity) >= 0.99
+  })
+  await page.waitForFunction(() => {
+    const title = document.querySelector('.video-card-band__title')
+    if (!title) return false
+    return getComputedStyle(title).fontFamily.toLowerCase().includes('bebas')
+  }, undefined, { timeout: 15_000 })
+  await page.evaluate(
+    () =>
+      new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+      }),
+  )
+  await page.evaluate(() => {
+    document.documentElement.classList.add('fyp-video-lead-in-ready')
+  })
+  // Let Playwright encode several hero-sized title frames before exploration init continues.
+  await page.waitForTimeout(900)
+}
+
+/** Minimum ms to hold lead-in on screen after it renders (recording continues during this). */
+export const LEAD_IN_SETTLE_MS = 900
+
+export async function runPlaybook(
+  page: Page,
+  playbook: PlaybookConfig,
+  options: PlaybookRunnerOptions = {},
+): Promise<void> {
+  await waitForVideoBridge(page)
+
+  let skippedLeadIn = false
+
+  for (let i = 0; i < playbook.steps.length; i++) {
+    const step = playbook.steps[i]!
+    options.onStep?.(i, step)
+    if (options.dryRun) {
+      console.log(`  [dry-run] step ${i + 1}/${playbook.steps.length}:`, JSON.stringify(step))
+      continue
+    }
+    const skipOverlay =
+      !skippedLeadIn &&
+      options.skipInitialOverlay !== undefined &&
+      step.overlay === options.skipInitialOverlay
+    if (skipOverlay) skippedLeadIn = true
+    await runStep(page, step, {
+      skipOverlay,
+      content: options.content,
+      zones: options.zones,
+    })
+  }
+}
+
+export async function waitForExplorationReady(page: Page, explorationId: string): Promise<void> {
+  const rootSelector = `#${explorationId}-c`
+  await page.waitForSelector(rootSelector, {
+    state: 'attached',
+    timeout: 60_000,
+  })
+  await page.waitForSelector('[data-testid="exploration-ready"]', {
+    state: 'attached',
+    timeout: 60_000,
+  })
+  await page.evaluate(async () => {
+    await document.fonts.ready
+  })
+}
diff --git a/video/src/preflight-cli.ts b/video/src/preflight-cli.ts
new file mode 100644
index 0000000..d1731c2
--- /dev/null
+++ b/video/src/preflight-cli.ts
@@ -0,0 +1,36 @@
+import './bootstrap-playwright-env.ts'
+
+import { type ChromiumStatusKind,formatChromiumStatus, inspectChromiumEnvironment } from './chromium.ts'
+
+function statusForAgent(kind: ChromiumStatusKind): string {
+  switch (kind) {
+    case 'ready':
+      return 'ready'
+    case 'og_deps_missing':
+    case 'browser_missing':
+    case 'launch_failed':
+      return 'needs_human_setup'
+    case 'browser_not_executable':
+    case 'needs_agent_permissions':
+      return 'needs_agent_permissions'
+    default:
+      return 'unknown'
+  }
+}
+
+async function main(): Promise<void> {
+  const env = await inspectChromiumEnvironment()
+  const agentStatus = statusForAgent(env.kind)
+
+  console.log(`status: ${agentStatus}`)
+  console.log(formatChromiumStatus(env))
+  if (env.executablePath) console.log(`executable: ${env.executablePath}`)
+  if (env.stamp) console.log(`last_verified: ${env.stamp.checkedAt}`)
+
+  process.exit(agentStatus === 'ready' ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
diff --git a/video/src/record-cli.ts b/video/src/record-cli.ts
new file mode 100644
index 0000000..17c59d0
--- /dev/null
+++ b/video/src/record-cli.ts
@@ -0,0 +1,71 @@
+import './bootstrap-playwright-env.ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { estimatePlaybookDurationMs, loadVideoProject } from './loadProject.ts'
+import { parseRecordCliArgs } from './parseRecordArgs.ts'
+import { buildStoryboard, printStoryboard, validateStoryboard } from './storyboard.ts'
+
+const WEBSITE_ROOT = join(import.meta.dirname, '../..')
+const DIST_DIR = join(WEBSITE_ROOT, 'dist')
+const PROJECTS_ROOT = join(import.meta.dirname, '../projects')
+
+function runDryRun(projectId: string): void {
+  const project = loadVideoProject(projectId, PROJECTS_ROOT)
+  if (project.voiceManifest) {
+    console.log(`Voice timing: ${join(project.projectDir, 'voice/manifest.json')}`)
+  }
+  const timeline = buildStoryboard(project.playbook, project.content)
+
+  console.log(`Project: ${projectId}`)
+  console.log(`Est. duration: ~${Math.round(estimatePlaybookDurationMs(project.playbook) / 1000)}s`)
+  printStoryboard(timeline)
+  const issues = validateStoryboard(project.playbook, project.content, project.zones)
+  if (issues.length) {
+    console.log('\nValidation:')
+    for (const issue of issues) {
+      console.log(`  [${issue.severity.toUpperCase()}] step ${issue.step}: ${issue.message}`)
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  let args: ReturnType<typeof parseRecordCliArgs>
+  try {
+    args = parseRecordCliArgs(process.argv.slice(2))
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  }
+
+  const projectDir = join(PROJECTS_ROOT, args.projectId)
+  if (!existsSync(projectDir)) {
+    console.error(`Unknown project: ${args.projectId}`)
+    console.error(`Expected: video/projects/${args.projectId}/`)
+    process.exit(1)
+  }
+
+  if (args.dryRun) {
+    runDryRun(args.projectId)
+    return
+  }
+
+  if (!existsSync(join(DIST_DIR, 'website'))) {
+    console.error('Website build not found. Run first: npm run website:build')
+    process.exit(1)
+  }
+
+  const { recordVideo } = await import('./recordVideo.ts')
+  await recordVideo(args.projectId, {
+    preview: args.preview,
+    dryRun: false,
+    distDir: DIST_DIR,
+    projectsRoot: PROJECTS_ROOT,
+    noVoice: args.noVoice,
+  })
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
diff --git a/video/src/recordVideo.ts b/video/src/recordVideo.ts
new file mode 100644
index 0000000..3d6502d
--- /dev/null
+++ b/video/src/recordVideo.ts
@@ -0,0 +1,192 @@
+import { mkdirSync, readdirSync, renameSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { startStaticServer } from '../../og/src/server.ts'
+import { assertChromiumReady } from './chromium.ts'
+import { parseVideoFormatId, VIDEO_FORMATS, VIDEO_RECORD_FORMAT } from './formats.ts'
+import { estimatePlaybookDurationMs, loadVideoProject } from './loadProject.ts'
+import { ensureVideoFontsReady, runPlaybook, showLeadInOverlay, waitForExplorationReady } from './playbookRunner.ts'
+import { trimVideoLeadIn } from './trimLeadIn.ts'
+import type { LoadedVideoProject } from './types.ts'
+
+export interface RecordVideoOptions {
+  preview?: boolean
+  distDir: string
+  projectsRoot: string
+  /** When true, ignore voice/manifest.json for playbook timing */
+  noVoice?: boolean
+  /** Internal: called from generateVideo — adjusts console hints */
+  fromGenerate?: boolean
+}
+
+export interface RecordVideoResult {
+  project: LoadedVideoProject
+  outputPath?: string
+  estimatedDurationMs: number
+}
+
+function websiteDistPath(distDir: string): string {
+  const path = join(distDir, 'website')
+  try {
+    if (!statSync(path).isDirectory()) throw new Error('not a directory')
+  } catch {
+    throw new Error(`Missing build output: ${path}\nRun: npm run website:build`)
+  }
+  return path
+}
+
+function buildExplorationUrl(baseUrl: string, project: LoadedVideoProject, example?: string): string {
+  const params = new URLSearchParams({ 'fyp-video': '1' })
+  if (example) params.set('example', example)
+  return `${baseUrl}${project.explorationPath}?${params.toString()}`
+}
+
+function collectNewestWebm(dir: string, before: Set<string>): string | undefined {
+  const after = readdirSync(dir).filter((f) => f.endsWith('.webm'))
+  const added = after.filter((f) => !before.has(f))
+  if (added.length === 0) return undefined
+  const paths = added.map((f) => join(dir, f))
+  paths.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+  return paths[0]
+}
+
+export async function recordVideo(
+  projectId: string,
+  options: RecordVideoOptions,
+): Promise<RecordVideoResult> {
+  const project = loadVideoProject(projectId, options.projectsRoot, {
+    useVoiceTiming: !options.noVoice,
+  })
+  const deliverableId = parseVideoFormatId(
+    options.preview ? 'shorts-preview' : project.playbook.format,
+  )
+  const deliverable = VIDEO_FORMATS[deliverableId]
+  const recordFormat = VIDEO_RECORD_FORMAT
+  const estimatedDurationMs = estimatePlaybookDurationMs(project.playbook)
+
+  console.log(`Project: ${projectId}`)
+  console.log(`Record:  ${recordFormat.viewportWidth}×${recordFormat.viewportHeight} (layout reference)`)
+  console.log(`Output:  ${deliverable.width}×${deliverable.height}${options.preview ? '' : ' (2× upscale on mux)'}`)
+  if (project.voiceManifest) {
+    console.log(`Voice:   ~${Math.round(project.voiceManifest.totalDurationMs / 1000)}s (synced playbook)`)
+  }
+  console.log(`Est. duration: ~${Math.round(estimatedDurationMs / 1000)}s`)
+
+  await assertChromiumReady()
+
+  const distRoot = websiteDistPath(options.distDir)
+  const server = await startStaticServer(distRoot)
+  const outputDir = join(project.projectDir, 'output')
+  mkdirSync(outputDir, { recursive: true })
+
+  const existingWebms = new Set(readdirSync(outputDir).filter((f) => f.endsWith('.webm')))
+
+  const { chromium } = await import('playwright')
+  const browser = await chromium.launch({ headless: true })
+
+  try {
+    const context = await browser.newContext({
+      viewport: { width: recordFormat.viewportWidth, height: recordFormat.viewportHeight },
+      deviceScaleFactor: recordFormat.deviceScaleFactor,
+      recordVideo: {
+        dir: outputDir,
+        // Must match reference viewport — deliverable upscale happens at mux time.
+        size: { width: recordFormat.viewportWidth, height: recordFormat.viewportHeight },
+      },
+    })
+
+    const page = await context.newPage()
+
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') console.error(`  [page] ${msg.text()}`)
+    })
+
+    await page.addInitScript((config) => {
+      window.__FYP_VIDEO_CONFIG__ = config
+      document.documentElement.classList.add('fyp-video-capture')
+      document.documentElement.style.backgroundColor = '#000'
+      if (document.body) document.body.style.backgroundColor = '#000'
+      const href =
+        'https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Barlow+Condensed:ital,wght@0,700;0,800;0,900;1,700&display=block'
+      if (!document.querySelector('link[data-fyp-video-fonts]')) {
+        const link = document.createElement('link')
+        link.rel = 'stylesheet'
+        link.href = href
+        link.dataset.fypVideoFonts = '1'
+        document.head.appendChild(link)
+      }
+      const explorationRoot = `#${config.explorationId}-c`
+      const style = document.createElement('style')
+      style.dataset.fypVideoLeadIn = '1'
+      style.textContent = `
+        html.fyp-video-capture:not(.fyp-video-lead-in-ready) ${explorationRoot} {
+          visibility: hidden !important;
+        }
+      `
+      document.documentElement.appendChild(style)
+    }, project.content)
+
+    const url = buildExplorationUrl(server.url, project, project.playbook.defaultExample)
+
+    console.log(`Recording: ${url}`)
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 })
+
+    await ensureVideoFontsReady(page)
+
+    const firstStep = project.playbook.steps[0]
+    const leadInOverlay = firstStep?.overlay
+
+    if (leadInOverlay) {
+      console.log(`Lead-in: ${leadInOverlay}`)
+      await showLeadInOverlay(page, leadInOverlay)
+    }
+
+    // Load exploration behind the title card (EVM init can take several seconds).
+    await waitForExplorationReady(page, project.content.explorationId)
+
+    console.log('Running playbook…')
+    await runPlaybook(page, project.playbook, {
+      skipInitialOverlay: leadInOverlay,
+      content: project.content,
+      zones: project.zones,
+      onStep: (i, step) => {
+        const label = step.overlay ?? step.selectExample ?? step.step ?? 'action'
+        console.log(`  step ${i + 1}: ${typeof label === 'object' ? 'step' : label}`)
+      },
+    })
+
+    await page.waitForTimeout(500)
+    await context.close()
+
+    const rawWebm = collectNewestWebm(outputDir, existingWebms)
+    if (!rawWebm) {
+      throw new Error('Playwright did not produce a .webm file')
+    }
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+    const finalPath = join(outputDir, `${projectId}-${timestamp}.webm`)
+    renameSync(rawWebm, finalPath)
+
+    console.log('Verifying lead-in preview frame…')
+    const trim = trimVideoLeadIn(finalPath)
+    if (trim.trimmedSec > 0) {
+      console.log(
+        `  Trimmed ${trim.trimmedSec.toFixed(2)}s black lead-in (luminance ${trim.maxLuminanceBefore} → ${trim.maxLuminanceAfter})`,
+      )
+    } else {
+      console.log(`  Lead-in OK (luminance ${trim.maxLuminanceAfter})`)
+    }
+
+    console.log(`Saved (silent intermediate — no audio): ${finalPath}`)
+    if (project.voiceManifest && !options.fromGenerate && !options.noVoice) {
+      const flags = [options.preview ? '--preview' : '', '--skip-synth'].filter(Boolean).join(' ')
+      console.log(
+        `\nTo mux voice into the final upload file:\n  npm run video:generate -- ${projectId} ${flags}`.trimEnd(),
+      )
+    }
+    return { project, outputPath: finalPath, estimatedDurationMs }
+  } finally {
+    await browser.close()
+    await server.close()
+  }
+}
diff --git a/video/src/storyboard-cli.ts b/video/src/storyboard-cli.ts
new file mode 100644
index 0000000..eb9abd8
--- /dev/null
+++ b/video/src/storyboard-cli.ts
@@ -0,0 +1,46 @@
+import './bootstrap-playwright-env.ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { loadVideoProject, resolvePlaybook } from './loadProject.ts'
+import { buildStoryboard, printStoryboard, validateStoryboard } from './storyboard.ts'
+
+const PROJECTS_ROOT = join(import.meta.dirname, '../projects')
+
+function main(): void {
+  const projectId = process.argv[2]
+  if (!projectId) {
+    console.error('Usage: npm run storyboard -- <project-id>')
+    process.exit(1)
+  }
+
+  const projectDir = join(PROJECTS_ROOT, projectId)
+  if (!existsSync(projectDir)) {
+    console.error(`Unknown project: ${projectId}`)
+    process.exit(1)
+  }
+
+  const project = loadVideoProject(projectId, PROJECTS_ROOT)
+  const playbook = resolvePlaybook(project)
+  const timeline = buildStoryboard(playbook, project.content)
+  const issues = validateStoryboard(playbook, project.content, project.zones)
+
+  console.log(`Project: ${projectId}`)
+  if (project.voiceManifest) {
+    console.log(`Voice timing: manifest (${Math.round(project.voiceManifest.totalDurationMs / 1000)}s)`)
+  }
+  printStoryboard(timeline)
+
+  if (issues.length > 0) {
+    console.log('\nValidation:')
+    for (const issue of issues) {
+      const prefix = issue.severity === 'error' ? 'ERROR' : 'WARN'
+      console.log(`  [${prefix}] step ${issue.step}${issue.beat ? ` (${issue.beat})` : ''}: ${issue.message}`)
+    }
+    if (issues.some((i) => i.severity === 'error')) process.exit(1)
+  } else {
+    console.log('\nValidation: OK')
+  }
+}
+
+main()
diff --git a/video/src/storyboard.ts b/video/src/storyboard.ts
new file mode 100644
index 0000000..b184d39
--- /dev/null
+++ b/video/src/storyboard.ts
@@ -0,0 +1,321 @@
+import type {
+  PlaybookConfig,
+  PlaybookStep,
+  PlaybookStepAction,
+  VideoContentConfig,
+  ZonesFile,
+} from './types.ts'
+
+export interface StoryboardEntry {
+  index: number
+  beat?: string
+  phase: 'title' | 'cue' | 'reveal' | 'hold' | 'pause' | 'guide'
+  overlay?: string
+  annotation?: string
+  placement?: string
+  focus?: string
+  durationMs: number
+  label: string
+}
+
+export interface StoryboardTimeline {
+  entries: StoryboardEntry[]
+  totalMs: number
+}
+
+function stepHasActions(step: PlaybookStep): boolean {
+  return (
+    step.selectExample !== undefined ||
+    step.step !== undefined ||
+    step.scroll !== undefined ||
+    step.expandCompanion !== undefined ||
+    step.click !== undefined
+  )
+}
+
+function stepAction(step: PlaybookStep): PlaybookStepAction | undefined {
+  if (step.step === undefined) return undefined
+  return typeof step.step === 'number' ? { count: step.step } : step.step
+}
+
+function actionDuration(step: PlaybookStep): number {
+  let total = 0
+  if (step.selectExample) total += 800
+  const action = stepAction(step)
+  if (action) {
+    const count = action.count ?? 1
+    const interval = action.interval ?? 400
+    const climaxFrom = action.climaxFrom ?? 0
+    const climaxInterval = action.climaxInterval ?? Math.round(interval * 2.6)
+    const climaxPauseMs = action.climaxPauseMs ?? 0
+    const holdAfterClimaxMs = action.holdAfterClimaxMs ?? 0
+
+    for (let i = 0; i < count; i++) {
+      const stepNum = i + 1
+      const inClimax = climaxFrom > 0 && stepNum >= climaxFrom
+      if (inClimax && action.highlightSet && stepNum === climaxFrom) {
+        total += climaxPauseMs + 150
+      }
+      total += inClimax ? climaxInterval : interval
+      if (action.highlightAfterStep === stepNum) {
+        total += 350 + holdAfterClimaxMs
+      }
+    }
+  }
+  if (step.scroll) total += 700
+  if (step.expandCompanion) total += 500
+  return total
+}
+
+function formatTime(ms: number): string {
+  const s = ms / 1000
+  const m = Math.floor(s / 60)
+  const r = s - m * 60
+  return `${String(m).padStart(2, '0')}:${r.toFixed(1).padStart(4, '0')}`
+}
+
+export function buildStoryboard(
+  playbook: PlaybookConfig,
+  content?: VideoContentConfig,
+): StoryboardTimeline {
+  const entries: StoryboardEntry[] = []
+  let cursor = 0
+
+  for (let i = 0; i < playbook.steps.length; i++) {
+    const step = playbook.steps[i]!
+    const hasActions = stepHasActions(step)
+    const beat = step.beat ?? `step-${i + 1}`
+    const overlayDef = step.overlay && content?.overlays[step.overlay]
+    const annotationDef = step.annotate && content?.annotations?.[step.annotate]
+
+    if (step.annotate && annotationDef) {
+      entries.push({
+        index: i,
+        beat,
+        phase: 'guide',
+        annotation: step.annotate,
+        focus: annotationDef.target,
+        durationMs: 0,
+        label: `GUIDE → ${annotationDef.label} (parallel through beat)`,
+      })
+    }
+
+    if (step.overlay) {
+      const readMs = step.cue ?? (hasActions ? 0 : (step.wait ?? 0))
+      if (readMs > 0) {
+        entries.push({
+          index: i,
+          beat,
+          phase: overlayDef?.type === 'title-card' || overlayDef?.type === 'outro-card' ? 'title' : 'cue',
+          overlay: step.overlay,
+          placement: step.placement ?? overlayDef?.placement,
+          focus: step.focus,
+          durationMs: readMs,
+          label: `READ  "${overlayLabel(step.overlay, content)}"`,
+        })
+        cursor += readMs
+      }
+    }
+
+    if (
+      step.overlay &&
+      (step.hideOverlay === true ||
+        (hasActions && step.hideOverlay !== false && step.cue !== undefined))
+    ) {
+      entries.push({
+        index: i,
+        beat,
+        phase: 'reveal',
+        durationMs: 0,
+        label: 'HIDE overlay → reveal exploration',
+      })
+    }
+
+    if (step.hideOverlay && !step.overlay) {
+      entries.push({
+        index: i,
+        beat,
+        phase: 'pause',
+        durationMs: 0,
+        label: 'HIDE overlay',
+      })
+    }
+
+    const actionMs = actionDuration(step)
+    if (actionMs > 0) {
+      entries.push({
+        index: i,
+        beat,
+        phase: 'reveal',
+        focus: step.focus,
+        durationMs: actionMs,
+        label: revealLabel(step),
+      })
+      cursor += actionMs
+    }
+
+    const holdMs =
+      step.cue !== undefined && hasActions
+        ? (step.wait ?? 0)
+        : step.overlay && !hasActions
+          ? 0
+          : !step.overlay
+            ? (step.wait ?? 0)
+            : 0
+    if (holdMs > 0) {
+      entries.push({
+        index: i,
+        beat,
+        phase: 'hold',
+        focus: step.focus,
+        durationMs: holdMs,
+        label: 'HOLD (let viewer absorb)',
+      })
+      cursor += holdMs
+    }
+  }
+
+  return { entries, totalMs: cursor }
+}
+
+function overlayLabel(id: string, content?: VideoContentConfig): string {
+  const o = content?.overlays[id]
+  if (!o) return id
+  if (o.closing) return o.closing
+  if (o.ctas?.length) return o.ctas.map((c) => `${c.label} → ${c.url}`).join(' · ')
+  return o.text ?? o.headline ?? o.title ?? o.primary ?? o.cta ?? o.segments?.[0]?.text ?? id
+}
+
+function revealLabel(step: PlaybookStep): string {
+  const parts: string[] = []
+  if (step.selectExample) parts.push(`select ${step.selectExample}`)
+  if (step.step !== undefined) {
+    const a = typeof step.step === 'number' ? { count: step.step } : step.step
+    parts.push(`step ×${a.count ?? 1}`)
+  }
+  if (step.scroll) parts.push('scroll')
+  if (step.expandCompanion) parts.push(`companion ${step.expandCompanion}`)
+  if (step.click) parts.push(`click ${step.click}`)
+  return `REVEAL  ${parts.join(', ')}`
+}
+
+export function printStoryboard(timeline: StoryboardTimeline): void {
+  let cursor = 0
+  console.log('Storyboard timeline')
+  console.log('─'.repeat(72))
+  for (const entry of timeline.entries) {
+    const at = formatTime(cursor)
+    const dur = entry.durationMs > 0 ? ` (${Math.round(entry.durationMs / 100) / 10}s)` : ''
+    const meta = [
+      entry.overlay ? `overlay=${entry.overlay}` : '',
+      entry.annotation ? `annotate=${entry.annotation}` : '',
+      entry.placement ? `placement=${entry.placement}` : '',
+      entry.focus ? `focus=${entry.focus}` : '',
+    ]
+      .filter(Boolean)
+      .join(' ')
+    console.log(`${at}  [${entry.phase.toUpperCase()}] ${entry.label}${dur}`)
+    if (meta) console.log(`         ${meta}`)
+    cursor += entry.durationMs
+  }
+  console.log('─'.repeat(72))
+  console.log(`Total: ~${Math.round(timeline.totalMs / 1000)}s`)
+}
+
+export interface StoryboardIssue {
+  step: number
+  beat?: string
+  severity: 'error' | 'warn'
+  message: string
+}
+
+export function validateStoryboard(
+  playbook: PlaybookConfig,
+  content?: VideoContentConfig,
+  zones?: ZonesFile,
+): StoryboardIssue[] {
+  const issues: StoryboardIssue[] = []
+
+  for (let i = 0; i < playbook.steps.length; i++) {
+    const step = playbook.steps[i]!
+    const hasActions = stepHasActions(step)
+
+    if (step.overlay && hasActions && step.cue === undefined && step.hideOverlay !== true) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'warn',
+        message:
+          'Overlay and actions in same beat without `cue` — text may cover the action. Add cue (read ms) then hide before reveal.',
+      })
+    }
+
+    if (step.overlay && hasActions && step.cue !== undefined && step.cue < 1200) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'warn',
+        message: `Cue ${step.cue}ms is short for reading — consider ≥1800ms.`,
+      })
+    }
+
+    if (step.focus && zones && !zones.focusAreas[step.focus]) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'error',
+        message: `Unknown focus "${step.focus}" — add to zones.json.`,
+      })
+    }
+
+    if (step.overlay && content && !content.overlays[step.overlay]) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'error',
+        message: `Unknown overlay "${step.overlay}" in content.json.`,
+      })
+    }
+
+    if (step.annotate && content && !content.annotations?.[step.annotate]) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'error',
+        message: `Unknown annotation "${step.annotate}" in content.json.`,
+      })
+    }
+
+    if (step.annotate && content?.annotations?.[step.annotate] && zones) {
+      const target = content.annotations[step.annotate]!.target
+      if (!zones.focusAreas[target] && !target.startsWith('[') && !target.startsWith('.')) {
+        issues.push({
+          step: i + 1,
+          beat: step.beat,
+          severity: 'error',
+          message: `Annotation target "${target}" not in zones.json focusAreas.`,
+        })
+      }
+    }
+
+    const action = stepAction(step)
+    if (action?.highlightSet && content && !content.highlightSets?.[action.highlightSet]) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'error',
+        message: `Unknown highlightSet "${action.highlightSet}" in content.json.`,
+      })
+    }
+    if (action?.highlightSetAfter && content && !content.highlightSets?.[action.highlightSetAfter]) {
+      issues.push({
+        step: i + 1,
+        beat: step.beat,
+        severity: 'error',
+        message: `Unknown highlightSetAfter "${action.highlightSetAfter}" in content.json.`,
+      })
+    }
+  }
+
+  return issues
+}
diff --git a/video/src/trimLeadIn.ts b/video/src/trimLeadIn.ts
new file mode 100644
index 0000000..a952a41
--- /dev/null
+++ b/video/src/trimLeadIn.ts
@@ -0,0 +1,283 @@
+import { execFileSync } from 'node:child_process'
+import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+/** Scan step when searching for the first title-card frame. */
+const SCAN_INTERVAL_SEC = 0.05
+/** How far into the file we look for the lead-in overlay. */
+const MAX_SCAN_SEC = 12
+/**
+ * Minimum peak RGB in the center crop — title cards have white/purple text on black.
+ * Pure black lead-in + companion peek stays well below this.
+ */
+export const LEAD_IN_LUMINANCE_THRESHOLD = 72
+/** Title band center must be true black — exploration UI lavender fails this (min ≈ 25+). */
+export const LEAD_IN_MIN_DARK_THRESHOLD = 20
+/** Share of center-crop pixels that must be near-black (title band bg vs exploration UI). */
+export const LEAD_IN_MIN_DARK_PIXEL_RATIO = 0.35
+/** Mean luminance cap — exploration UI center crop averages ~240+ on white/lavender. */
+export const LEAD_IN_MAX_MEAN_LUMINANCE = 120
+/** Title at hero size spans at least this many px vertically in the center crop. */
+export const LEAD_IN_MIN_TEXT_SPAN_PX = 100
+
+export interface CenterLuminanceStats {
+  min: number
+  max: number
+  /** Vertical span of bright (title) pixels in the center crop. */
+  textSpanPx: number
+  /** Fraction of pixels with max channel ≤ LEAD_IN_MIN_DARK_THRESHOLD. */
+  darkPixelRatio: number
+  meanLuminance: number
+}
+
+function assertFfmpegAvailable(): void {
+  try {
+    execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' })
+  } catch {
+    throw new Error('ffmpeg is required for video lead-in trim/verify. Install ffmpeg and retry.')
+  }
+}
+
+function getVideoDimensions(videoPath: string): { width: number; height: number } {
+  try {
+    const raw = execFileSync(
+      'ffprobe',
+      [
+        '-hide_banner',
+        '-v',
+        'error',
+        '-select_streams',
+        'v:0',
+        '-show_entries',
+        'stream=width,height',
+        '-of',
+        'json',
+        videoPath,
+      ],
+      { encoding: 'utf8' },
+    )
+    const stream = (JSON.parse(raw) as { streams?: { width?: number; height?: number }[] })
+      .streams?.[0]
+    if (stream?.width && stream?.height) {
+      return { width: stream.width, height: stream.height }
+    }
+  } catch {
+    /* fall through */
+  }
+  return { width: 540, height: 960 }
+}
+
+export function extractCenterLuminanceStats(videoPath: string, timeSec: number): CenterLuminanceStats {
+  const tmp = join(tmpdir(), `fyp-vframe-${process.pid}-${Date.now()}.raw`)
+  const empty: CenterLuminanceStats = {
+    min: 255,
+    max: 0,
+    textSpanPx: 0,
+    darkPixelRatio: 0,
+    meanLuminance: 255,
+  }
+  try {
+    const { width: vw, height: vh } = getVideoDimensions(videoPath)
+    const cropW = Math.max(1, Math.floor(vw * 0.6))
+    const cropH = Math.max(1, Math.floor(vh * 0.35))
+
+    execFileSync(
+      'ffmpeg',
+      [
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-y',
+        '-ss',
+        String(timeSec),
+        '-i',
+        videoPath,
+        '-frames:v',
+        '1',
+        '-vf',
+        'crop=iw*0.6:ih*0.35:iw*0.2:ih*0.30',
+        '-f',
+        'rawvideo',
+        '-pix_fmt',
+        'rgb24',
+        tmp,
+      ],
+      { stdio: ['ignore', 'ignore', 'pipe'] },
+    )
+    const buf = readFileSync(tmp)
+    let min = 255
+    let max = 0
+    let brightMinY = Infinity
+    let brightMaxY = -1
+    let darkPixels = 0
+    let lumSum = 0
+    let pixelCount = 0
+
+    for (let i = 0; i + 2 < buf.length; i += 3) {
+      const lum = Math.max(buf[i]!, buf[i + 1]!, buf[i + 2]!)
+      if (lum > max) max = lum
+      if (lum < min) min = lum
+      if (lum <= LEAD_IN_MIN_DARK_THRESHOLD) darkPixels++
+      lumSum += lum
+      pixelCount++
+      if (lum >= LEAD_IN_LUMINANCE_THRESHOLD) {
+        const y = Math.floor(i / 3 / cropW)
+        if (y < brightMinY) brightMinY = y
+        if (y > brightMaxY) brightMaxY = y
+      }
+    }
+    const textSpanPx =
+      brightMaxY >= brightMinY && brightMaxY < cropH ? brightMaxY - brightMinY + 1 : 0
+    return {
+      min,
+      max,
+      textSpanPx,
+      darkPixelRatio: pixelCount > 0 ? darkPixels / pixelCount : 0,
+      meanLuminance: pixelCount > 0 ? lumSum / pixelCount : 255,
+    }
+  } catch {
+    return empty
+  } finally {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** Title/outro band: bright text on a dark center panel at hero size (rejects exploration UI). */
+export function isTitleBandFrame(
+  stats: CenterLuminanceStats,
+  maxThreshold = LEAD_IN_LUMINANCE_THRESHOLD,
+  minDarkThreshold = LEAD_IN_MIN_DARK_THRESHOLD,
+  minTextSpanPx = LEAD_IN_MIN_TEXT_SPAN_PX,
+  minDarkPixelRatio = LEAD_IN_MIN_DARK_PIXEL_RATIO,
+  maxMeanLuminance = LEAD_IN_MAX_MEAN_LUMINANCE,
+): boolean {
+  return (
+    stats.max >= maxThreshold &&
+    stats.min <= minDarkThreshold &&
+    stats.textSpanPx >= minTextSpanPx &&
+    stats.darkPixelRatio >= minDarkPixelRatio &&
+    stats.meanLuminance <= maxMeanLuminance
+  )
+}
+
+/** Find the first timestamp where the title/lead-in content is visible. */
+export function findLeadInTrimSec(
+  videoPath: string,
+  maxThreshold = LEAD_IN_LUMINANCE_THRESHOLD,
+  minDarkThreshold = LEAD_IN_MIN_DARK_THRESHOLD,
+  minTextSpanPx = LEAD_IN_MIN_TEXT_SPAN_PX,
+): number {
+  for (let t = 0; t <= MAX_SCAN_SEC; t += SCAN_INTERVAL_SEC) {
+    const stats = extractCenterLuminanceStats(videoPath, t)
+    if (isTitleBandFrame(stats, maxThreshold, minDarkThreshold, minTextSpanPx)) {
+      return t
+    }
+  }
+  return 0
+}
+
+export function verifyVideoLeadIn(
+  videoPath: string,
+  maxThreshold = LEAD_IN_LUMINANCE_THRESHOLD,
+  minDarkThreshold = LEAD_IN_MIN_DARK_THRESHOLD,
+  minTextSpanPx = LEAD_IN_MIN_TEXT_SPAN_PX,
+): { ok: boolean; maxLuminance: number; minLuminance: number; textSpanPx: number; darkPixelRatio: number; meanLuminance: number } {
+  const stats = extractCenterLuminanceStats(videoPath, 0)
+  return {
+    ok: isTitleBandFrame(stats, maxThreshold, minDarkThreshold, minTextSpanPx),
+    maxLuminance: stats.max,
+    minLuminance: stats.min,
+    textSpanPx: stats.textSpanPx,
+    darkPixelRatio: stats.darkPixelRatio,
+    meanLuminance: stats.meanLuminance,
+  }
+}
+
+export interface TrimLeadInResult {
+  trimmedSec: number
+  maxLuminanceBefore: number
+  maxLuminanceAfter: number
+}
+
+/**
+ * Trim black/unstyled lead-in so frame 0 matches the title card (preview thumbnail).
+ * Returns how many seconds were removed (0 if already OK).
+ */
+export function trimVideoLeadIn(videoPath: string): TrimLeadInResult {
+  assertFfmpegAvailable()
+
+  const before = verifyVideoLeadIn(videoPath)
+  if (before.ok) {
+    return {
+      trimmedSec: 0,
+      maxLuminanceBefore: before.maxLuminance,
+      maxLuminanceAfter: before.maxLuminance,
+    }
+  }
+
+  const trimSec = findLeadInTrimSec(videoPath)
+  if (trimSec <= 0.01) {
+    throw new Error(
+      `Video has no valid lead-in frame in the first ${MAX_SCAN_SEC}s (peak luminance ${before.maxLuminance}). Ensure the first playbook step is a title-card.`,
+    )
+  }
+
+  const tmpOut = `${videoPath}.trim.webm`
+  try {
+    execFileSync(
+      'ffmpeg',
+      [
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-y',
+        '-ss',
+        String(trimSec),
+        '-i',
+        videoPath,
+        '-c:v',
+        'libvpx-vp9',
+        '-crf',
+        '32',
+        '-b:v',
+        '0',
+        '-an',
+        tmpOut,
+      ],
+      { stdio: ['ignore', 'ignore', 'pipe'] },
+    )
+  } catch (err) {
+    throw new Error(
+      `Failed to trim video lead-in (${trimSec.toFixed(2)}s): ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+
+  if (!existsSync(tmpOut)) {
+    throw new Error('ffmpeg did not produce trimmed output')
+  }
+
+  renameSync(tmpOut, videoPath)
+
+  const after = verifyVideoLeadIn(videoPath)
+  if (!after.ok) {
+    throw new Error(
+      `Video lead-in still invalid after trim (center min/max/span/mean/dark ${after.minLuminance}/${after.maxLuminance}/${after.textSpanPx}/${Math.round(after.meanLuminance ?? 0)}/${((after.darkPixelRatio ?? 0) * 100).toFixed(1)}%; need dark ≥ ${LEAD_IN_MIN_DARK_PIXEL_RATIO * 100}%, mean ≤ ${LEAD_IN_MAX_MEAN_LUMINANCE}). Check lead-in overlay setup.`,
+    )
+  }
+
+  return {
+    trimmedSec: trimSec,
+    maxLuminanceBefore: before.maxLuminance,
+    maxLuminanceAfter: after.maxLuminance,
+  }
+}
+
+/** Copy helper for tests. */
+export function copyVideoForTest(src: string, dest: string): void {
+  copyFileSync(src, dest)
+}
diff --git a/video/src/types.ts b/video/src/types.ts
new file mode 100644
index 0000000..55780e2
--- /dev/null
+++ b/video/src/types.ts
@@ -0,0 +1,200 @@
+/** Mirrors src/video/types.ts — kept in the isolated package for playbook tooling. */
+
+export type VideoOverlayType =
+  | 'title-card'
+  | 'outro-card'
+  | 'punch'
+  | 'split'
+  | 'callout'
+  | 'list-flash'
+  | 'banner'
+  /** @deprecated */
+  | 'title'
+  | 'list'
+  | 'outro'
+
+export type VideoOverlayPlacement =
+  | 'top-banner'
+  | 'bottom-banner'
+  | 'top'
+  | 'center'
+  | 'bottom'
+
+export interface VideoTheme {
+  bg: string
+  text: string
+  accent: string
+  badgeBg?: string
+}
+
+export interface VideoTextSegment {
+  text: string
+  size?: 'md' | 'lg' | 'xl' | 'hero'
+  emphasis?: boolean
+  slot?: 'a' | 'b' | 'c'
+}
+
+export interface VideoOutroCta {
+  label: string
+  url: string
+  variant?: 'primary' | 'secondary'
+}
+
+export interface VideoFocusAreaRef {
+  selector: string
+}
+
+export type AnnotationCalloutSide = 'top' | 'bottom' | 'left' | 'right'
+
+export interface VideoAnnotationDefinition {
+  id: string
+  target: string
+  label: string
+  hint?: string
+  side?: AnnotationCalloutSide | 'auto'
+}
+
+export interface VideoHighlightMarkDefinition {
+  target: string
+  pad?: number
+  padX?: number
+  padY?: number
+  /** @deprecated No longer used */
+  tilt?: number
+  /** @deprecated Labels removed — marker-only highlights */
+  label?: string
+}
+
+export interface VideoHighlightSetDefinition {
+  id: string
+  marks: VideoHighlightMarkDefinition[]
+}
+
+export interface VideoOverlayDefinition {
+  type: VideoOverlayType
+  id: string
+  placement?: VideoOverlayPlacement
+  layout?: 'banner' | 'scatter'
+  eyebrow?: string
+  title?: string
+  subtitle?: string
+  hook?: string[]
+  text?: string
+  sub?: string
+  position?: 'top' | 'center' | 'bottom'
+  invert?: boolean
+  segments?: VideoTextSegment[]
+  headline?: string
+  items?: string[]
+  primary?: string
+  cta?: string
+  secondary?: string
+  closing?: string
+  ctas?: VideoOutroCta[]
+  lines?: string[]
+  question?: string
+}
+
+export interface VideoContentConfig {
+  explorationId: string
+  theme?: VideoTheme
+  overlays: Record<string, VideoOverlayDefinition>
+  annotations?: Record<string, VideoAnnotationDefinition>
+  highlightSets?: Record<string, VideoHighlightSetDefinition>
+  focusAreas?: Record<string, VideoFocusAreaRef>
+}
+
+export interface PlaybookStepAction {
+  count?: number
+  interval?: number
+  /** 1-based step index to enter slow-mo + optional highlightSet */
+  climaxFrom?: number
+  climaxInterval?: number
+  /** Pause before the first climax step (anticipation beat) */
+  climaxPauseMs?: number
+  highlightSet?: string
+  /** Switch highlights after this step number completes */
+  highlightAfterStep?: number
+  highlightSetAfter?: string
+  /** Extra hold after payoff highlights (ms) */
+  holdAfterClimaxMs?: number
+}
+
+export interface PlaybookStep {
+  /** Story beat label (for storyboard / validation) */
+  beat?: string
+  overlay?: string
+  /** UI guide callout id — stays visible through reveal while story overlay may hide */
+  annotate?: string
+  /** Per-step placement override */
+  placement?: VideoOverlayPlacement
+  /** Exploration UI region to keep visible (see zones.json) */
+  focus?: string
+  /** Read time in ms — overlay stays up so the viewer can read before actions */
+  cue?: number
+  hideOverlay?: boolean
+  /** Hold time in ms after actions (or after cue when overlay-only) */
+  wait?: number
+  selectExample?: string
+  step?: number | PlaybookStepAction
+  scroll?: { selector: string; y?: number }
+  expandCompanion?: 'half' | 'full'
+  click?: string
+}
+
+export interface PlaybookConfig {
+  format?: 'shorts' | 'shorts-preview'
+  exploration: string
+  defaultExample?: string
+  steps: PlaybookStep[]
+}
+
+export interface ContentFile {
+  meta: {
+    exploration: string
+    defaultExample?: string
+  }
+  overlays: Record<string, Omit<VideoOverlayDefinition, 'id'> & { type: VideoOverlayType }>
+  annotations?: Record<string, Omit<VideoAnnotationDefinition, 'id'>>
+  highlightSets?: Record<string, Omit<VideoHighlightSetDefinition, 'id'>>
+}
+
+export interface FocusAreaDef {
+  selector: string
+  description?: string
+}
+
+export interface PlacementDef {
+  anchor: 'top' | 'bottom'
+  insetPx: number
+  maxHeightPx: number
+  description?: string
+}
+
+export interface SafeZoneDef {
+  topPx: number
+  bottomPx: number
+  leftPx: number
+  rightPx: number
+  description?: string
+}
+
+export interface ZonesFile {
+  format: { width: number; height: number }
+  /** YouTube Shorts / platform chrome — matches CSS --video-safe-* in capture mode */
+  safeZone?: SafeZoneDef
+  focusAreas: Record<string, FocusAreaDef>
+  placements: Record<string, PlacementDef>
+}
+
+export interface LoadedVideoProject {
+  projectId: string
+  projectDir: string
+  content: VideoContentConfig
+  playbook: PlaybookConfig
+  /** Original playbook before voice timing merge */
+  playbookBase: PlaybookConfig
+  voiceManifest?: import('./voice/types.ts').VoiceManifest
+  zones?: ZonesFile
+  explorationPath: string
+}
diff --git a/video/src/voice/actionTiming.ts b/video/src/voice/actionTiming.ts
new file mode 100644
index 0000000..3f967d0
--- /dev/null
+++ b/video/src/voice/actionTiming.ts
@@ -0,0 +1,92 @@
+import type { PlaybookStep, PlaybookStepAction } from '../types.ts'
+
+export const SELECT_EXAMPLE_MS = 800
+export const SCROLL_MS = 700
+export const COMPANION_MS = 500
+export const HIGHLIGHT_SWITCH_MS = 350
+
+export function normalizeStepAction(step: number | PlaybookStepAction): PlaybookStepAction {
+  if (typeof step === 'number') return { count: step, interval: 400 }
+  return {
+    count: step.count ?? 1,
+    interval: step.interval ?? 400,
+    climaxFrom: step.climaxFrom,
+    climaxInterval: step.climaxInterval,
+    climaxPauseMs: step.climaxPauseMs,
+    highlightSet: step.highlightSet,
+    highlightAfterStep: step.highlightAfterStep,
+    highlightSetAfter: step.highlightSetAfter,
+    holdAfterClimaxMs: step.holdAfterClimaxMs,
+  }
+}
+
+export function stepHasActions(step: PlaybookStep): boolean {
+  return (
+    step.selectExample !== undefined ||
+    step.step !== undefined ||
+    step.scroll !== undefined ||
+    step.expandCompanion !== undefined ||
+    step.click !== undefined
+  )
+}
+
+/** Fixed action duration for a step given step interval overrides. */
+export function actionDurationMs(step: PlaybookStep, intervalOverride?: number): number {
+  let total = 0
+  if (step.selectExample) total += SELECT_EXAMPLE_MS
+  if (step.scroll) total += SCROLL_MS
+  if (step.expandCompanion) total += COMPANION_MS
+
+  if (step.step !== undefined) {
+    const action = normalizeStepAction(step.step)
+    const count = action.count ?? 1
+    const interval = intervalOverride ?? action.interval ?? 400
+    const climaxFrom = action.climaxFrom ?? 0
+    const climaxInterval = action.climaxInterval ?? Math.round(interval * 2.6)
+    const climaxPauseMs = action.climaxPauseMs ?? 0
+    const holdAfterClimaxMs = action.holdAfterClimaxMs ?? 0
+
+    for (let i = 0; i < count; i++) {
+      const stepNum = i + 1
+      const inClimax = climaxFrom > 0 && stepNum >= climaxFrom
+      if (inClimax && action.highlightSet && stepNum === climaxFrom) {
+        total += climaxPauseMs + 150
+      }
+      total += inClimax ? climaxInterval : interval
+      if (action.highlightAfterStep === stepNum) {
+        total += HIGHLIGHT_SWITCH_MS + holdAfterClimaxMs
+      }
+    }
+  }
+
+  return total
+}
+
+export function fitStepIntervals(
+  step: PlaybookStep,
+  budgetMs: number,
+): PlaybookStepAction | undefined {
+  if (step.step === undefined) return undefined
+
+  const template = normalizeStepAction(step.step)
+  const count = template.count ?? 1
+  const climaxFrom = template.climaxFrom ?? 0
+  const climaxInterval = template.climaxInterval ?? Math.round((template.interval ?? 400) * 2.6)
+  const climaxPauseMs = template.climaxPauseMs ?? 0
+  const holdAfterClimaxMs = template.holdAfterClimaxMs ?? 0
+
+  let overhead = 0
+  if (climaxFrom > 0 && template.highlightSet) {
+    overhead += climaxPauseMs + 150 + climaxInterval
+    if (template.highlightAfterStep) {
+      overhead += HIGHLIGHT_SWITCH_MS + holdAfterClimaxMs
+    }
+  }
+
+  const routineCount = climaxFrom > 0 ? Math.max(0, climaxFrom - 1) : count
+  const routineBudget = Math.max(routineCount * 280, budgetMs - overhead)
+  const interval =
+    routineCount > 0 ? Math.max(280, Math.floor(routineBudget / routineCount)) : (template.interval ?? 400)
+
+  return { ...template, interval, climaxInterval }
+}
diff --git a/video/src/voice/alignment.ts b/video/src/voice/alignment.ts
new file mode 100644
index 0000000..32ad0af
--- /dev/null
+++ b/video/src/voice/alignment.ts
@@ -0,0 +1,9 @@
+import type { CharacterAlignment } from './types.ts'
+
+/** Duration in ms from ElevenLabs character alignment. */
+export function alignmentDurationMs(alignment: CharacterAlignment | null | undefined): number {
+  const ends = alignment?.character_end_times_seconds
+  if (!ends?.length) return 0
+  const last = ends[ends.length - 1]!
+  return Math.ceil(last * 1000)
+}
diff --git a/video/src/voice/elevenlabs.ts b/video/src/voice/elevenlabs.ts
new file mode 100644
index 0000000..9f63fe1
--- /dev/null
+++ b/video/src/voice/elevenlabs.ts
@@ -0,0 +1,56 @@
+import type { SpeechWithTimestampsResponse } from './types.ts'
+
+const DEFAULT_MODEL = 'eleven_v3'
+
+export interface ElevenLabsConfig {
+  apiKey: string
+  voiceId: string
+  modelId?: string
+}
+
+export function resolveElevenLabsConfig(): ElevenLabsConfig {
+  const apiKey = process.env.ELEVENLABS_API_KEY?.trim()
+  const voiceId = process.env.ELEVENLABS_VOICE_ID?.trim()
+  if (!apiKey) {
+    throw new Error(
+      'Missing ELEVENLABS_API_KEY. Copy video/.env.example to video/.env and add your key.',
+    )
+  }
+  if (!voiceId) {
+    throw new Error('Missing ELEVENLABS_VOICE_ID in video/.env')
+  }
+  return {
+    apiKey,
+    voiceId,
+    modelId: process.env.ELEVENLABS_MODEL_ID?.trim() || DEFAULT_MODEL,
+  }
+}
+
+export async function synthesizeWithTimestamps(
+  config: ElevenLabsConfig,
+  text: string,
+  modelId?: string,
+): Promise<SpeechWithTimestampsResponse> {
+  const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(config.voiceId)}/with-timestamps`
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'xi-api-key': config.apiKey,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({ text, model_id: modelId ?? config.modelId ?? DEFAULT_MODEL }),
+  }).catch((err: unknown) => {
+    const cause = err instanceof Error && 'cause' in err ? (err.cause as Error | undefined) : undefined
+    const detail = cause?.message ?? (err instanceof Error ? err.message : String(err))
+    throw new Error(`ElevenLabs request failed (${detail})`)
+  })
+
+  const bodyText = await res.text()
+  if (!res.ok) {
+    throw new Error(`ElevenLabs HTTP ${res.status}: ${bodyText}`)
+  }
+
+  return JSON.parse(bodyText) as SpeechWithTimestampsResponse
+}
diff --git a/video/src/voice/ffmpeg.ts b/video/src/voice/ffmpeg.ts
new file mode 100644
index 0000000..12fbc4d
--- /dev/null
+++ b/video/src/voice/ffmpeg.ts
@@ -0,0 +1,164 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export function assertFfmpeg(): void {
+  try {
+    execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' })
+  } catch {
+    throw new Error('ffmpeg is required. Install ffmpeg and retry.')
+  }
+}
+
+export function writeSilenceMp3(path: string, durationSec: number): void {
+  execFileSync(
+    'ffmpeg',
+    [
+      '-y',
+      '-f',
+      'lavfi',
+      '-i',
+      'anullsrc=r=44100:cl=mono',
+      '-t',
+      String(durationSec),
+      '-q:a',
+      '9',
+      '-acodec',
+      'libmp3lame',
+      path,
+    ],
+    { stdio: 'ignore' },
+  )
+}
+
+/** Concatenate mp3 files with optional silence gaps between them. */
+export function concatMp3Files(outputPath: string, parts: string[], gapMs: number): void {
+  assertFfmpeg()
+  const dir = mkdtempSync(join(tmpdir(), 'fyp-voice-'))
+  const listPath = join(dir, 'concat.txt')
+  const lines: string[] = []
+  const gapSec = gapMs / 1000
+
+  for (let i = 0; i < parts.length; i++) {
+    lines.push(`file '${parts[i]!.replace(/'/g, "'\\''")}'`)
+    if (i < parts.length - 1 && gapMs > 0) {
+      const silencePath = join(dir, `gap-${i}.mp3`)
+      writeSilenceMp3(silencePath, gapSec)
+      lines.push(`file '${silencePath.replace(/'/g, "'\\''")}'`)
+    }
+  }
+
+  writeFileSync(listPath, lines.join('\n'))
+  execFileSync(
+    'ffmpeg',
+    ['-y', '-f', 'concat', '-safe', '0', '-i', listPath, '-c', 'copy', outputPath],
+    { stdio: 'ignore' },
+  )
+}
+
+export interface MuxVideoAudioOptions {
+  /** When set and different from source, video is upscaled/downscaled with lanczos. */
+  videoWidth?: number
+  videoHeight?: number
+}
+
+export function probeVideoSize(mediaPath: string): { width: number; height: number } | undefined {
+  try {
+    const raw = execFileSync(
+      'ffprobe',
+      [
+        '-v',
+        'error',
+        '-select_streams',
+        'v:0',
+        '-show_entries',
+        'stream=width,height',
+        '-of',
+        'csv=p=0:s=x',
+        mediaPath,
+      ],
+      { encoding: 'utf8' },
+    ).trim()
+    const [w, h] = raw.split('x').map((n) => Number.parseInt(n, 10))
+    if (!Number.isFinite(w) || !Number.isFinite(h)) return undefined
+    return { width: w!, height: h! }
+  } catch {
+    return undefined
+  }
+}
+
+export function muxVideoAudio(
+  videoPath: string,
+  audioPath: string,
+  outputPath: string,
+  options: MuxVideoAudioOptions = {},
+): void {
+  assertFfmpeg()
+
+  const videoSec = probeDurationMs(videoPath) / 1000
+  const audioSec = probeDurationMs(audioPath) / 1000
+  const padSec = Math.max(0, videoSec - audioSec)
+
+  const source = probeVideoSize(videoPath)
+  const targetW = options.videoWidth ?? source?.width
+  const targetH = options.videoHeight ?? source?.height
+  const needsScale =
+    source !== undefined &&
+    targetW !== undefined &&
+    targetH !== undefined &&
+    (source.width !== targetW || source.height !== targetH)
+
+  const filterParts: string[] = []
+  if (needsScale) {
+    filterParts.push(`[0:v]scale=${targetW}:${targetH}:flags=lanczos[vout]`)
+  }
+  filterParts.push(
+    padSec > 0.02 ? `[1:a]apad=pad_dur=${padSec.toFixed(3)}[aout]` : '[1:a]anull[aout]',
+  )
+
+  const args = [
+    '-y',
+    '-i',
+    videoPath,
+    '-i',
+    audioPath,
+    '-filter_complex',
+    filterParts.join(';'),
+    '-map',
+    needsScale ? '[vout]' : '0:v:0',
+    '-map',
+    '[aout]',
+    '-c:v',
+    needsScale ? 'libx264' : 'copy',
+    ...(needsScale ? ['-preset', 'fast', '-crf', '18', '-pix_fmt', 'yuv420p'] : []),
+    '-c:a',
+    'aac',
+    '-b:a',
+    '192k',
+    '-t',
+    String(videoSec),
+    outputPath,
+  ]
+
+  execFileSync('ffmpeg', args, { stdio: 'ignore' })
+}
+
+export function probeDurationMs(mediaPath: string): number {
+  const raw = execFileSync(
+    'ffprobe',
+    [
+      '-v',
+      'error',
+      '-show_entries',
+      'format=duration',
+      '-of',
+      'default=noprint_wrappers=1:nokey=1',
+      mediaPath,
+    ],
+    { encoding: 'utf8' },
+  ).trim()
+  const sec = Number.parseFloat(raw)
+  if (!Number.isFinite(sec)) return 0
+  return Math.round(sec * 1000)
+}
diff --git a/video/src/voice/mergeTiming.ts b/video/src/voice/mergeTiming.ts
new file mode 100644
index 0000000..0f56d8e
--- /dev/null
+++ b/video/src/voice/mergeTiming.ts
@@ -0,0 +1,144 @@
+import type { PlaybookConfig, PlaybookStep } from '../types.ts'
+import {
+  actionDurationMs,
+  fitStepIntervals,
+  stepHasActions,
+} from './actionTiming.ts'
+import type { VoiceManifest } from './types.ts'
+
+const POST_CARD_TAIL_MS = 300
+const MIN_WAIT_MS = 400
+const TIMELINE_BUFFER_MS = 120
+/** Outro CTA band — hold at least this long so Forkcast / FYP cards are readable. */
+export const OUTRO_MIN_HOLD_MS = 5000
+
+export interface MergeVoiceTimingOptions {
+  minWaitMs?: number
+  postCardTailMs?: number
+}
+
+function clonePlaybook(playbook: PlaybookConfig): PlaybookConfig {
+  return JSON.parse(JSON.stringify(playbook)) as PlaybookConfig
+}
+
+function beatKey(step: PlaybookStep, index: number): string {
+  return step.beat ?? `step-${index + 1}`
+}
+
+function nextVoiceBeat(
+  steps: PlaybookStep[],
+  fromIndex: number,
+  manifest: VoiceManifest,
+): { index: number; startMs: number } | undefined {
+  for (let i = fromIndex + 1; i < steps.length; i++) {
+    const key = beatKey(steps[i]!, i)
+    const timing = manifest.beats[key]
+    if (timing) return { index: i, startMs: timing.startMs }
+  }
+  return undefined
+}
+
+function isCardOnlyStep(step: PlaybookStep): boolean {
+  const hasActions = stepHasActions(step)
+  return Boolean(step.overlay) && !hasActions && step.cue === undefined
+}
+
+/**
+ * Apply voice manifest timestamps to playbook cue/wait/interval fields.
+ * Returns a new playbook; original is unchanged.
+ */
+export function mergeVoiceTiming(
+  playbook: PlaybookConfig,
+  manifest: VoiceManifest,
+  options: MergeVoiceTimingOptions = {},
+): PlaybookConfig {
+  const merged = clonePlaybook(playbook)
+  const postTail = options.postCardTailMs ?? POST_CARD_TAIL_MS
+  const minWait = options.minWaitMs ?? MIN_WAIT_MS
+
+  for (let i = 0; i < merged.steps.length; i++) {
+    const step = merged.steps[i]!
+    const key = beatKey(step, i)
+    const voice = manifest.beats[key]
+    if (!voice) continue
+
+    const hasActions = stepHasActions(step)
+    const next = nextVoiceBeat(merged.steps, i, manifest)
+
+    if (isCardOnlyStep(step)) {
+      if (key === 'outro') {
+        step.wait = Math.max(voice.durationMs + postTail, OUTRO_MIN_HOLD_MS)
+      } else {
+        step.wait = voice.durationMs + postTail
+      }
+      continue
+    }
+
+    if (step.overlay && step.cue !== undefined && hasActions) {
+      step.cue = voice.durationMs
+
+      const postVoiceBudget =
+        (next?.startMs ?? voice.endMs + 2000) - voice.endMs - TIMELINE_BUFFER_MS
+
+      const fixedWithoutSteps = actionDurationMs({ ...step, step: undefined })
+      const stepBudget = Math.max(0, postVoiceBudget - fixedWithoutSteps - minWait)
+
+      if (step.step !== undefined) {
+        const fitted = fitStepIntervals(step, stepBudget)
+        if (fitted) step.step = fitted
+      }
+
+      const actionMs = actionDurationMs(step)
+      step.wait = Math.max(minWait, postVoiceBudget - actionMs)
+      continue
+    }
+
+    if (step.overlay && step.cue !== undefined && !hasActions) {
+      step.cue = voice.durationMs
+      const postVoiceBudget =
+        (next?.startMs ?? voice.endMs + 2000) - voice.endMs - TIMELINE_BUFFER_MS
+      step.wait = Math.max(minWait, postVoiceBudget)
+      continue
+    }
+
+    if (step.overlay && !step.cue && !hasActions && step.wait !== undefined) {
+      step.wait = voice.durationMs
+    }
+  }
+
+  return merged
+}
+
+export function voiceTimingSummary(
+  playbook: PlaybookConfig,
+  manifest: VoiceManifest,
+): Array<{ beat: string; voiceMs: number; stepTotalMs: number }> {
+  const merged = mergeVoiceTiming(playbook, manifest)
+  const rows: Array<{ beat: string; voiceMs: number; stepTotalMs: number }> = []
+
+  for (let i = 0; i < merged.steps.length; i++) {
+    const step = merged.steps[i]!
+    const key = beatKey(step, i)
+    const voice = manifest.beats[key]
+    if (!voice) continue
+
+    const hasActions = stepHasActions(step)
+    let stepTotal = 0
+    if (isCardOnlyStep(step)) {
+      stepTotal = step.wait ?? 0
+    } else if (step.cue !== undefined) {
+      stepTotal = step.cue
+      if (hasActions) {
+        stepTotal += actionDurationMs(step) + (step.wait ?? 0)
+      } else {
+        stepTotal += step.wait ?? 0
+      }
+    } else {
+      stepTotal = step.wait ?? 0
+    }
+
+    rows.push({ beat: key, voiceMs: voice.durationMs, stepTotalMs: stepTotal })
+  }
+
+  return rows
+}
diff --git a/video/src/voice/mux-cli.ts b/video/src/voice/mux-cli.ts
new file mode 100644
index 0000000..36653a5
--- /dev/null
+++ b/video/src/voice/mux-cli.ts
@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { VIDEO_FORMATS } from '../formats.ts'
+import { finalMp4Path, formatOutputBanner } from '../outputPaths.ts'
+import { parseMuxArgs } from '../parseProjectArgs.ts'
+import { muxVideoAudio } from '../voice/ffmpeg.ts'
+import { voiceDir } from '../voice/synthesize.ts'
+
+const PROJECTS_ROOT = join(import.meta.dirname, '../../projects')
+
+function newestWebm(dir: string): string | undefined {
+  if (!existsSync(dir)) return undefined
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.webm'))
+    .map((f) => join(dir, f))
+  if (!files.length) return undefined
+  files.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+  return files[0]
+}
+
+function main(): void {
+  let args: ReturnType<typeof parseMuxArgs>
+  try {
+    args = parseMuxArgs(process.argv.slice(2))
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  }
+
+  const projectDir = join(PROJECTS_ROOT, args.projectId)
+  const outputDir = join(projectDir, 'output')
+  const videoPath = args.input ?? newestWebm(outputDir)
+  const audioPath = join(voiceDir(projectDir), 'full.mp3')
+
+  if (!videoPath || !existsSync(videoPath)) {
+    console.error('No video file found. Record first or pass --input path/to/video.webm')
+    process.exit(1)
+  }
+  if (!existsSync(audioPath)) {
+    console.error(`Missing ${audioPath}. Run: npm run video:voice:synth -- ${args.projectId}`)
+    process.exit(1)
+  }
+
+  const outPath = args.output ?? finalMp4Path(videoPath)
+  const deliverable = VIDEO_FORMATS[args.preview ? 'shorts-preview' : 'shorts']
+
+  console.log(`Video: ${videoPath}`)
+  console.log(`Audio: ${audioPath}`)
+  console.log(`Output: ${deliverable.width}×${deliverable.height}`)
+  console.log('Muxing…')
+  muxVideoAudio(videoPath, audioPath, outPath, {
+    videoWidth: deliverable.width,
+    videoHeight: deliverable.height,
+  })
+  console.log(formatOutputBanner(outPath, videoPath))
+}
+
+main()
diff --git a/video/src/voice/plan-cli.ts b/video/src/voice/plan-cli.ts
new file mode 100644
index 0000000..8e1f893
--- /dev/null
+++ b/video/src/voice/plan-cli.ts
@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { estimatePlaybookDurationMs, loadVideoProject, resolvePlaybook } from '../loadProject.ts'
+import { parseProjectArgs } from '../parseProjectArgs.ts'
+import { buildStoryboard, printStoryboard, validateStoryboard } from '../storyboard.ts'
+import { voiceTimingSummary } from '../voice/mergeTiming.ts'
+import { loadVoiceManifest } from '../voice/synthesize.ts'
+
+const PROJECTS_ROOT = join(import.meta.dirname, '../../projects')
+
+function main(): void {
+  let projectId: string
+  try {
+    projectId = parseProjectArgs(process.argv.slice(2)).projectId
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    console.error('Usage: npm run voice:plan -- <project-id>')
+    process.exit(1)
+  }
+
+  const projectDir = join(PROJECTS_ROOT, projectId)
+  if (!existsSync(projectDir)) {
+    console.error(`Unknown project: ${projectId}`)
+    process.exit(1)
+  }
+
+  const manifest = loadVoiceManifest(projectDir)
+  if (!manifest) {
+    console.error(`No voice/manifest.json — run: npm run video:voice:synth -- ${projectId}`)
+    process.exit(1)
+  }
+
+  const project = loadVideoProject(projectId, PROJECTS_ROOT)
+  const playbook = resolvePlaybook(project)
+  const timeline = buildStoryboard(playbook, project.content)
+
+  console.log(`Project: ${projectId}`)
+  console.log(`Voice track: ~${Math.round(manifest.totalDurationMs / 1000)}s`)
+  console.log(`Video est.:  ~${Math.round(estimatePlaybookDurationMs(playbook) / 1000)}s (voice-synced)`)
+  console.log('')
+  console.log('Voice ↔ beat alignment')
+  console.log('─'.repeat(56))
+  let voiceCursor = 0
+  for (const row of voiceTimingSummary(project.playbook, manifest)) {
+    const at = formatTime(voiceCursor)
+    console.log(
+      `${at}  ${row.beat.padEnd(14)} voice ${(row.voiceMs / 1000).toFixed(1)}s  step ${(row.stepTotalMs / 1000).toFixed(1)}s`,
+    )
+    voiceCursor += row.stepTotalMs
+  }
+  console.log('─'.repeat(56))
+  console.log('')
+  printStoryboard(timeline)
+
+  const issues = validateStoryboard(playbook, project.content, project.zones)
+  if (issues.length) {
+    console.log('\nValidation:')
+    for (const issue of issues) {
+      console.log(`  [${issue.severity.toUpperCase()}] step ${issue.step}: ${issue.message}`)
+    }
+  }
+}
+
+function formatTime(ms: number): string {
+  const s = ms / 1000
+  const m = Math.floor(s / 60)
+  const r = s - m * 60
+  return `${String(m).padStart(2, '0')}:${r.toFixed(1).padStart(4, '0')}`
+}
+
+main()
diff --git a/video/src/voice/synth-cli.ts b/video/src/voice/synth-cli.ts
new file mode 100644
index 0000000..72e3031
--- /dev/null
+++ b/video/src/voice/synth-cli.ts
@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { loadVideoEnv } from '../loadEnv.ts'
+import { parseProjectArgs } from '../parseProjectArgs.ts'
+import { synthesizeProjectVoice } from '../voice/synthesize.ts'
+
+const PROJECTS_ROOT = join(import.meta.dirname, '../../projects')
+
+async function main(): Promise<void> {
+  loadVideoEnv()
+
+  let projectId: string
+  try {
+    projectId = parseProjectArgs(process.argv.slice(2)).projectId
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    console.error('Usage: npm run voice:synth -- <project-id> [--force]')
+    process.exit(1)
+  }
+
+  const force = process.argv.includes('--force')
+  const projectDir = join(PROJECTS_ROOT, projectId)
+  if (!existsSync(projectDir)) {
+    console.error(`Unknown project: ${projectId}`)
+    process.exit(1)
+  }
+
+  console.log(`Synthesizing voice for ${projectId}…`)
+  const manifest = await synthesizeProjectVoice(projectDir, { force })
+
+  console.log(`\nWrote ${join(projectDir, 'voice/full.mp3')}`)
+  console.log(`Wrote ${join(projectDir, 'voice/manifest.json')}`)
+  console.log(`Total voice: ~${Math.round(manifest.totalDurationMs / 100) / 10}s`)
+  for (const [beat, timing] of Object.entries(manifest.beats)) {
+    console.log(`  ${beat}: ${(timing.durationMs / 1000).toFixed(1)}s`)
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})
diff --git a/video/src/voice/synthesize.ts b/video/src/voice/synthesize.ts
new file mode 100644
index 0000000..4bc1d3a
--- /dev/null
+++ b/video/src/voice/synthesize.ts
@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { alignmentDurationMs } from './alignment.ts'
+import { resolveElevenLabsConfig, synthesizeWithTimestamps } from './elevenlabs.ts'
+import { concatMp3Files, probeDurationMs } from './ffmpeg.ts'
+import type {
+  NarrationFile,
+  SynthesizedSegment,
+  VoiceManifest,
+} from './types.ts'
+
+export function loadNarrationFile(projectDir: string): NarrationFile {
+  const path = join(projectDir, 'narration.json')
+  if (!existsSync(path)) {
+    throw new Error(`Missing narration.json in ${projectDir}`)
+  }
+  return JSON.parse(readFileSync(path, 'utf8')) as NarrationFile
+}
+
+export function voiceDir(projectDir: string): string {
+  return join(projectDir, 'voice')
+}
+
+export function manifestPath(projectDir: string): string {
+  return join(voiceDir(projectDir), 'manifest.json')
+}
+
+export function loadVoiceManifest(projectDir: string): VoiceManifest | undefined {
+  const path = manifestPath(projectDir)
+  if (!existsSync(path)) return undefined
+  return JSON.parse(readFileSync(path, 'utf8')) as VoiceManifest
+}
+
+function segmentPaths(projectDir: string, beat: string): { mp3: string; alignment: string } {
+  const dir = join(voiceDir(projectDir), 'segments')
+  return {
+    mp3: join(dir, `${beat}.mp3`),
+    alignment: join(dir, `${beat}.alignment.json`),
+  }
+}
+
+export async function synthesizeProjectVoice(
+  projectDir: string,
+  options: { force?: boolean } = {},
+): Promise<VoiceManifest> {
+  const narration = loadNarrationFile(projectDir)
+  const config = resolveElevenLabsConfig()
+  const model = narration.model ?? config.modelId ?? 'eleven_v3'
+  const gapMs = narration.segmentGapMs ?? 350
+
+  const vDir = voiceDir(projectDir)
+  const segDir = join(vDir, 'segments')
+  mkdirSync(segDir, { recursive: true })
+
+  const synthesized: SynthesizedSegment[] = []
+
+  for (const segment of narration.segments) {
+    const paths = segmentPaths(projectDir, segment.beat)
+    if (!options.force && existsSync(paths.mp3) && existsSync(paths.alignment)) {
+      const alignment = JSON.parse(readFileSync(paths.alignment, 'utf8'))
+      synthesized.push({
+        beat: segment.beat,
+        text: segment.text,
+        audioPath: paths.mp3,
+        alignmentPath: paths.alignment,
+        durationMs: alignmentDurationMs(alignment),
+      })
+      console.log(`  skip ${segment.beat} (cached)`)
+      continue
+    }
+
+    console.log(`  synth ${segment.beat}…`)
+    const result = await synthesizeWithTimestamps(config, segment.text, model)
+    writeFileSync(paths.mp3, Buffer.from(result.audio_base64, 'base64'))
+    writeFileSync(paths.alignment, JSON.stringify(result.alignment ?? null, null, 2))
+
+    synthesized.push({
+      beat: segment.beat,
+      text: segment.text,
+      audioPath: paths.mp3,
+      alignmentPath: paths.alignment,
+      durationMs: alignmentDurationMs(result.alignment),
+    })
+  }
+
+  const fullPath = join(vDir, 'full.mp3')
+  concatMp3Files(
+    fullPath,
+    synthesized.map((s) => s.audioPath),
+    gapMs,
+  )
+
+  const beats: VoiceManifest['beats'] = {}
+  let cursor = 0
+  for (let i = 0; i < synthesized.length; i++) {
+    const seg = synthesized[i]!
+    const startMs = cursor
+    const endMs = cursor + seg.durationMs
+    beats[seg.beat] = {
+      startMs,
+      endMs,
+      durationMs: seg.durationMs,
+      segmentFile: seg.audioPath,
+    }
+    cursor = endMs
+    if (i < synthesized.length - 1) cursor += gapMs
+  }
+
+  const manifest: VoiceManifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    model,
+    voiceId: config.voiceId,
+    audioFile: 'voice/full.mp3',
+    segmentGapMs: gapMs,
+    totalDurationMs: probeDurationMs(fullPath) || cursor,
+    beats,
+  }
+
+  writeFileSync(manifestPath(projectDir), JSON.stringify(manifest, null, 2))
+  return manifest
+}
diff --git a/video/src/voice/types.ts b/video/src/voice/types.ts
new file mode 100644
index 0000000..13ce870
--- /dev/null
+++ b/video/src/voice/types.ts
@@ -0,0 +1,47 @@
+export interface NarrationSegment {
+  beat: string
+  text: string
+}
+
+export interface NarrationFile {
+  model?: string
+  segmentGapMs?: number
+  segments: NarrationSegment[]
+}
+
+export interface CharacterAlignment {
+  characters: string[]
+  character_start_times_seconds: number[]
+  character_end_times_seconds: number[]
+}
+
+export interface SpeechWithTimestampsResponse {
+  audio_base64: string
+  alignment?: CharacterAlignment | null
+}
+
+export interface VoiceBeatTiming {
+  startMs: number
+  endMs: number
+  durationMs: number
+  segmentFile: string
+}
+
+export interface VoiceManifest {
+  version: 1
+  generatedAt: string
+  model: string
+  voiceId: string
+  audioFile: string
+  segmentGapMs: number
+  totalDurationMs: number
+  beats: Record<string, VoiceBeatTiming>
+}
+
+export interface SynthesizedSegment {
+  beat: string
+  text: string
+  audioPath: string
+  alignmentPath: string
+  durationMs: number
+}
diff --git a/vitest.config.ts b/vitest.config.ts
index dbab159..96c0072 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -14,6 +14,7 @@ export default mergeConfig(
     },
     test: {
       environment: 'jsdom',
+      setupFiles: ['./vitest.setup.ts'],
       exclude: [...configDefaults.exclude, 'e2e/**'],
       /** Entire repo — src, community-token, roadmap, og tooling; CI runs all via `npm run test:unit:ci`. */
       include: [
@@ -21,6 +22,7 @@ export default mergeConfig(
         'community-token/**/*.spec.ts',
         'roadmap/**/*.spec.ts',
         'og/**/*.spec.ts',
+        'video/**/*.spec.ts',
       ],
       root: fileURLToPath(new URL('./', import.meta.url)),
     },
diff --git a/vitest.setup.ts b/vitest.setup.ts
new file mode 100644
index 0000000..e2d3c11
--- /dev/null
+++ b/vitest.setup.ts
@@ -0,0 +1,4 @@
+/** jsdom does not implement scrollIntoView — stub for component tests that step bytecode. */
+if (typeof Element !== 'undefined' && typeof Element.prototype.scrollIntoView !== 'function') {
+  Element.prototype.scrollIntoView = () => {}
+}