storyshot 0.3.1 → 0.4.1

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. |
 
@@ -228,13 +252,18 @@ voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceo
 storageState: auth.json                         # optional Playwright login state
 ignoreHTTPSErrors: true                         # internal site with a self-signed HTTPS certificate (plain http:// needs nothing)
 captionPosition: bottom                         # or top; can also be set per step. A caption that would cover a step's click target or zoom subject moves to the other side automatically
+captions: true                                  # false keeps caption pills off the video (chapters and SRT still use them), e.g. with subtitles: burn
 purpose: pitch                                  # pitch | tutorial | course | docs (sets the defaults below)
 highlight: false                                # spotlight targets before click/type (per step or per action too)
 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
+lang: es                                        # language of built-in labels ("Pause and think", chapter "Introduction", "Downloaded"): en, zh, es, pt, fr, de, ja; default: zh if the steps contain Chinese, else en
+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>, window, title, icon }
+                                                # window: app draws an installed app's window (its icon and name in the title bar, no address bar) for a PWA or desktop web app; title and icon come from the page's web app manifest unless given
 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
@@ -273,8 +302,7 @@ end_card:
   logo: { alt: Company logo }                         # captured from the page, or a path to an image
   title: Acme
   subtitle: Ship **faster**
-  cta: Start free at acme.com
-  duration: 1.0
+  cta: Start free at acme.com                         # duration: auto (default) fits the say line, bullets and cta, at least 2.5 s
 ```
 
 Steps that share a caption keep it on screen across both steps.
@@ -293,8 +321,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 +334,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.1",
   "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,
@@ -185,10 +193,12 @@ Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
   - `pitch`: 1.5–3 s per step (`duration:`), so the viewer gets one beat per
-    shot; the number of shots comes from the story, plus a 1–1.5 s `end_card`. Typical shape: `intro` → hero → 2–4
+    shot; the number of shots comes from the story, plus an `end_card` held long enough to read its call to action (at least 2.5 s; leave its `duration` out). Typical shape: `intro` → hero → 2–4
     steps of the core flow ending on a visible result → pricing or CTA → end
     card. Promos sit in a browser window on a backdrop (`frame: false` turns
-    that off).
+    that off). For an app people install (a PWA, or a desktop app built on
+    web tech), use `frame: { window: app }`: the title bar shows the app's
+    icon and name, not an address bar.
   - Other purposes: leave out `duration`. `auto` times each step to its
     narration and plays motion in real time.
 - **Captions ≤ 7 words.** `**bold**` the payoff ("Every text box is
@@ -219,8 +229,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
@@ -248,8 +259,13 @@ the page. Test new targets with `inspect_page` + `after_step`, which is much
 faster than a failed render.
 
 Notes:
-- The end card's duration fits its `say:` line automatically; leave out
-  `duration` there.
+- The end card's duration fits its `say:` line, bullets and `cta`
+  automatically (never under 2.5 s); leave out `duration` there.
+- Compose warns about **dead air**: 3 s or more where nothing moves and
+  nothing is said. Shorten the wait or pause, hide the load in a `hidden`
+  step, or narrate it. Keep `intro` cards to 6–8 s.
+- With `subtitles: burn`, the top caption pills can repeat the subtitles;
+  `captions: false` keeps them off the video (chapters and SRT still use them).
 - `.storyshot/` next to the YAML is a cache of recordings, screenshots and
   voice lines. Add it to `.gitignore`.
 

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;
@@ -177,8 +183,10 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   const wavFile = path.join(cfg.work, 'soundtrack.wav');
   fs.writeFileSync(wavFile, wav);
 
+  // loudnorm alone lets peaks through after AAC encoding; the limiter keeps true peaks near −2 dB,
+  // so re-encoding by video sites doesn't clip
   execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', silentVideo, '-i', wavFile,
-    '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-af', 'loudnorm=I=-14:TP=-1.5:LRA=11', '-ar', `${SR}`, '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', cfg.out]);
+    '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-af', `loudnorm=I=-14:TP=-1.5:LRA=11,aresample=${SR},alimiter=limit=0.7:level=false:attack=1:release=50`, '-ar', `${SR}`, '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', cfg.out]);
   log(`soundtrack: ${cfg.music ? (cfg.music.file ? 'music file' : `synth ${cfg.music.bpm} bpm`) : 'no music'}, ${events.clicks.length} clicks, ${events.whooshes.length} whooshes` +
     (cfg.voice ? `, ${events.voice.length} narration lines (${cfg.voice.provider}/${cfg.voice.voice})` : ''));
   return { out: cfg.out, warnings, narration };

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,17 +4,17 @@ 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',
-  'scrollOffset', 'captionPosition', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
+const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'lang', 'colorScheme',
+  'scrollOffset', 'captionPosition', 'captions', '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'];
 const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'bullets', 'image', 'think'];
 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', 'window', 'title', 'icon'], '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') {