storyshot 0.3.1 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ docs.
 
 > *"make a 15 s promo video of https://myapp.com"*
 
-Storyshot gives Cursor, Claude Code and other coding agents what they need to
+Storyshot gives coding agents (Cursor, Claude Code, Codex, Gemini CLI, Copilot in VS Code, Windsurf, Cline) what they need to
 do this well. A real browser clicks through your site, and the recording gets
 a smooth cursor, automatic zoom, captions, an optional AI voiceover, music
 and an end card. Loading time is squeezed out, so a 30-second AI job takes a
@@ -15,6 +15,13 @@ second or two on screen.
 The agent plans, writes and fixes the storyboard. Storyshot does the
 recording and editing, and the same storyboard always renders the same video.
 
+## Gallery
+
+**[boheling.github.io/storyshot-gallery](https://boheling.github.io/storyshot-gallery/)**: promos,
+tutorials, lessons and help-center docs of real web apps (Squoosh, Excalidraw, NCBI BLAST, Desmos,
+regex101, RCSB PDB, Datasette and more, two of them in Chinese). Each one was made by an agent from a
+one-paragraph request, and comes with its storyboard and notes on how it went.
+
 ## Next to similar tools
 
 Storyshot, [promo-video-recorder](https://github.com/palamut62/promo-video-recorder)
@@ -46,11 +53,28 @@ How each one was made, what we saw, and the caveats:
 
 ## Quick start
 
-Open your project in Cursor or Claude Code and paste this into the agent chat:
+Open your project in your coding agent and paste this into its chat, with your
+agent's name (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf` or `cline`):
+
+> Set up Storyshot in this project: run `npx -y storyshot setup cursor` and do
+> everything it says. Then make a short promo video of https://myapp.com
+
+| agent | what `setup` writes |
+|---|---|
+| Cursor | `.cursor/mcp.json` and the skill in `.cursor/skills/storyshot/` |
+| Claude Code | `.mcp.json` and the skill in `.claude/skills/storyshot/` |
+| Codex | the skill in `.agents/skills/storyshot/`, a short section in `AGENTS.md` pointing to it, and the MCP server through `codex mcp add` (in `~/.codex/config.toml`, for your user). Storyshot launches a browser, which Codex's sandbox blocks: approve it when Codex asks, or run Codex with `--sandbox danger-full-access` |
+| Gemini CLI | `.gemini/settings.json`, a section in `GEMINI.md`, the skill in `.agents/skills/storyshot/` (trust the folder when Gemini asks, or it ignores project settings) |
+| Copilot in VS Code (`vscode`) | `.vscode/mcp.json`, a section in `.github/copilot-instructions.md`, the skill in `.agents/skills/storyshot/` |
+| Windsurf | `.windsurf/rules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in `~/.codeium/windsurf/mcp_config.json` (for your user) |
+| Cline | `.clinerules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in Cline's own settings in each editor it is installed in (for your user) |
+
+Existing files are merged, not replaced: other MCP servers stay, and instruction files get one marked
+Storyshot section that a second `setup` updates instead of duplicating.
 
-> Set up Storyshot in this project: run `npx -y storyshot setup cursor` (use
-> `setup claude` in Claude Code) and do everything it says. Then make a 15 s
-> promo video of https://myapp.com
+**Tested end to end** (setup, then an agent making a real video from a plain request): **Claude Code,
+Cursor and Codex**. Gemini CLI, Copilot in VS Code, Windsurf and Cline get the configuration their docs
+describe, but haven't been tested with a real session yet; reports are welcome.
 
 The agent does the rest:
 - `setup` writes the MCP server config and the Storyshot skill, adds
@@ -61,7 +85,7 @@ The agent does the rest:
 - The agent reads the skill and starts on your video in the same chat, using
   the CLI.
 
-Reload Cursor (or restart Claude Code) when convenient. From the next chat on,
+Restart or reload your agent when convenient (`setup` says how for each one). From the next chat on,
 the agent uses the Storyshot MCP tools automatically, and you can just ask:
 
 - *"make a 15 s promo video of https://myapp.com"*, or type `/storyshot`
@@ -169,7 +193,7 @@ from `storyshot guide`.
 | `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file. |
 | `render_video` / `render_status` | Renders in the background and returns the MP4 path, warnings, a per-step speed log and the preview image. If the render isn't done within 45 s, it returns a `job_id`, so client tool timeouts never kill a render. |
 
-Other MCP clients: run `npx -y storyshot mcp` (stdio). When run from a git
+Any other MCP client: run `npx -y storyshot mcp` (stdio), and point the agent at the playbook (`storyshot guide`). When run from a git
 checkout, `setup` points to `node /path/to/checkout/bin/storyshot.mjs mcp` instead.
 
 When a step fails, the error names the step and action, and says whether the
@@ -192,7 +216,7 @@ Everything the agent does is also a command:
 | `storyshot compose videos/acme-promo.yaml [--draft]` | Rebuild from the last recording, in seconds. |
 | `storyshot record videos/acme-promo.yaml` | Only record. |
 | `storyshot guide` | Print the playbook and the reference. |
-| `storyshot setup cursor\|claude` | Set up the MCP server and the skill in this project, and install or check what Storyshot needs. |
+| `storyshot setup <agent>` (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf`, `cline`) | Set up the MCP server and the skill in this project, and install or check what Storyshot needs. |
 | `storyshot doctor` | Check Node, ffmpeg, Chromium and voices; install Chromium if it's missing. |
 | `storyshot mcp` | Run the MCP server. |
 
@@ -234,7 +258,9 @@ stepNumbers: false                              # numbered caption badges
 subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top)
 pace: slow                                      # fast (pitch) | normal (docs) | slow (tutorial, course): cursor and typing speed, a beat after each click, hold after narration, voice speed, how much of a wait is shown
 follow: true                                    # tutorial/course default: the camera zooms in on what each step touches and pans between steps (a step's own zoom wins; follow: false on a step skips it); or { scale: 1.8 }
-frame: true                                     # pitch default: the recording sits in a browser window on a backdrop; false = full frame, or { background: <css> }
+article: { title: Export a drawing, intro: … }  # docs: heading and first paragraph of <out>-steps/README.md
+cards: auto                                     # intro/section/end cards: auto follows the frame (dark frames get dark cards), or light | dark
+frame: aurora                                   # the recording sits in a browser window on a backdrop: aurora (dark, grain; pitch default), studio (light, grain; tutorial and course default), dark, pastel, blur (the page itself, blurred); false = full frame; or { style, background: <css> }
 chapters: false                                 # write <out>.chapters.txt for YouTube
 clips: null                                     # gif | webm | mp4 | png, or a list (docs default: [gif, png]): one file per step in <out>-steps/, cropped to what the step touches, plus README.md, a ready-to-paste article (step captions, `doc:` text, images)
 maxWait: 1.0                                    # with duration: auto, the longest a wait is shown
@@ -293,8 +319,9 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | action | example |
 |---|---|
 | `click` | `click: { role: button, name: Convert, ms: 800, offset: { x: 0.3, y: 0.5 } }` |
+| `dblclick` | `dblclick: { text: Start }` double-clicks (e.g. to edit a label in place) |
 | `move` / `hover` | `move: { text: "$0" }` or `move: { x: 0.5, y: 0.4, ms: 1200 }` |
-| `type` | `type: { target: { label: Email }, text: hi@acme.com, delay: 60 }`, or `type: hello` to type into whatever has focus |
+| `type` | `type: { target: { label: Email }, text: hi@acme.com, delay: 60 }`, or `type: hello` to type into whatever has focus. `clear: true` empties a pre-filled field first |
 | `drag` | `drag: { from: { css: ".slider" }, by: [{ x: -300 }, { x: 450 }] }` (several moves while held), or `to: <target or point>` |
 | `press` | `press: Enter`, `press: "^"`, `press: { key: Meta+K, show: true }`. When highlighting, shortcuts and special keys show an on-screen badge; plain characters don't. `show: false` hides it. |
 | `pause` | `pause: 700` (ms) |
@@ -305,9 +332,12 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` |
 | `scroll` | `scroll: 600` |
 | `dismiss` | `dismiss: { role: button, name: Close }` (clicks only if visible) |
+| `hide` | `hide: '[id*="QSI"], .chat-widget'` hides pop-ups, survey prompts, feedback tabs and chat widgets for the whole video, including ones that appear late (use it in `setup`) |
 | `mark` | `mark: "automatic zoom, captions"` sweeps a highlighter over that phrase, even inside a paragraph (scrolling to it if needed). `mark: { css: "table tr:nth-child(3)" }` marks any target with a box. Options: `ms` (sweep time, default 700), `color` (default: theme accent), `box: true/false`. Marks stay until the step ends. |
 | `unmark` | `unmark: true` clears the marks (and notes) earlier |
 | `note` | `note: { target: { label: Database }, text: Curated proteins only }` puts a short label with an arrow next to the element, on the side with the most room (or `side: left/right/top/bottom`). It stays until the step ends and gets reading time (about 3 words a second, or `ms`). |
+| `paste` | `paste: { target: { label: JSON }, text: '{"a": 1}' }` pastes text in one go through the real clipboard (with a ⌘V badge), so editors react as to a real paste; `paste: "..."` pastes into whatever has focus |
+| `slide` | `slide: { target: { label: Quality }, to: 0.2 }` drags a slider to a position along its track (0 = start, 1 = end), found from the element, not pixels |
 | `select` | `select: { target: { label: Database }, option: "UniProtKB/Swiss-Prot" }` picks an option in a dropdown (by its visible text, or part of it). `inspect` lists each dropdown's options. |
 
 `ms` sets how long the cursor takes to travel to the target (`dragMs` for each

package/bin/storyshot.mjs

@@ -24,7 +24,8 @@ Usage:
                                     (after changing captions, durations, zoom, music, voice, end card)
   storyshot record  <storyboard.yaml>     only (re-)record the browser session
   storyshot guide                   print the agent playbook + storyboard reference
-  storyshot setup cursor|claude     add the MCP server + playbook to this project for Cursor / Claude Code,
+  storyshot setup <agent>          add the MCP server + playbook to this project for your coding agent:
+                                    cursor, claude, codex, gemini, vscode (Copilot), windsurf, cline —
                                     and install / check everything Storyshot needs
   storyshot doctor                  check (and install what it can of) Chromium, ffmpeg, voices
   storyshot mcp                     run as an MCP server (stdio)
@@ -77,7 +78,14 @@ try {
       `  show up in this session, use the CLI instead: ${cliCommand()} <command>`,
       arg === 'cursor'
         ? '  User: reload Cursor (Cmd/Ctrl+Shift+P → "Reload Window") so the storyshot MCP tools load; future chats use them automatically.'
-        : '  User: restart Claude Code in this project and approve the storyshot MCP server; future sessions use it automatically.',
+        : ({
+          claude: '  User: restart Claude Code in this project and approve the storyshot MCP server; future sessions use it automatically.',
+          codex: '  User: start a new Codex session in this project; it reads AGENTS.md and loads the storyshot MCP server. Storyshot needs to launch a browser, which Codex\'s sandbox blocks: approve it when Codex asks, or start Codex with --sandbox danger-full-access.',
+          gemini: '  User: restart Gemini CLI in this project and trust the folder when asked (Gemini ignores project settings in untrusted folders); /mcp then lists the storyshot tools.',
+          vscode: '  User: in VS Code, open .vscode/mcp.json and click Start on "storyshot", then use Copilot Chat in Agent mode.',
+          windsurf: '  User: in Windsurf, open Cascade → MCP servers and refresh; the storyshot tools then appear.',
+          cline: '  User: in Cline, open MCP Servers and make sure "storyshot" is enabled (restart the editor if it is not listed).',
+        })[arg],
     ].join('\n'));
   } else if (cmd === 'login') {
     const { login, authFileFor } = await import('../src/auth.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Turn a short YAML storyboard into a polished product demo video of your web app — smooth cursor, auto zoom, captions, music.",
   "author": "boheling <boheling@gmail.com>",
   "repository": {

package/skills/storyshot/SKILL.md

@@ -38,6 +38,12 @@ is missing, a tool says so and gives the install command. Run that command
 yourself (with the user's approval), then retry. `storyshot doctor` checks
 everything.
 
+**Never fake the video.** Storyshot records the real site in a real browser. If
+the browser can't start (an agent sandbox that blocks it, a missing Chromium),
+or the tools keep failing, stop and tell the user what blocked it and how to
+allow it. Never produce a substitute: no mock-ups, redrawn screens, scripted
+frames or stock footage presented as a recording of their app.
+
 ## 1. Look, then confirm the brief
 
 1. **Look first.** `inspect_page` the start URL (about 5 s). Note what the site
@@ -166,7 +172,9 @@ small controls are readable. Your job is the structure:
   cropped to what it touches and holds the result before looping; a PNG of
   each result and `<out>-steps/README.md` are written too. Give every step a
   short `caption` (the heading) and a `doc:` line (the article text), and
-  `note` the field the reader must not miss.
+  `note` the field the reader must not miss. Set the article's heading and
+  first paragraph with `article: { title: …, intro: … }`. Downloads show a
+  "Downloaded" bubble; `paste` and copy-to-clipboard work.
 - **End with a recap**: `end_card` with `bullets` listing the steps or rules
   to remember, and a `say` that repeats them.
 - **Narrating real results.** You can't know the numbers (scores, counts,
@@ -219,8 +227,9 @@ Rules of thumb from real renders (promos and tutorials):
   `mark` the claims as they are spoken, zoom on 2–3 of them, and end on a
   command or URL. If the product has a real flow, show that instead.
 - **Cut boring navigation** with a `hidden: true` step (e.g. `goto: /pricing`).
-- **Clean the frame** in `setup`: dismiss cookie banners, announcement bars and
-  chat widgets. `dismiss` is a no-op when the element isn't there.
+- **Clean the frame** in `setup`: dismiss cookie banners and announcement bars
+  (`dismiss` is a no-op when the element isn't there), and `hide` survey
+  pop-ups, feedback tabs and chat widgets, which often appear late.
 - **Keep the caption off the subject.** Captions sit bottom-centre. When one
   would cover a target the step clicks, hovers, types into or drags, or the
   zoom subject, it moves to the top automatically (with a warning). Other things

package/src/audio.mjs

@@ -92,8 +92,14 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
 
   // --- sound effects ------------------------------------------------------------------------
   if (cfg.sfx) {
+    // a mouse click: the press (band-passed noise with a small body thump), then a quieter release
     for (const c of events.clicks) {
-      add(sfx, c, 0.05, (t) => (Math.sin(2 * Math.PI * 2900 * t) * 0.6 + rand() * 0.4) * Math.exp(-t * 140), 0.45);
+      const fa = svf(), fb = svf();
+      add(sfx, c, 0.1, (t) => {
+        const press = t < 0.02 ? (fa(rand(), 3200, 2.5).bp * 1.4 + Math.sin(2 * Math.PI * 190 * t) * 0.5) * Math.exp(-t * 320) : 0;
+        const r = t - 0.075, release = r > 0 && r < 0.015 ? fb(rand(), 4200, 3).bp * 0.8 * Math.exp(-r * 420) : 0;
+        return press + release;
+      }, 0.55);
     }
     for (const c of events.whooshes) {
       const filt = svf(), len = 0.45;

package/src/build.mjs

@@ -10,9 +10,9 @@ export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   if (mode !== 'compose') await record(cfg, { log });
   if (mode === 'record') return { warnings: [] };
   const voiceLens = await measureVoice(cfg, { log });
-  const { silent, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
+  const { silent, clean, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
   const audio = await soundtrack(cfg, events, silent, { log });
   if (cfg.subtitles === 'burn') burnSubtitles(cfg, audio.narration ?? [], { log });
-  const extras = await writeOutputs(cfg, { captions, cards, segs, narration: audio.narration, total: events.total }, { log });
+  const extras = await writeOutputs(cfg, { captions, cards, segs, clean, narration: audio.narration, total: events.total }, { log });
   return { out: audio.out, extras, preview, warnings: [...warnings, ...audio.warnings], duration: events.total, seconds: Math.round((Date.now() - t0) / 1000) };
 }

package/src/check.mjs

@@ -4,7 +4,7 @@ import YAML from 'yaml';
 import { loadConfig } from './config.mjs';
 import { gitIgnored } from './auth.mjs';
 
-const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'colorScheme',
+const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'lang', 'colorScheme',
   'scrollOffset', 'captionPosition', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
 const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc'];
 const ZOOM = ['target', 'scale', 'start', 'end', 'ramp', 'offset'];
@@ -12,9 +12,9 @@ const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'b
 const TARGET = ['role', 'name', 'text', 'label', 'placeholder', 'alt', 'testId', 'css', 'exact', 'last', 'nth'];
 const OPTS = ['ms', 'offset', 'timeout', 'highlight', 'color', 'box'];
 const ACTIONS = {
-  pause: 'number', wait: 'number', move: 'target', hover: 'target', click: 'target', dismiss: 'target', waitFor: 'target',
+  pause: 'number', wait: 'number', move: 'target', hover: 'target', click: 'target', dblclick: 'target', dismiss: 'target', waitFor: 'target',
   waitForUrl: 'string', networkIdle: 'any', goto: 'string', scrollTo: 'target', scroll: 'any', type: 'type', drag: 'drag', press: 'any',
-  mark: 'mark', unmark: 'any', note: 'note', select: 'select',
+  mark: 'mark', unmark: 'any', note: 'note', select: 'select', hide: 'any', slide: 'slide', paste: 'type',
 };
 
 const dist = (a, b) => {
@@ -73,7 +73,7 @@ export function check(file, { draft = false } = {}) {
     // tutorials: one thing per step, so the viewer can follow (and the narration can explain it)
     const purpose = raw.purpose ?? 'pitch';
     if ((purpose === 'tutorial' || purpose === 'course') && !s.hidden) {
-      const doing = (s.actions ?? []).filter((a) => a && ['click', 'type', 'drag', 'press', 'goto', 'select'].includes(Object.keys(a)[0]) && !(Object.keys(a)[0] === 'press' && /^(Enter|Tab)$/.test(String(Object.values(a)[0]))));
+      const doing = (s.actions ?? []).filter((a) => a && ['click', 'dblclick', 'type', 'drag', 'press', 'goto', 'select', 'slide', 'paste'].includes(Object.keys(a)[0]) && !(Object.keys(a)[0] === 'press' && /^(Enter|Tab)$/.test(String(Object.values(a)[0]))));
       if (doing.length > 2) warnings.push(`${where}: does ${doing.length} things (${doing.map((a) => Object.keys(a)[0]).join(', ')}) in one step — in a ${purpose}, split it so each action gets its own explanation and the viewer can keep up`);
       if (doing.length && !s.say) warnings.push(`${where}: does something but has no say: line — in a ${purpose}, tell the viewer what and why`);
       const kinds = (s.actions ?? []).map((a) => a && Object.keys(a)[0]);
@@ -84,7 +84,8 @@ export function check(file, { draft = false } = {}) {
   }
   if (raw.end_card) unknown(raw.end_card, END, 'end_card');
   if (raw.intro) unknown(raw.intro, END, 'intro');
-  if (raw.frame && typeof raw.frame === 'object') unknown(raw.frame, ['background'], 'frame');
+  if (raw.article) unknown(raw.article, ['title', 'intro'], 'article');
+  if (raw.frame && typeof raw.frame === 'object') unknown(raw.frame, ['background', 'style'], 'frame');
   const todo = (fs.readFileSync(file, 'utf8').split('\n').map((l, i) => [l.replace(/#.*$/, ''), i + 1]).filter(([l]) => /\bTODO\b/.test(l)));
   for (const [, n] of todo) errors.push(`line ${n}: replace the TODO placeholder`);
 
@@ -101,18 +102,23 @@ export function check(file, { draft = false } = {}) {
     if (type === 'string' && typeof v !== 'string') errors.push(`${where}: ${kind} takes a string`);
     if (type === 'target') target(v, `${where} (${kind})`);
     if (type === 'mark' && typeof v !== 'string') target(v, `${where} (mark)`); // a string is a phrase to highlight
+    if (type === 'slide') {
+      if (!v?.target || typeof v?.to !== 'number' || v.to < 0 || v.to > 1) errors.push(`${where}: slide needs { target: <slider>, to: 0..1 } (0 = start of the track, 1 = end)`);
+      else target(v.target, `${where} (slide.target)`);
+    }
     if (type === 'select') {
       if (!v?.target || v?.option == null) errors.push(`${where}: select needs { target: <dropdown>, option: "visible text of the option" }`);
       else target(v.target, `${where} (select.target)`);
     }
     if (type === 'note') {
       if (!v?.target || !v?.text) errors.push(`${where}: note needs { target: <target>, text: "short label" }`);
+      else if (isPoint(v.target)) errors.push(`${where}: a note points at an element, not a screen position — target the element (a label, button, cell…) next to that spot`);
       else { target(v.target, `${where} (note.target)`); unknown(v, ['target', 'text', 'side', 'ms', 'timeout'], `${where} (note)`); }
       if (v?.side && !['auto', 'left', 'right', 'top', 'bottom'].includes(v.side)) errors.push(`${where}: note side must be auto, left, right, top or bottom`);
     }
     if (type === 'type') {
       if (typeof v === 'string' || typeof v === 'number') return;
-      if (v?.text == null) errors.push(`${where}: type needs text — "type: hello" types into the focused element, "type: { target: <target>, text: hello }" clicks the target first`);
+      if (v?.text == null) errors.push(`${where}: ${kind} needs text — "type: hello" types into the focused element, "type: { target: <target>, text: hello }" clicks the target first`);
       else if (v.target) target(v.target, `${where} (type.target)`);
     }
     if (type === 'drag') {

package/src/compose.mjs

@@ -116,17 +116,30 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const tw = 160, th = 90, rate = 10;
     const buf = execFileSync('ffmpeg', ['-loglevel', 'error', '-framerate', `${FPS}`, '-i', path.join(SEQ, '%05d.jpg'),
       '-vf', `fps=${rate},scale=${tw}:${th},format=gray`, '-f', 'rawvideo', 'pipe:1'], { maxBuffer: 1 << 28 });
-    const n = Math.floor(buf.length / (tw * th)), score = [];
+    // plus the share of 8x8 blocks with no detail at all: an empty canvas or image area that is still
+    // loading (dark or light) next to toolbars that are already there
+    const n = Math.floor(buf.length / (tw * th)), score = [], flat = [];
     for (let f = 0; f < n; f++) {
       let e = 0;
+      const blocks = new Float64Array(Math.ceil(tw / 8) * Math.ceil(th / 8));
       for (let y = 0, o = f * tw * th; y < th - 1; y++) for (let x = 0; x < tw - 1; x++) {
-        const k = o + y * tw + x;
-        e += Math.abs(buf[k] - buf[k + 1]) + Math.abs(buf[k] - buf[k + tw]);
+        const k = o + y * tw + x, d = Math.abs(buf[k] - buf[k + 1]) + Math.abs(buf[k] - buf[k + tw]);
+        e += d; blocks[Math.floor(y / 8) * Math.ceil(tw / 8) + Math.floor(x / 8)] += d;
       }
       score.push(e / (tw * th));
+      flat.push(blocks.filter((b) => b / 64 < 0.6).length / blocks.length);
     }
     const median = [...score].sort((a, b) => a - b)[Math.floor(n / 2)] ?? 0;
     const blank = score.map((e) => e < 3 && e < median * 0.4);
+    for (const g of segs) {
+      // compared with how the step ends (its content loaded): much emptier = still loading. Only right
+      // after the step waited for something (a load), so drawing on an empty canvas isn't flagged.
+      const last = Math.min(n - 1, Math.max(0, Math.floor(g.o1 * rate) - 1));
+      const loading = (tl.steps[g.i].waits ?? []).map(([a, b]) => [toOut(a), toOut(b)]).filter(([a]) => a != null).map(([a, b]) => [a, (b ?? a) + 1.5]);
+      for (let f = Math.ceil(g.o0 * rate); f <= last; f++) {
+        if (flat[f] > 0.55 && flat[f] - flat[last] > 0.25 && loading.some(([a, b]) => f / rate >= a - 0.1 && f / rate <= b)) blank[f] = true;
+      }
+    }
     for (const g of segs) {
       let run = 0, from = 0;
       const report = (to) => { if (run / rate >= 0.2) warn(`step ${g.i + 1}: ${(run / rate).toFixed(1)}s of near-blank frames at ${from.toFixed(1)}–${to.toFixed(1)}s (the page is still loading) — move that load into a hidden step, or wait for the loaded content before the step starts`); };
@@ -172,7 +185,9 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     if (t && typeof t === 'object' && typeof t.x === 'number' && typeof t.y === 'number' && !t.role && !t.css && !t.text) {
       // a point needs no measuring, so it works even if the zoom was added after recording
       const { width: VW, height: VH } = cfg.viewport;
-      g.zoomBox = { x: t.x <= 1 ? t.x * VW : t.x, y: t.y <= 1 ? t.y * VH : t.y, width: 0, height: 0 };
+      // a point names the middle of the subject: give it some area, so captions keep off it too
+      const px = t.x <= 1 ? t.x * VW : t.x, py = t.y <= 1 ? t.y * VH : t.y, bw = VW * 0.12, bh = VH * 0.1;
+      g.zoomBox = { x: px - bw / 2, y: py - bh / 2, width: bw, height: bh };
     } else if (t && 'zoomTarget' in tl.steps[g.i] && JSON.stringify(tl.steps[g.i].zoomTarget) !== JSON.stringify(t)) {
       warn(`step ${g.i + 1}: zoom target was added or changed after recording, so its position is unknown — re-render with mode "render" (or use a point target)`);
       g.zoomBox = null;
@@ -213,7 +228,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   };
   // browser-window frame: the page is drawn at (FX, FY), FW x FH, inside a window on a backdrop
   const even = (x) => 2 * Math.round(x / 2);
-  const FW = cfg.frame ? even(W * 0.86) : W, FH = cfg.frame ? even(H * 0.86) : H, BAR = cfg.frame ? Math.round(H * 0.034) : 0;
+  const FW = cfg.frame ? even(W * 0.82) : W, FH = cfg.frame ? even(H * 0.82) : H, BAR = cfg.frame ? Math.round(H * 0.034) : 0;
   const FX = even((W - FW) / 2), FY = cfg.frame ? even((H - FH - BAR) / 2 + BAR) : 0, F = FW / W;
   const onScreen = (b, t) => {
     const v = view(t);
@@ -280,51 +295,61 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       warn(`step ${g.i + 1}: the ${want} caption would cover ${hit.what}, so it was moved to the ${other}` + (explicit ? ` (despite captionPosition: ${explicit})` : '') + ` — set captionPosition: ${other} to make this explicit`);
     } else if (hit) warn(`step ${g.i + 1}: the caption covers ${hit.what} at both top and bottom — shorten the caption, or change the zoom`);
     if (prev && n === prev.n && prev.pos === pos) prev.t[1] = g.o1;
-    else captions.push({ text: g.step.caption, t: [g.o0, g.o1], pos, n });
+    else captions.push({ text: g.step.caption, t: [g.o0, g.o1], pos, n, h });
   }
   for (const [i, c] of captions.entries()) await shot(bubble(c.text, c.n, c.pos), path.join(cfg.work, `cap${i}.png`), true);
   // Intro and end cards are short animations (logo pops, title rises, the highlight sweeps, a command
   // CTA types itself out), rendered frame by frame by seeking the page's CSS animations.
   const u = H / 1080;
+  // cards follow the frame: dark backdrops (aurora, dark, blur) get dark cards, so a dark app doesn't
+  // cut to a white card; `cards: light | dark` overrides
+  const darkCards = cfg.cards === 'dark' || (cfg.cards !== 'light' && ['aurora', 'dark', 'blur'].includes(cfg.frame?.style));
+  const CK = darkCards
+    ? { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#1e2a44 0%,#111830 60%,#0b1020 100%)`, title: '#f1f5f9', sub: '#cbd5e1', muted: '#94a3b8', item: '#e2e8f0', track: '#26314d',
+      pillBg: '#1a2238', pillFg: '#e2e8f0', pillLine: '1px solid #33405f', ctaBg: accent, ctaFg: ink, shadow: 'rgba(0,0,0,.45)' }
+    : { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#ffffff 0%,#eef2f7 60%,#e2e8f0 100%)`, title: ink, sub: '#334155', muted: '#64748b', item: '#1e293b', track: '#e2e8f0',
+      pillBg: ink, pillFg: '#e2e8f0', pillLine: 'none', ctaBg: ink, ctaFg: '#fff', shadow: 'rgba(15,23,42,.25)' };
   const card = (c, logoPath, { thinkAt = 0 } = {}) => {
     const image = c.imageFile && fs.existsSync(c.imageFile)
       ? `<img class="a rise" src="data:image/${path.extname(c.imageFile).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(c.imageFile).toString('base64')}" style="animation-delay:.4s;max-width:${W * 0.6}px;max-height:${H * 0.42}px;border-radius:${12 * H / 1080}px;box-shadow:0 ${12 * H / 1080}px ${36 * H / 1080}px rgba(15,23,42,.18)">` : '';
-    const think = c.think ? `<div class="a rise" style="animation-delay:${thinkAt.toFixed(2)}s;position:absolute;left:50%;bottom:${H * 0.1}px;transform:translateX(-50%);width:${W * 0.3}px;text-align:center;font-size:${26 * H / 1080}px;color:#64748b">
-        <div style="margin-bottom:${12 * H / 1080}px">Pause and think</div>
-        <div style="height:${8 * H / 1080}px;border-radius:99px;background:#e2e8f0;overflow:hidden"><div style="height:100%;background:${accent};transform-origin:left;animation:drain ${c.think}s linear ${thinkAt.toFixed(2)}s both"></div></div></div>
+    const think = c.think ? `<div class="a rise" style="animation-delay:${thinkAt.toFixed(2)}s;position:absolute;left:50%;bottom:${H * 0.1}px;transform:translateX(-50%);width:${W * 0.3}px;text-align:center;font-size:${26 * H / 1080}px;color:${CK.muted}">
+        <div style="margin-bottom:${12 * H / 1080}px">${cfg.lang === 'zh' ? '先想一想' : 'Pause and think'}</div>
+        <div style="height:${8 * H / 1080}px;border-radius:99px;background:${CK.track};overflow:hidden"><div style="height:100%;background:${accent};transform-origin:left;animation:drain ${c.think}s linear ${thinkAt.toFixed(2)}s both"></div></div></div>
         <style>@keyframes drain{from{transform:scaleX(1)}to{transform:scaleX(0)}}</style>` : '';
     const logo = fs.existsSync(logoPath)
-      ? `<img class="a pop" src="data:image/${path.extname(logoPath).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(logoPath).toString('base64')}" style="height:${Math.round(H * 0.09)}px">` : '';
+      ? `<img class="a pop" src="data:image/${path.extname(logoPath).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(logoPath).toString('base64')}" style="height:${Math.round(H * 0.09)}px;${darkCards ? `background:#fff;padding:${Math.round(10 * u)}px ${Math.round(16 * u)}px;border-radius:${Math.round(14 * u)}px;box-shadow:0 ${8 * u}px ${24 * u}px rgba(0,0,0,.35)` : ''}">` : ''; // logos captured from a light page often carry its white: give them a plate on dark cards
     const cmd = c.cta && /^\$?\s*(npx|npm|pnpm|yarn|bun|pip|pipx|uv|brew|curl|git|docker|cargo|go)\b/.test(c.cta);
     const ctaText = String(c.cta ?? '').replace(/^\$\s*/, '');
     return `<body style="margin:0;width:${W}px;height:${H}px;${fontCss}
-      background:radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#ffffff 0%,#eef2f7 60%,#e2e8f0 100%);
+      background:${CK.bg};
       display:flex;flex-direction:column;align-items:center;justify-content:center;gap:${28 * u}px;text-align:center">
       <style>
         .a{animation-fill-mode:both;animation-timing-function:cubic-bezier(.2,.8,.2,1)}
         .pop{animation-name:pop;animation-duration:.55s;animation-delay:.05s}
         .rise{animation-name:rise;animation-duration:.6s}
-        .hl{background:linear-gradient(transparent 62%,${accent} 62%) no-repeat 0 0/0% 100%;animation:sweep .6s cubic-bezier(.4,0,.2,1) .75s both}
+        ${darkCards
+          ? `.hl{color:${accent};background:linear-gradient(${accent},${accent}) no-repeat 0 100%/0% ${Math.max(2, Math.round(3 * u))}px;padding-bottom:${Math.round(4 * u)}px;animation:sweep .6s cubic-bezier(.4,0,.2,1) .75s both}`
+          : `.hl{background:linear-gradient(transparent 60%,${accent} 60%) no-repeat 0 0/0% 100%;animation:sweep .6s cubic-bezier(.4,0,.2,1) .75s both}`}
         .type{display:inline-block;overflow:hidden;white-space:nowrap;vertical-align:bottom;width:0;animation:type ${(ctaText.length * 0.045).toFixed(2)}s steps(${ctaText.length || 1}) .8s both}
         .caret{display:inline-block;width:.55em;height:1.1em;margin-left:.1em;vertical-align:-.15em;background:${accent};animation:blink 1s steps(1) .8s infinite}
         @keyframes pop{from{opacity:0;transform:scale(.7)}to{opacity:1;transform:none}}
         @keyframes rise{from{opacity:0;transform:translateY(${24 * u}px)}to{opacity:1;transform:none}}
-        @keyframes sweep{to{background-size:100% 100%}}
+        @keyframes sweep{to{background-size:100% ${darkCards ? `${Math.max(2, Math.round(3 * u))}px` : '100%'}}}
         @keyframes type{to{width:${ctaText.length}ch}}
         @keyframes blink{50%{opacity:0}}
       </style>
-      ${c.kicker ? `<div class="a rise" style="font-size:${30 * u}px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:#64748b">${esc(c.kicker)}</div>` : ''}
+      ${c.kicker ? `<div class="a rise" style="font-size:${30 * u}px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:${CK.muted}">${esc(c.kicker)}</div>` : ''}
       <div style="display:flex;align-items:center;gap:${22 * u}px">${logo}
-        ${c.title ? `<span class="a rise" style="animation-delay:.12s;font-size:${92 * u}px;font-weight:600;letter-spacing:-.03em;color:${ink}">${esc(c.title).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</span>` : ''}</div>
-      ${c.subtitle ? `<div class="a rise" style="animation-delay:.3s;font-size:${44 * u}px;color:#334155;letter-spacing:-.01em">${esc(c.subtitle).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</div>` : ''}
+        ${c.title ? `<span class="a rise" style="animation-delay:.12s;display:block;max-width:${W * 0.8}px;text-wrap:balance;line-height:1.15;font-size:${(c.title.length > 40 ? 68 : 92) * u}px;font-weight:600;letter-spacing:-.03em;color:${CK.title}">${esc(c.title).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</span>` : ''}</div>
+      ${c.subtitle ? `<div class="a rise" style="animation-delay:.3s;font-size:${44 * u}px;color:${CK.sub};letter-spacing:-.01em">${esc(c.subtitle).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</div>` : ''}
       ${image}${think}
       ${c.bullets?.length ? `<ol style="margin:${10 * u}px 0 0;padding:0;list-style:none;text-align:left;display:flex;flex-direction:column;gap:${18 * u}px">${c.bullets.map((b, k) =>
-        `<li class="a rise" style="animation-delay:${(0.6 + 0.4 * k).toFixed(2)}s;display:flex;align-items:center;gap:${20 * u}px;font-size:${38 * u}px;color:#1e293b">
+        `<li class="a rise" style="animation-delay:${(0.6 + 0.4 * k).toFixed(2)}s;display:flex;align-items:center;gap:${20 * u}px;font-size:${38 * u}px;color:${CK.item}">
           <span style="flex:none;display:inline-flex;align-items:center;justify-content:center;width:${52 * u}px;height:${52 * u}px;border-radius:50%;background:${accent};color:${ink};font-weight:700;font-size:${28 * u}px">${k + 1}</span>
-          <span>${md(b, ink)}</span></li>`).join('')}</ol>` : ''}
+          <span>${md(b, darkCards ? accent : ink)}</span></li>`).join('')}</ol>` : ''}
       ${!c.cta ? '' : cmd
-        ? `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font:500 ${36 * u}px ui-monospace,SFMono-Regular,Menlo,monospace;color:#e2e8f0;background:${ink};padding:${20 * u}px ${36 * u}px;border-radius:${16 * u}px;text-align:left;box-shadow:0 ${16 * u}px ${40 * u}px rgba(15,23,42,.25)"><span style="color:${accent}">$</span> <span class="type">${esc(ctaText)}</span><span class="caret"></span></div>`
-        : `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font-size:${38 * u}px;font-weight:600;color:#fff;background:${ink};padding:${20 * u}px ${46 * u}px;border-radius:${16 * u}px">${esc(c.cta)}</div>`}
+        ? `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font:500 ${36 * u}px ui-monospace,SFMono-Regular,Menlo,monospace;color:${CK.pillFg};background:${CK.pillBg};border:${CK.pillLine};padding:${20 * u}px ${36 * u}px;border-radius:${16 * u}px;text-align:left;box-shadow:0 ${16 * u}px ${40 * u}px ${CK.shadow}"><span style="color:${accent}">$</span> <span class="type">${esc(ctaText)}</span><span class="caret"></span></div>`
+        : `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font-size:${38 * u}px;font-weight:600;color:${CK.ctaFg};background:${CK.ctaBg};padding:${20 * u}px ${46 * u}px;border-radius:${16 * u}px">${esc(c.cta)}</div>`}
       </body>`;
   };
   const animate = async (html, seconds, dir) => {
@@ -343,20 +368,32 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   for (const [k, c] of cards.entries()) await animate(card(c.card, c.card.logoFile ?? '', { thinkAt: c.thinkAt }), c.t1 - c.t0, path.join(cfg.work, `card${k}`));
   if (in0) await animate(card(in0, in0.logoFile ?? path.join(cfg.work, 'intro-logo.png')), INTRO, path.join(cfg.work, 'intro'));
   if (cfg.frame) {
-    // backdrop + window (under the page) and the backdrop again with a rounded hole (over it, for the corners)
-    const bg = cfg.frame.background ?? `radial-gradient(${W * 0.7}px ${H * 0.8}px at 15% 0%, ${accent}66, transparent 70%), radial-gradient(${W * 0.7}px ${H * 0.8}px at 100% 100%, #6366f166, transparent 70%), linear-gradient(135deg, #1e293b, ${ink})`;
-    const R = Math.round(12 * u), host = new URL(cfg.url).host.replace(/^www\./, '') + new URL(cfg.url).pathname.replace(/\/$/, '');
-    const dot = (c) => `<span style="width:${13 * u}px;height:${13 * u}px;border-radius:50%;background:${c};display:inline-block"></span>`;
-    await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:${bg};${fontCss}">
-      <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${FH + BAR}px;border-radius:${R}px;background:#fff;box-shadow:0 ${30 * u}px ${80 * u}px rgba(0,0,0,.45),0 0 0 1px rgba(255,255,255,.08)"></div>
-      <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${BAR}px;border-radius:${R}px ${R}px 0 0;background:#e8ebef;display:flex;align-items:center;border-bottom:1px solid #d5d9df">
+    // three layers: the backdrop (a picture, or the page itself blurred), the window chrome (shadow and
+    // title bar), and the page with rounded bottom corners
+    const grain = `url('data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200"><filter id="n"><feTurbulence type="fractalNoise" baseFrequency=".9" numOctaves="2" stitchTiles="stitch"/><feColorMatrix values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 .09 0"/></filter><rect width="200" height="200" filter="url(#n)"/></svg>')}')`;
+    const STYLES = {
+      aurora: { dark: true, bg: `${grain}, radial-gradient(${W * 0.47}px ${H * 0.65}px at 20% 20%, #22d3ee99, transparent 60%), radial-gradient(${W * 0.47}px ${H * 0.65}px at 80% 30%, #a78bfa99, transparent 60%), radial-gradient(${W * 0.52}px ${H * 0.74}px at 50% 100%, #34d39988, transparent 60%), #0b1020` },
+      studio: { dark: false, bg: `${grain}, radial-gradient(${W * 0.73}px ${H * 0.83}px at 50% 0%, #ffffff, #e9edf3 60%, #d6dce6)` },
+      dark: { dark: true, bg: `radial-gradient(${W * 0.7}px ${H * 0.8}px at 15% 0%, ${accent}66, transparent 70%), radial-gradient(${W * 0.7}px ${H * 0.8}px at 100% 100%, #6366f166, transparent 70%), linear-gradient(135deg, #1e293b, ${ink})` },
+      pastel: { dark: false, bg: 'linear-gradient(135deg, #fde2e4 0%, #e2ece9 35%, #dfe7fd 70%, #f0e6ff 100%)' },
+      blur: { dark: true, bg: null },
+    };
+    const st = STYLES[cfg.frame.style], bg = cfg.frame.background ?? st.bg;
+    const R = Math.round(14 * u), host = new URL(cfg.url).host.replace(/^www\./, '') + new URL(cfg.url).pathname.replace(/\/$/, '');
+    const dot = (col) => `<span style="width:${13 * u}px;height:${13 * u}px;border-radius:50%;background:${col};display:inline-block"></span>`;
+    const [barBg, barFg, pill, line] = st.dark ? ['#1f2430', '#9aa4b2', '#2b3140', '#11151d'] : ['#e8ebef', '#4b5563', '#fff', '#d5d9df'];
+    if (bg) await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:${bg}"></body>`, path.join(cfg.work, 'frame-bg.png'), false);
+    await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:transparent;${fontCss}">
+      <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${FH + BAR}px;border-radius:${R}px;background:#fff;box-shadow:0 ${30 * u}px ${80 * u}px rgba(0,0,0,${st.dark ? '.5' : '.25'}),0 0 0 1px rgba(255,255,255,.08)"></div>
+      <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${BAR}px;border-radius:${R}px ${R}px 0 0;background:${barBg};display:flex;align-items:center;border-bottom:1px solid ${line}">
         <div style="display:flex;gap:${8 * u}px;margin-left:${16 * u}px">${dot('#ff5f57')}${dot('#febc2e')}${dot('#28c840')}</div>
-        <div style="position:absolute;left:50%;transform:translateX(-50%);font-size:${15 * u}px;color:#4b5563;background:#fff;border-radius:${8 * u}px;padding:${4 * u}px ${60 * u}px">${esc(host)}</div>
-      </div></body>`, path.join(cfg.work, 'frame-bg.png'), false);
-    const hole = encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}"><rect x="${FX}" y="${FY - BAR}" width="${FW}" height="${FH + BAR}" rx="${R}"/></svg>`);
-    await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:transparent">
-      <div style="position:absolute;inset:0;background:${bg};-webkit-mask:linear-gradient(#000 0 0),url('data:image/svg+xml,${hole}');-webkit-mask-composite:xor;mask-composite:exclude"></div></body>`,
-      path.join(cfg.work, 'frame-fg.png'), true);
+        <div style="position:absolute;left:50%;transform:translateX(-50%);font-size:${15 * u}px;color:${barFg};background:${pill};border-radius:${8 * u}px;padding:${4 * u}px ${60 * u}px">${esc(host)}</div>
+      </div></body>`, path.join(cfg.work, 'frame-chrome.png'), true);
+    // alpha mask for the page: rounded bottom corners (the title bar covers the top ones)
+    await pg.setViewportSize({ width: FW, height: FH });
+    await pg.setContent(`<body style="margin:0;width:${FW}px;height:${FH}px;background:#000"><div style="width:100%;height:100%;background:#fff;border-radius:0 0 ${R}px ${R}px"></div></body>`);
+    await pg.screenshot({ path: path.join(cfg.work, 'frame-mask.png') });
+    await pg.setViewportSize({ width: W, height: H });
   }
   await browser.close();
 
@@ -367,11 +404,23 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     `:d=1:fps=${FPS}:s=${W}x${H},format=yuv420p${END ? `,tpad=stop_mode=clone:stop_duration=${END}` : ''}[v0];\n`;
   let last = 'v0', idx = 1;
   if (cfg.frame) {
-    inputs.push('-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, 'frame-bg.png'),
-      '-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, 'frame-fg.png'));
-    graph += `[v0]scale=${FW}:${FH}:flags=lanczos[pg];[${idx}:v][pg]overlay=${FX}:${FY}[fb];[fb][${idx + 1}:v]overlay=0:0,format=yuv420p[vf];\n`;
-    last = 'vf'; idx += 2;
+    const still = (f) => inputs.push('-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, f));
+    const blur = !cfg.frame.background && cfg.frame.style === 'blur';
+    let base;
+    if (blur) {
+      graph += `[v0]split[v0a][v0b];[v0b]scale=${even(W / 12)}:${even(H / 12)},gblur=sigma=4,scale=${W}:${H},eq=brightness=-0.12:saturation=1.3[fbg];\n`;
+      base = 'fbg';
+    } else { still('frame-bg.png'); base = `${idx++}:v`; }
+    still('frame-chrome.png'); const chrome = idx++;
+    still('frame-mask.png'); const mask = idx++;
+    graph += `[${blur ? 'v0a' : 'v0'}]scale=${FW}:${FH}:flags=lanczos,format=rgba[pg0];[${mask}:v]format=gray,scale=${FW}:${FH}[pm];[pg0][pm]alphamerge[pg];\n` +
+      `[${base}][${chrome}:v]overlay=0:0[fc];[fc][pg]overlay=${FX}:${FY},format=yuv420p[vf];\n`;
+    last = 'vf';
   }
+  // docs: a second, caption-free copy for the per-step clips and stills (the article carries the
+  // text), so crops never have to dodge a caption
+  const clean = cfg.clips.length ? path.join(cfg.work, 'video-clean.mp4') : null;
+  if (clean) { graph += `[${last}]split[vmain][vclean0];\n`; last = 'vmain'; }
   for (const [i, c] of captions.entries()) {
     const a = c.t[0] + 0.1, b = c.t[1] - 0.1;
     // each caption is an input only as long as it is on screen (decoding a looped PNG for the whole
@@ -401,6 +450,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     last = `v${idx}`;
   }
   graph += `[${last}]trim=duration=${TOTAL},format=yuv420p[out]`;
+  if (clean) graph += `;\n[vclean0]trim=duration=${TOTAL},format=yuv420p[clean]`;
   const graphFile = path.join(cfg.work, 'graph.txt');
   fs.writeFileSync(graphFile, graph);
   const silent = path.join(cfg.work, 'video-silent.mp4');
@@ -409,7 +459,8 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   const major = Number((execFileSync('ffmpeg', ['-version']).toString().match(/ffmpeg version n?(\d+)/) ?? [])[1] ?? 7);
   const graphArgs = major >= 7 ? ['-/filter_complex', graphFile] : ['-filter_complex_script', graphFile];
   execFileSync('ffmpeg', ['-y', '-loglevel', 'error', ...inputs, ...graphArgs, '-map', '[out]',
-    '-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-pix_fmt', 'yuv420p', '-r', `${FPS}`, silent]);
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-pix_fmt', 'yuv420p', '-r', `${FPS}`, silent,
+    ...(clean ? ['-map', '[clean]', '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-pix_fmt', 'yuv420p', '-r', `${FPS}`, clean] : [])]);
 
   // --- 6. preview contact sheet: one frame per step (at its zoom peak) + end card ------------
   // zoomed steps: at the zoom peak; others: late in the step, where its actions' result is visible
@@ -441,7 +492,10 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     endCard: ec ? VIDEO : null,
     clicks: tl.clicks.map(toOut).filter((t) => t != null),
     whooshes: dedupe([
-      ...tl.navs.map(toOut).filter((t) => t != null && t > 0.2),
+      // whoosh on deliberate scene changes (goto) only: a page the app opens after a click, or a
+      // results page reloading itself while you wait, is not a scene change
+      ...(tl.gotos ?? tl.navs.filter((n) => !tl.clicks.some((c) => n - c >= 0 && n - c < 2) && !tl.steps.some((s) => (s.waits ?? []).some(([a, b]) => n >= a - 0.5 && n <= b + 0.5))))
+        .map(toOut).filter((t) => t != null && t > 0.2),
       ...segs.filter((g) => g.afterHidden).map((g) => g.o0),
       ...(in0 ? [INTRO - 0.3] : []),
       ...cards.flatMap((c) => [c.t0, c.t1 - 0.3]),
@@ -472,8 +526,8 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     let w = Math.max(x1 - x0 + 2 * pad, W * 0.5), h = Math.max(y1 - y0 + 2 * pad, H * 0.5);
     if (w / h > W / H) h = w * H / W; else w = h * W / H;
     w = Math.min(W, w); h = Math.min(H, h);
-    const cx = (x0 + x1) / 2, cy = (y0 + y1) / 2;
+    let cx = (x0 + x1) / 2, cy = (y0 + y1) / 2;
     g.crop = { x: even(Math.max(0, Math.min(W - w, cx - w / 2))), y: even(Math.max(0, Math.min(H - h, cy - h / 2))), w: even(w), h: even(h) };
   }
-  return { silent, events, preview, warnings, captions, cards: cards.map((c) => ({ t: c.t0, title: [c.card.kicker, c.card.title].filter(Boolean).join(' · ') })), segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption, doc: g.step.doc ?? g.step.say, crop: g.crop })) };
+  return { silent, clean, events, preview, warnings, captions, cards: cards.map((c) => ({ t: c.t0, title: [c.card.kicker, c.card.title].filter(Boolean).join(' · ') })), segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption, doc: g.step.doc ?? g.step.say, crop: g.crop })) };
 }

package/src/config.mjs

@@ -19,9 +19,9 @@ export function loadEnv(dir) {
 
 // What the video is for sets sensible defaults; anything in the YAML overrides them.
 export const PURPOSES = {
-  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: true, pace: 'fast', follow: false },
-  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: true,  highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: false, pace: 'slow', follow: true },
-  course:   { duration: 'auto', music: false,                     sfx: true,  highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: false, pace: 'slow', follow: true },
+  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false },
+  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: true,  highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
+  course:   { duration: 'auto', music: false,                     sfx: true,  highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
   docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false },
 };
 
@@ -36,6 +36,8 @@ export const PACES = {
   slow:   { cursor: 1200, type: 95,  beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92 },
 };
 
+export const FRAME_STYLES = ['aurora', 'studio', 'dark', 'pastel', 'blur'];
+
 export const VIDEO_DIR = 'videos';
 export const KINDS = { pitch: 'promo', tutorial: 'tutorial', course: 'lesson', docs: 'docs' };
 // pxgenius.ai → pxgenius; an IP or a port is kept whole so two internal apps don't share a name
@@ -110,7 +112,11 @@ export function loadConfig(file, { draft = false } = {}) {
   // follow: the camera zooms in on what each step touches and pans from step to step (tutorials)
   const follow0 = pick('follow');
   const follow = follow0 ? { scale: 1.8, ...(typeof follow0 === 'object' ? follow0 : {}) } : null;
-  const frame = frame0 ? { background: null, ...(typeof frame0 === 'object' ? frame0 : {}) } : null;
+  // frame: false | true | a style name | { style, background: <css> }. Styles: aurora (dark, grain),
+  // studio (light, grain), dark, pastel, blur (the page itself, blurred, behind the window)
+  const styleOf = (f) => (typeof f === 'string' ? f : f?.style) ?? (typeof P.frame === 'string' ? P.frame : 'aurora');
+  const frame = frame0 ? { background: null, ...(typeof frame0 === 'object' ? frame0 : {}), style: styleOf(frame0) } : null;
+  if (frame && !FRAME_STYLES.includes(frame.style)) throw new Error(`frame style must be one of ${FRAME_STYLES.join(', ')}`);
 
   let voice = null;
   if (raw.voice) {
@@ -155,6 +161,10 @@ export function loadConfig(file, { draft = false } = {}) {
     steps,
     endCard,
     intro,
+    article: raw.article ?? null,
+    cards: raw.cards ?? 'auto',
+    // language of the built-in labels ("Pause and think", "Introduction"): `lang`, else guessed from the captions
+    lang: raw.lang ?? (/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(JSON.stringify(raw.steps ?? [])) ? 'zh' : 'en'),
     frame,
     follow,
     music,

package/src/inspect.mjs

@@ -118,8 +118,10 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
     seen.add(key);
     let target = null;
     if (el.kind === 'role') {
+      // sliders, inputs and dropdowns: their label is stable, their value (often their name) is not
+      if (['slider', 'textbox', 'combobox', 'searchbox', 'spinbutton'].includes(el.role) && el.label) target = await verify(page.getByLabel(el.label, { exact: true }), { label: el.label, exact: true }, el);
       // our name guess can differ from the browser's accessible name, so fall back gracefully
-      if (el.name) target = await verify(page.getByRole(el.role, { name: el.name, exact: true }), { role: el.role, name: el.name, exact: true }, el);
+      if (!target && el.name) target = await verify(page.getByRole(el.role, { name: el.name, exact: true }), { role: el.role, name: el.name, exact: true }, el);
       if (!target && el.alt) target = await verify(page.getByAltText(el.alt, { exact: true }), { alt: el.alt, exact: true }, el);
       if (!target && el.name) target = await verify(page.getByRole(el.role, { name: el.name }), { role: el.role, name: el.name }, el);
       if (!target && el.name) target = await verify(page.getByText(el.name, { exact: true }), { text: el.name, exact: true }, el);
@@ -156,7 +158,7 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
     '',
     '## Clickable elements — verified targets (each matches exactly one visible element) for click/move/zoom',
     '   Copy targets exactly; `name` is the accessible name, which may differ from the on-screen label.',
-    ...elements.map((e) => `${fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}`),
+    ...elements.map((e) => `${fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.role === 'slider' ? '  (slider — `slide: { target: …, to: 0..1 }`)' : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}`),
     '',
     '## Images with alt text (target: { alt: "..." })',
     ...(info.images.length ? info.images.map((i) => `${fold(i.y)} y=${i.y}\t"${i.alt}"`) : ['(none)']),

package/src/outputs.mjs

@@ -11,7 +11,7 @@ const srtTime = (t) => {
 const clock = (t) => `${Math.floor(t / 60)}:${String(Math.floor(t % 60)).padStart(2, '0')}`;
 const slug = (s) => plain(s).toLowerCase().replace(/[^a-z0-9一-鿿]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
 
-export async function writeOutputs(cfg, { captions, cards = [], segs, narration, total }, { log = console.log } = {}) {
+export async function writeOutputs(cfg, { captions, cards = [], segs, clean, narration, total }, { log = console.log } = {}) {
   const base = cfg.out.replace(/\.[^.]+$/, '');
   const files = [];
 
@@ -27,7 +27,7 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, narration,
   if (cfg.chapters && (captions.length || cards.length)) {
     // section cards make the chapters when there are any; otherwise one chapter per caption
     const lines = cards.length
-      ? [...(cards[0].t > 1 ? [`0:00 Introduction`] : []), ...cards.map((c, k) => `${clock(k === 0 && cards[0].t <= 1 ? 0 : c.t)} ${plain(c.title)}`)]
+      ? [...(cards[0].t > 1 ? [`0:00 ${cfg.lang === 'zh' ? '开场' : 'Introduction'}`] : []), ...cards.map((c, k) => `${clock(k === 0 && cards[0].t <= 1 ? 0 : c.t)} ${plain(c.title)}`)]
       : captions.map((c, k) => `${clock(k === 0 ? 0 : c.t[0])} ${cfg.stepNumbers ? `${c.n}. ` : ''}${plain(c.text)}`);
     fs.writeFileSync(`${base}.chapters.txt`, `${lines.join('\n')}\n`);
     files.push(`${base}.chapters.txt`);
@@ -40,12 +40,17 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, narration,
     const dir = `${base}-steps`;
     fs.rmSync(dir, { recursive: true, force: true });
     fs.mkdirSync(dir, { recursive: true });
-    const article = [`# ${plain(cfg.intro?.title ?? cfg.name)}`, ''];
+    // title and intro: `article: { title, intro }`, else the intro card, else the name in words
+    const art = cfg.article ?? {};
+    const title = art.title ?? cfg.intro?.title ?? cfg.name.replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase());
+    const intro = art.intro ?? cfg.intro?.subtitle;
+    const article = [`# ${plain(title)}`, '', ...(intro ? [String(intro), ''] : [])];
     for (const [k, g] of segs.entries()) {
       const stem = `${String(k + 1).padStart(2, '0')}${g.caption ? `-${slug(g.caption)}` : ''}`;
       const crop = g.crop ? `crop=${g.crop.w}:${g.crop.h}:${g.crop.x}:${g.crop.y},` : '';
       const cw = g.crop?.w ?? cfg.output.width;
-      const span = ['-ss', g.o0.toFixed(3), '-t', (g.o1 - g.o0).toFixed(3), '-i', cfg.out];
+      const src = clean && fs.existsSync(clean) ? clean : cfg.out; // the caption-free copy
+      const span = ['-ss', g.o0.toFixed(3), '-t', (g.o1 - g.o0).toFixed(3), '-i', src];
       const made = [];
       for (const kind of cfg.clips) {
         const f = path.join(dir, `${stem}.${kind}`);
@@ -54,7 +59,7 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, narration,
           execFileSync('ffmpeg', ['-y', '-loglevel', 'error', ...span, '-filter_complex',
             `${crop}fps=12,scale=${w}:-1:flags=lanczos,split[a][b];[a]palettegen=max_colors=160:stats_mode=diff[p];[b][p]paletteuse=dither=sierra2_4a:diff_mode=rectangle`, f]);
         } else if (kind === 'png') {
-          execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-ss', Math.max(g.o0, g.o1 - 0.2).toFixed(3), '-i', cfg.out, '-frames:v', '1', ...(crop ? ['-vf', crop.slice(0, -1)] : []), f]);
+          execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-ss', Math.max(g.o0, g.o1 - 0.2).toFixed(3), '-i', src, '-frames:v', '1', ...(crop ? ['-vf', crop.slice(0, -1)] : []), f]);
         } else if (kind === 'webm') {
           execFileSync('ffmpeg', ['-y', '-loglevel', 'error', ...span, '-an', '-vf', `${crop}scale=${Math.min(cw, 1280)}:-2`, '-c:v', 'libvpx-vp9', '-b:v', '0', '-crf', '34', '-row-mt', '1', f]);
         } else {
@@ -62,7 +67,7 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, narration,
         }
         files.push(f); made.push(path.basename(f));
       }
-      article.push(`${k + 1}. **${plain(g.caption ?? `Step ${k + 1}`)}**${g.doc ? `\n\n   ${plain(g.doc)}` : ''}`, '');
+      article.push(`${k + 1}. **${plain(g.caption ?? `Step ${k + 1}`)}**${g.doc ? `\n\n   ${String(g.doc)}` : ''}`, ''); // doc text keeps its **bold**
       const show = made.find((m) => m.endsWith('.gif') || m.endsWith('.png'));
       if (show) article.push(`   ![${plain(g.caption ?? `Step ${k + 1}`)}](${encodeURI(show)})`, '');
     }

package/src/record.mjs

@@ -233,13 +233,52 @@ function pageScript({ scrollOffset }) {
     const x0 = Math.min(r.left, p.left), y0 = Math.min(r.top, p.top);
     return { x: x0, y: y0, width: Math.max(r.right, p.right) - x0, height: Math.max(r.bottom, p.bottom) - y0 };
   };
-  window.__demoUnnote = () => {
+  // native <select> popups are drawn by the OS, not the page, so they never appear in a recording:
+  // draw a look-alike menu under the dropdown, return where the chosen option is
+  window.__demoMenu = (r, items, pick) => {
+    document.getElementById('__demo_menu')?.remove();
+    const m = document.createElement('div');
+    m.id = '__demo_menu';
+    const fs = Math.max(13, Math.min(18, r.height * 0.6));
+    Object.assign(m.style, { position: 'fixed', left: `${r.x}px`, top: `${r.y + r.height + 4}px`, minWidth: `${r.width}px`, zIndex: '2147483645', pointerEvents: 'none',
+      background: '#fff', border: '1px solid #cbd5e1', borderRadius: '8px', boxShadow: '0 12px 32px rgba(15,23,42,.22)', padding: '4px', font: `${fs}px -apple-system, "Segoe UI", sans-serif`, color: '#0f172a' });
+    items.forEach((t, i) => {
+      const o = document.createElement('div');
+      o.textContent = t;
+      Object.assign(o.style, { padding: `${fs * 0.35}px ${fs * 0.7}px`, borderRadius: '5px', whiteSpace: 'nowrap', transition: 'background .15s' });
+      o.dataset.i = i;
+      m.appendChild(o);
+    });
+    document.documentElement.appendChild(m);
+    // keep it on screen: open upwards if there is no room below
+    const b = m.getBoundingClientRect();
+    if (b.bottom > innerHeight - 8) m.style.top = `${Math.max(8, r.y - b.height - 4)}px`;
+    m.animate([{ opacity: 0, transform: 'translateY(-4px)' }, { opacity: 1, transform: 'none' }], { duration: 160, easing: 'ease-out' });
+    const q = m.children[pick].getBoundingClientRect();
+    return { x: q.x + Math.min(q.width / 2, 120), y: q.y + q.height / 2 };
+  };
+  window.__demoMenuHover = (i) => { const m = document.getElementById('__demo_menu'); if (m) [...m.children].forEach((o, k) => { o.style.background = k === i ? '#e0ecff' : ''; }); };
+  window.__demoMenuClose = () => document.getElementById('__demo_menu')?.remove();
+  // downloads leave no trace in a recording: show a browser-style "downloaded" bubble instead
+  window.__demoDownload = (name) => {
+    const el = document.createElement('div');
+    el.innerHTML = `<span style="display:inline-grid;place-items:center;width:30px;height:30px;border-radius:50%;background:#22c55e;color:#fff;font-weight:700">✓</span><span><b style="display:block;font-weight:600">${name.replace(/[<&]/g, '')}</b><span style="color:#64748b;font-size:14px">Downloaded</span></span>`;
+    Object.assign(el.style, { position: 'fixed', right: '24px', top: '20px', zIndex: '2147483646', pointerEvents: 'none', display: 'flex', alignItems: 'center', gap: '12px',
+      background: '#fff', color: '#0f172a', font: '16px -apple-system, "Segoe UI", sans-serif', padding: '12px 18px 12px 14px', borderRadius: '12px', boxShadow: '0 12px 32px rgba(15,23,42,.25)', border: '1px solid #e2e8f0' });
+    document.documentElement.appendChild(el);
+    el.animate([{ opacity: 0, transform: 'translateY(-8px)' }, { opacity: 1, transform: 'none', offset: 0.1 }, { opacity: 1, offset: 0.85 }, { opacity: 0 }], { duration: 2800, easing: 'ease-out' }).onfinish = () => el.remove();
+  };
+  window.__demoUnnote = (instant) => {
+    // detach it first, so a note or mark added during the fade gets a fresh layer instead of vanishing with this one
     const layer = document.getElementById('__demo_notes');
-    if (layer) { layer.style.opacity = '0'; setTimeout(() => layer.remove(), 300); }
+    if (layer && instant) layer.remove();
+    else if (layer) { layer.id = ''; layer.style.opacity = '0'; setTimeout(() => layer.remove(), 300); }
   };
-  window.__demoUnmark = () => {
+  window.__demoUnmark = (instant) => {
+    // detach it first, so a note or mark added during the fade gets a fresh layer instead of vanishing with this one
     const layer = document.getElementById('__demo_marks');
-    if (layer) { layer.style.opacity = '0'; setTimeout(() => layer.remove(), 300); }
+    if (layer && instant) layer.remove();
+    else if (layer) { layer.id = ''; layer.style.opacity = '0'; setTimeout(() => layer.remove(), 300); }
   };
   // in-page anchor links scroll smoothly instead of jumping. Runs after the page's own handlers
   // (bubble phase) and only when none of them handled the click, so app links like
@@ -299,9 +338,14 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   const browser = await chromium.launch();
   const context = await sessionContext(browser, {
     viewport: cfg.viewport, deviceScaleFactor: cfg.scale, colorScheme: cfg.colorScheme, storageState: cfg.storageState, ignoreHTTPSErrors: cfg.ignoreHTTPSErrors,
+    permissions: ['clipboard-read', 'clipboard-write'], // for `paste`
   });
   await context.addInitScript(pageScript, { scrollOffset: cfg.scrollOffset });
   const page = await context.newPage();
+  page.on('download', (d) => {
+    page.evaluate((n) => window.__demoDownload?.(n), d.suggestedFilename()).catch(() => {});
+    marks.push({ t: Date.now() / 1000, box: { x: cfg.viewport.width - 360, y: 10, width: 340, height: 80 } }); // so docs crops include the bubble
+  });
   const sleep = (ms) => page.waitForTimeout(ms);
   const now = () => Date.now() / 1000;
 
@@ -309,7 +353,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   let cur = { x: VW * 0.62, y: VH * 0.55 };
   const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
   async function moveTo(x, y, ms = 700) {
-    if (fast) ms = 40;
+    if (fast) ms = Math.min(ms, 160); // still along the real path: menus that open on hover must behave as in the recording
     const from = { ...cur }, steps = Math.max(8, Math.round(ms / 16));
     for (let i = 1; i <= steps; i++) {
       const k = ease(i / steps);
@@ -322,6 +366,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   // a pause after an action that changes the page (tutorial pace), counted like a `pause`
   const beat = async () => { if (fast || !cfg.pace.beat) return; holds += cfg.pace.beat / 1000; await sleep(cfg.pace.beat); };
   const clicks = [];
+  const gotos = []; // deliberate scene changes (a whoosh); other navigations are the app's own
   async function press() { clicks.push(now()); await page.mouse.down(); await sleep(70); await page.mouse.up(); }
   // Time spent waiting on the page (loads, AI processing…) is tracked separately so
   // compose can compress it hard while keeping cursor motion at a natural speed.
@@ -394,17 +439,28 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         await moveTo(p.x, p.y, opt.ms ?? cfg.pace.cursor);
         break;
       }
-      case 'click': {
+      case 'click': case 'dblclick': {
         const p = await pointOf(spec, opt);
         const lit = await spot(p.box, hl);
         await moveTo(p.x, p.y, opt.ms ?? cfg.pace.cursor);
         await sleep(lit ? 350 + cfg.pace.beat / 3 : 120);
-        await press();
+        if (kind === 'dblclick') { clicks.push(now()); await page.mouse.dblclick(p.x, p.y); } else await press();
         if (lit) { await sleep(150); await spotOff(); }
         await settle();
         await beat(); // let the viewer see what the click did
         break;
       }
+      case 'hide': {
+        // hide: ".chat-widget, [id*=QSI]" — keep pop-ups, survey prompts, feedback tabs and chat widgets
+        // out of the video for good, on this page and every page after it (they often appear late)
+        const css = `${[].concat(value).join(', ')} { display: none !important; visibility: hidden !important; }`;
+        await context.addInitScript((c) => {
+          const add = () => { if (!document.getElementById('__demo_hide')) document.documentElement.appendChild(Object.assign(document.createElement('style'), { id: '__demo_hide', textContent: c })); };
+          if (document.documentElement) add(); else document.addEventListener('DOMContentLoaded', add);
+        }, css);
+        await page.evaluate((c) => document.documentElement.appendChild(Object.assign(document.createElement('style'), { textContent: c })), css);
+        break;
+      }
       case 'dismiss': {
         const l = locate(page, spec);
         if (await l.isVisible().catch(() => false)) { await l.click(); await sleep(400); }
@@ -413,7 +469,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       case 'waitFor': await waiting(() => locate(page, spec).waitFor({ state: 'visible', timeout: opt.timeout ?? 180000 })); await settle(); await nudge(); break;
       case 'waitForUrl': await waiting(() => page.waitForURL(value, { timeout: 60000 })); await settle(); await nudge(); break;
       case 'networkIdle': await waiting(() => page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {})); await settle(); break;
-      case 'goto': await waiting(() => page.goto(new URL(value, cfg.url).href, { waitUntil: 'domcontentloaded' })); await settle(); await nudge(); break;
+      case 'goto': gotos.push(now()); await waiting(() => page.goto(new URL(value, cfg.url).href, { waitUntil: 'domcontentloaded' })); await settle(); await nudge(); break;
       case 'scrollTo': {
         const h = await locate(page, spec).elementHandle({ timeout: opt.timeout ?? 15000 });
         await page.evaluate(([el, ms]) => window.__demoScrollTo(el, ms), [h, opt.ms ?? 1200]);
@@ -423,6 +479,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       case 'type': {
         // type: "text" or { text } types into whatever has focus; { target, text } clicks the target first
         const v = typeof value === 'object' ? value : { text: value };
+        // clear: true empties the field first (the page may have pre-filled it)
         let lit = false;
         if (v.target) {
           const p = await pointOf(v.target, v);
@@ -430,6 +487,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
           await moveTo(p.x, p.y, v.ms ?? cfg.pace.cursor * 0.85);
           await press();
         }
+        if (v.clear) { await page.keyboard.press('ControlOrMeta+A'); await page.keyboard.press('Delete'); }
         await page.keyboard.type(String(v.text), { delay: fast ? 0 : v.delay ?? cfg.pace.type });
         if (lit) await spotOff();
         break;
@@ -456,19 +514,79 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         const p = await pointOf(value.target, value);
         const lit = await spot(p.box, hl);
         await moveTo(p.x, p.y, value.ms ?? cfg.pace.cursor);
-        clicks.push(now());
-        await page.evaluate(([x, y]) => document.dispatchEvent(new PointerEvent('pointerdown', { clientX: x, clientY: y, bubbles: true })), [p.x, p.y]);
-        await sleep(250);
         const l = locate(page, value.target), want = String(value.option);
         const options = await l.evaluate((s) => [...(s.options ?? [])].map((o) => ({ text: o.text.trim(), value: o.value })));
-        const hit = options.find((o) => o.text === want) ?? options.find((o) => o.value === want) ?? options.find((o) => o.text.toLowerCase().includes(want.toLowerCase()));
-        if (!hit) throw new Error(`no option "${want}" in that dropdown — options: ${options.map((o) => `"${o.text}"`).join(', ')}`);
-        await l.selectOption({ value: hit.value });
+        const k = [(o) => o.text === want, (o) => o.value === want, (o) => o.text.toLowerCase().includes(want.toLowerCase())].map((f) => options.findIndex(f)).find((i) => i >= 0);
+        if (k == null) throw new Error(`no option "${want}" in that dropdown — options: ${options.map((o) => `"${o.text}"`).join(', ')}`);
+        // click it open (a drawn menu, since the real one never shows on video), move to the option, pick it
+        await press();
+        if (!fast && options.length <= 14) {
+          const at = await page.evaluate(([r, items, i]) => window.__demoMenu(r, items, i), [p.box, options.map((o) => o.text), k]);
+          await sleep(350);
+          await moveTo(at.x, at.y, Math.min(900, cfg.pace.cursor));
+          await page.evaluate((i) => window.__demoMenuHover(i), k);
+          await sleep(250);
+          clicks.push(now());
+          await sleep(120);
+          await page.evaluate(() => window.__demoMenuClose());
+        }
+        await page.keyboard.press('Escape').catch(() => {}); // in case the click opened the real one
+        await l.selectOption({ value: options[k].value });
         if (lit) { await sleep(300); await spotOff(); }
         await settle();
         await beat();
         break;
       }
+      case 'paste': {
+        // paste: { target: <field>, text: "..." } or paste: "..." (into whatever has focus) — the text arrives
+        // at once, the way a real paste does, with a ⌘V / Ctrl+V badge; real paste events, so editors that
+        // reformat on paste (code editors, rich text) behave as they would for a user
+        const v = typeof value === 'object' ? value : { text: value };
+        if (v.text == null) throw new Error('paste needs text: paste: "..." or paste: { target: <field>, text: "..." }');
+        let lit = false;
+        if (v.target) {
+          const p = await pointOf(v.target, v);
+          lit = await spot(p.box, hl);
+          await moveTo(p.x, p.y, v.ms ?? cfg.pace.cursor * 0.85);
+          await press();
+        }
+        const text = String(v.text);
+        const before = await page.evaluate(() => (document.activeElement?.value ?? document.activeElement?.textContent ?? '').length).catch(() => 0);
+        const copied = await page.evaluate((t) => navigator.clipboard.writeText(t).then(() => true, () => false), text).catch(() => false);
+        if (!fast) await page.evaluate((l) => window.__demoKeys(l), process.platform === 'darwin' ? '⌘ V' : 'Ctrl V').catch(() => {});
+        if (copied) await page.keyboard.press('ControlOrMeta+V');
+        await sleep(200);
+        const after = await page.evaluate(() => (document.activeElement?.value ?? document.activeElement?.textContent ?? '').length).catch(() => 0);
+        if (!copied || after === before) await page.keyboard.insertText(text); // no clipboard access: insert it in one go
+        if (lit) await spotOff();
+        await settle();
+        await beat();
+        break;
+      }
+      case 'slide': {
+        // slide: { target: <slider>, to: 0.2 } — drag a slider to a position along its track (0 = start,
+        // 1 = end), found from the element instead of pixel positions that break when the layout moves
+        if (!value?.target || typeof value?.to !== 'number') throw new Error('slide needs { target: <slider>, to: 0..1 }');
+        const p = await pointOf(value.target, value);
+        const b = p.box;
+        const from = await locate(page, value.target).evaluate((el) => {
+          const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
+          if (r) return (Number(r.value) - Number(r.min || 0)) / ((Number(r.max || 100) - Number(r.min || 0)) || 1);
+          const now = Number(el.getAttribute('aria-valuenow')), lo = Number(el.getAttribute('aria-valuemin') ?? 0), hi = Number(el.getAttribute('aria-valuemax') ?? 100);
+          return Number.isFinite(now) ? (now - lo) / ((hi - lo) || 1) : 0.5;
+        }).catch(() => 0.5);
+        const x0 = b.x + b.width * from, x1 = b.x + b.width * Math.max(0, Math.min(1, value.to)), y = b.y + b.height / 2;
+        await moveTo(x0, y, value.ms ?? cfg.pace.cursor);
+        await sleep(120);
+        clicks.push(now());
+        await page.mouse.down();
+        await moveTo(x1, y, value.dragMs ?? 900);
+        await sleep(120);
+        await page.mouse.up();
+        await settle();
+        await beat();
+        break;
+      }
       case 'mark': {
         // mark: "a phrase" | { text: "a phrase" } (a text range, even inside a paragraph) | any target
         // (e.g. a table row: { css: "tr:nth-child(3)" }) → highlighter sweep, kept until the step ends
@@ -638,7 +756,8 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await runAll(s.actions, `step ${i + 1}`);
     const end = now(); // before clearing: a step that is held for its narration keeps its marks
     await spotOff();
-    await page.evaluate(() => { window.__demoUnmark(); window.__demoUnnote(); }).catch(() => {});
+    // docs clips start where the step starts: clear at once, so no fading callout leaks into the next clip
+    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, cfg.clips.length > 0).catch(() => {});
     let zoomBox = null;
     if (s.zoom?.target) {
       if (isPoint(s.zoom.target)) {
@@ -658,7 +777,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   await cdp.send('Page.stopScreencast');
   await browser.close();
 
-  const timeline = { frames, steps, clicks, navs, scale: cfg.scale };
+  const timeline = { frames, steps, clicks, navs, gotos, scale: cfg.scale };
   fs.writeFileSync(path.join(cfg.work, 'timeline.json'), JSON.stringify(timeline, null, 1));
   log(`recorded ${frames.length} frames`);
   return timeline;

package/src/setup.mjs

@@ -1,6 +1,8 @@
-// `storyshot setup cursor|claude`: wire Storyshot into a coding agent for this project —
+// `storyshot setup <agent>`: wire Storyshot into a coding agent for this project —
 // the MCP server config plus the playbook as an Agent Skill (both read SKILL.md).
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -38,9 +40,59 @@ function mergeMcp(file) {
   return file;
 }
 
+// one shared copy of the playbook for agents that read instruction files rather than skills folders
+function sharedSkill(dir, skill) {
+  const dest = path.join(dir, '.agents', 'skills', 'storyshot', 'SKILL.md');
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, skill);
+  return dest;
+}
+const pointer = () => ['## Videos of this web app (Storyshot)', '',
+  'When asked for a demo or promo video, a tutorial or onboarding video, a lesson, or GIFs for docs of a website or web app,',
+  'read `.agents/skills/storyshot/SKILL.md` first and follow it. Use the `storyshot` MCP tools when they are available;',
+  `otherwise run the CLI: \`${cliCommand()} <command>\` (\`${cliCommand()} guide\` prints the playbook and storyboard reference).`].join('\n');
+// add (or refresh) our section in a shared instructions file, leaving the rest of the file alone
+function upsertBlock(file, body) {
+  const block = `<!-- storyshot:start -->\n${body}\n<!-- storyshot:end -->`;
+  const re = /<!-- storyshot:start -->[\s\S]*?<!-- storyshot:end -->/;
+  const cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, re.test(cur) ? cur.replace(re, block) : `${cur}${cur && !cur.endsWith('\n') ? '\n\n' : cur ? '\n' : ''}${block}\n`);
+  return file;
+}
+// a rules file we own outright
+function writeRule(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return file;
+}
+function mergeJson(file, key, entry) {
+  let json = {};
+  if (fs.existsSync(file)) {
+    try { json = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { throw new Error(`${file} is not valid JSON — fix or remove it first`); }
+  }
+  json[key] = { ...(json[key] ?? {}), storyshot: entry };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(json, null, 2)}\n`);
+  return file;
+}
+// Cline keeps MCP servers in its extension storage, per editor (VS Code, Cursor, Windsurf…)
+function clineSettings() {
+  const home = os.homedir();
+  const base = process.platform === 'darwin' ? path.join(home, 'Library', 'Application Support')
+    : process.platform === 'win32' ? (process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming')) : path.join(home, '.config');
+  return ['Code', 'Code - Insiders', 'Cursor', 'Windsurf', 'VSCodium']
+    .map((ed) => path.join(base, ed, 'User', 'globalStorage', 'saoudrizwan.claude-dev'))
+    .filter((d) => fs.existsSync(d))
+    .map((d) => path.join(d, 'settings', 'cline_mcp_settings.json'));
+}
+
+export const TARGETS = ['cursor', 'claude', 'codex', 'gemini', 'vscode', 'windsurf', 'cline'];
+
 export function setup(target, dir = process.cwd()) {
   const skill = fs.readFileSync(path.join(ROOT, 'skills/storyshot/SKILL.md'), 'utf8');
   const written = [];
+  const server = serverCommand();
   if (target === 'cursor') {
     // Cursor loads Agent Skills from .cursor/skills/<name>/SKILL.md (same format as Claude Code)
     written.push(mergeMcp(path.join(dir, '.cursor', 'mcp.json')));
@@ -54,8 +106,35 @@ export function setup(target, dir = process.cwd()) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.writeFileSync(dest, skill);
     written.push(dest);
+  } else if (target === 'codex') {
+    // Codex reads AGENTS.md on every task and keeps MCP servers in ~/.codex/config.toml (per user).
+    written.push(sharedSkill(dir, skill), upsertBlock(path.join(dir, 'AGENTS.md'), `${pointer()}\n\nStoryshot launches a browser (Chromium) and ffmpeg. Codex's default sandbox blocks the browser: when a Storyshot\ncommand or tool needs it, ask the user to approve running it outside the sandbox. Never work around a blocked browser\nby faking the video.`));
+    try {
+      execFileSync('codex', ['mcp', 'add', 'storyshot', '--', server.command, ...server.args], { stdio: 'ignore' });
+      written.push(`${process.env.CODEX_HOME ?? '~/.codex'}/config.toml (codex mcp add storyshot)`);
+    } catch {
+      written.push(`(codex CLI not found: add the MCP server yourself with \`codex mcp add storyshot -- ${[server.command, ...server.args].join(' ')}\`)`);
+    }
+  } else if (target === 'gemini') {
+    // Gemini CLI: project settings in .gemini/settings.json, project context in GEMINI.md
+    written.push(sharedSkill(dir, skill), mergeJson(path.join(dir, '.gemini', 'settings.json'), 'mcpServers', server), upsertBlock(path.join(dir, 'GEMINI.md'), pointer()));
+  } else if (target === 'vscode') {
+    // VS Code (GitHub Copilot agent mode): workspace MCP servers in .vscode/mcp.json, instructions in .github/copilot-instructions.md
+    written.push(sharedSkill(dir, skill), mergeJson(path.join(dir, '.vscode', 'mcp.json'), 'servers', { type: 'stdio', ...server }),
+      upsertBlock(path.join(dir, '.github', 'copilot-instructions.md'), pointer()));
+  } else if (target === 'windsurf') {
+    // Windsurf: workspace rules in .windsurf/rules/, MCP servers only per user in ~/.codeium/windsurf/mcp_config.json
+    written.push(sharedSkill(dir, skill), writeRule(path.join(dir, '.windsurf', 'rules', 'storyshot.md'),
+      `---\ntrigger: model_decision\ndescription: Making demo, promo, tutorial, lesson or docs videos/GIFs of a website or web app with Storyshot\n---\n\n${pointer()}\n`));
+    written.push(mergeJson(path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', server));
+  } else if (target === 'cline') {
+    // Cline: project rules in .clinerules/, MCP servers in the extension's settings (per user, per editor)
+    written.push(sharedSkill(dir, skill), writeRule(path.join(dir, '.clinerules', 'storyshot.md'), `${pointer()}\n`));
+    const files = clineSettings();
+    for (const f of files) written.push(mergeJson(f, 'mcpServers', { ...server, disabled: false }));
+    if (!files.length) written.push(`(Cline not found in VS Code, Cursor or Windsurf: in Cline, open MCP Servers → Configure and add "storyshot": ${JSON.stringify(server)})`);
   } else {
-    throw new Error('usage: storyshot setup cursor | claude');
+    throw new Error(`usage: storyshot setup ${TARGETS.join(' | ')}`);
   }
   const gi = ignoreCache(dir);
   if (gi) written.push(`${gi} (added .storyshot/)`);