storyshot 0.1.3 → 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,13 +15,66 @@ 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)
+and [demo-dev](https://www.npmjs.com/package/demo-dev) each made a promo of this
+repo's page, with the same storyline and free local voices only. The grid
+below is muted; open the full videos to hear them.
+
+https://github.com/user-attachments/assets/3d8175ab-ba15-4b61-961d-481e57566e7a
+
+<details>
+<summary>The three full videos, with sound</summary>
+
+**Storyshot**
+
+https://github.com/user-attachments/assets/22987356-2a74-4e28-9a14-a1b01d04f932
+
+**promo-video-recorder**
+
+https://github.com/user-attachments/assets/e5eb86e5-e69c-403b-ad6c-c4499592307a
+
+**demo-dev**
+
+https://github.com/user-attachments/assets/8d3370ca-7a90-48af-b1c9-88189763e95d
+
+</details>
+
+How each one was made, what we saw, and the caveats:
+[docs/comparison](docs/comparison/README.md).
+
 ## 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
@@ -32,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`
@@ -51,8 +104,8 @@ macOS, Linux and Windows.
 
    ```
    Here's the plan. Reply "ok", or change any line:
-   1. Type: pitch: a 15–30 s promo
-   2. Length: about 15 s, 6 shots
+   1. Type: pitch: a promo for the landing page
+   2. Length: about 20 s, 6 shots
    3. Flow: hero → Examples → Try It → AI result → pricing → end card
    4. Voice: none (other options: free local English voice; ElevenLabs, key found in .env)
    5. Music: upbeat · Captions: English · Subtitle file (.srt): no
@@ -82,10 +135,13 @@ After your next release, re-render it and you have an up-to-date video.
 
 | ask for | type (`purpose`) | you get |
 |---|---|---|
-| a promo / launch / landing-page clip | `pitch` | 15–30 s, music, captions, tightly cut |
-| a how-to or onboarding video | `tutorial` | narrated, a spotlight on each click, numbered steps, soft music, `.srt` + chapters |
-| a lesson or explainer | `course` | narrated and explains the *why*, no music, `.srt` + chapters |
-| help-center snippets | `docs` | silent, one GIF per step |
+| a promo / launch / landing-page clip | `pitch` | short and tightly cut: intro card, the app in a browser frame, music, captions |
+| a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters |
+| a lesson or explainer | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
+
+Length follows the purpose and the content, not a target: a promo is as short as
+its message, a tutorial as long as the workflow takes to explain.
 
 Any type can also be vertical (9:16) or in another language.
 
@@ -137,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
@@ -160,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. |
 
@@ -199,11 +255,21 @@ captionPosition: bottom                         # or top; can also be set per st
 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)
+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 }
+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: one file per step in <out>-steps/
+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
 
+intro:                                          # optional title card before the recording (same fields as end_card)
+  title: Acme
+  subtitle: Ship **faster**
+  say: Meet Acme.
+
 setup:                                          # runs before recording starts
   - dismiss: { role: button, name: Accept cookies }
 
@@ -220,6 +286,11 @@ steps:
     sfx: riser                                        # rising sound + chime (or `chime`)
     actions:
       - waitFor: { text: Done, timeout: 120000 }      # waiting is compressed automatically
+  - card: { kicker: Part 2, title: Read the results }  # a section card before this step (tutorials); becomes a chapter
+    caption: The hits table
+    say: Each row is a protein similar to yours.
+    actions:
+      - mark: { css: "tbody tr:nth-child(1)" }
   - hidden: true                                      # cut, not shown in the video
     actions:
       - goto: /
@@ -248,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) |
@@ -260,6 +332,13 @@ 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
 drag move). `highlight: true/false` on `click`, `type` or `move` overrides the
@@ -326,17 +405,28 @@ changed. Write names the way they should be pronounced (`say: P X Genius.`),
 and spell out prices (`eleven ninety-nine`) in `pronounce` or in the line itself. At normal pace that comes to
 about 2.5 words per second, or roughly 35 words for a 15 s video.
 
-### End card
+### Intro and end card
 
-Every field is optional; leave out `end_card` entirely for no end card.
+Every field is optional; leave out `intro` / `end_card` for none. A step's
+`card` takes the same fields and plays before that step (section titles in
+tutorials). Both are short
+animations: the logo pops in, the title rises, the `**bold**` highlight sweeps,
+and a `cta` that is a command (`npx …`, `npm …`, `pip …`, `brew …`, `curl …`)
+types itself out in a terminal pill. `init` writes an `intro` for promos;
+tutorials and lessons can add one (e.g. "How to export a report"), docs GIFs
+usually shouldn't.
 
 | field | meaning |
 |---|---|
 | `logo` | A target on the page (captured as an image, e.g. `{ alt: Acme logo }`) or a path to an image file. If the logo image already contains the wordmark, leave out `title`. |
 | `title` | Large product name next to the logo. |
+| `kicker` | Small label above the title, e.g. `Part 2`. |
 | `subtitle` | One line; `**bold**` gets an accent highlight. |
+| `image` | A picture or diagram file (png, jpg, svg) under the title: concept cards in lessons. |
+| `think` | Seconds to pause after the card's `say` (a question card), with a "Pause and think" countdown. The next step shows the answer. |
+| `bullets` | A numbered list that appears one item at a time: "what you'll learn" on an intro, a recap on the end card. The card stays up long enough to read it. |
 | `cta` | Dark call-to-action pill, e.g. `Start free at acme.com`. |
-| `duration` | Seconds (default 1.0). |
+| `duration` | Seconds. Default: fits the `say` line, else 1.0 (end card) or 2.2 (intro). |
 | `say` | Voiceover line played over the end card. |
 
 ## License

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.1.3",
+  "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
@@ -55,9 +61,9 @@ everything.
 
    ```
    Here's the plan. Reply "ok", or change any line:
-   1. Type: pitch: a 15–30 s promo (other options: tutorial = narrated how-to;
-      course = narrated lesson; docs = silent step-by-step GIFs)
-   2. Length: about 15 s, 6 shots
+   1. Type: pitch: a promo for the landing page (other options: tutorial =
+      narrated how-to; course = narrated lesson; docs = silent step-by-step GIFs)
+   2. Length: about 20 s, 6 shots (it follows from the flow below)
    3. Flow: hero → Examples → Try It → AI result → pricing → end card
    4. Voice: none (other options: free local English voice; ElevenLabs, best
       quality and Chinese support, key found in .env)
@@ -67,14 +73,16 @@ everything.
       window for you to log in once; please use a demo account)
    ```
 
-   Defaults by type (propose these unless the request says otherwise):
+   Defaults by type (propose these unless the request says otherwise). There
+   is no target length: it follows from the purpose and the content. Estimate
+   it from the flow and say it in the plan, so the user can react.
 
-   | type | length | voice | music | on screen / files |
+   | type | length comes from | voice | music | on screen / files |
    |---|---|---|---|---|
-   | `pitch` | 15 s (or 30 s), 5–7 shots | optional | upbeat | captions |
-   | `tutorial` | 45–90 s, 6–12 steps | yes | soft | step numbers, spotlight, .srt, chapters |
-   | `course` | 1–3 min | yes | none | spotlight, .srt, chapters |
-   | `docs` | one GIF per step | none | none | step numbers, spotlight, GIFs |
+   | `pitch` | where it's shown and its one message: a landing-page loop or social clip is a handful of shots; a launch video can tell a longer story | optional | upbeat | captions, intro, frame |
+   | `tutorial` | every step of the workflow, each explained, plus a second example; as long as that takes | yes | soft | step numbers, spotlight, camera follows, part cards, recap, .srt, chapters |
+   | `course` | the concepts to teach: each idea, shown in the app, checked with a question | yes | none | spotlight, camera follows, concept and question cards, recap, .srt, chapters |
+   | `docs` | one clip per step, each just long enough to see its result | none | none | step numbers, spotlight, cropped GIFs + PNGs, README.md article |
 
    Captions match the site's language. `kokoro` (free, local) speaks English
    only; for other languages, use ElevenLabs.
@@ -121,12 +129,74 @@ everything.
 
 ## 3. Write the storyboard
 
-Rules of thumb from real renders:
+### Tutorials and lessons are not ads
+
+A promo shows as much as possible, fast. A tutorial does the opposite: the
+viewer has to be able to **do it themselves** afterwards, often in a technical
+or scientific tool they have never seen. Storyshot paces `tutorial` and
+`course` slowly by default (`pace: slow`: slower cursor and typing, a beat
+after every click, a hold after every narration line, slower voice, real
+progress shown for waits) and the camera follows the action (`follow`), so
+small controls are readable. Your job is the structure:
+
+- **Start with the goal**: an `intro` with `bullets` saying what the viewer
+  will be able to do ("Run a BLAST search", "Read the hits table", "Judge a
+  match by E-value"), and what they need beforehand.
+- **Split the workflow into parts**, each opened by a `card`
+  (`card: { kicker: Part 2, title: Read the results }` on its first step).
+  Cards become the YouTube chapters.
+- **One action per step.** Each click, field or choice is its own step with
+  its own `say:` explaining **what** it does and **why this value**. Never
+  "fill in the form and submit" in one line. `check` warns when a tutorial
+  step does more than two things.
+- **Show, then explain the result.** After an action that produces output
+  (a results table, a number, a plot, a status), add a step that only looks:
+  `mark` the value or row you're talking about (`mark: "E value"`,
+  `mark: { css: "tbody tr:nth-child(1)" }`), and say what it means and how to
+  judge it ("an E-value this small means the match is not by chance").
+- **Label the controls that matter.** `note: { target: …, text: "FASTA or accession" }`
+  puts a short callout with an arrow next to a field, button or column. Use it for
+  the one thing a newcomer would get wrong, not for everything.
+- **Dropdowns:** `select: { target: …, option: "…" }` (inspect lists the
+  options). Say why this option.
+- **Then a different example.** Run the workflow again with a second input
+  that behaves differently (another sequence, sample, parameter), and point
+  out what changed and why. Comparison is what makes the concept stick.
+  A short `card` ("Now a second example") separates it.
+- **Lessons (`course`) explain the why.** Use concept cards for ideas that
+  aren't on screen (`card: { kicker: Concept, title: …, bullets: […], image:
+  diagram.svg }`), and question cards before a reveal (`card: { kicker:
+  Question, title: "Which hit is the real homolog?", think: 3 }`, then the
+  next step marks the answer).
+- **Docs GIFs (`docs`)** become a help-center article: each step's clip is
+  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. 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,
+  E-values) before the app produces them. Write the result steps with
+  general narration, render once, read the actual values from the preview
+  frames, then rewrite those `say:`/`note`/caption lines with the real
+  numbers and run `compose` only (no re-recording, no new jobs).
+- **Waiting is part of the lesson.** Long computations are still compressed,
+  but say what is happening ("BLAST is now comparing your sequence against
+  the database; this usually takes under a minute").
+- Length follows the content. Don't cut explanation to hit a length, and
+  don't pad: if a part is long, split it into more parts rather than
+  speeding it up.
+
+Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
-  - `pitch`: 1.5–3 s per step (`duration:`). A 15 s video is 5–7 visible
-    steps plus a 1–1.5 s `end_card`. Typical shape: hero → 2–4 steps of the
-    core flow ending on a visible result → pricing or CTA → end card.
+  - `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
+    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).
   - 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
@@ -148,9 +218,18 @@ Rules of thumb from real renders:
   and `press: "^"` send single keys. In `tutorial`/`course`, the spotlight
   highlights each click target automatically; add `highlight: true` to a
   `move` to point at something without clicking it.
+- **Point at what the narration names.** `mark: "the exact phrase"` sweeps a
+  highlighter over words on the page (or `mark: <target>` boxes a table row,
+  card or code line) while the voice says them. On text-heavy pages a mark
+  plus a zoom tells the viewer where to look.
+- **Static pages (a landing page, docs, a README) have nothing to click.**
+  Don't make a slideshow of scrolls: open with an `intro` (the promise),
+  `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

@@ -3,15 +3,16 @@ import { record } from './record.mjs';
 import { compose } from './compose.mjs';
 import { soundtrack } from './audio.mjs';
 import { measureVoice } from './voice.mjs';
-import { writeOutputs } from './outputs.mjs';
+import { writeOutputs, burnSubtitles } from './outputs.mjs';
 
 export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const t0 = Date.now();
   if (mode !== 'compose') await record(cfg, { log });
   if (mode === 'record') return { warnings: [] };
   const voiceLens = await measureVoice(cfg, { log });
-  const { silent, events, preview, warnings, captions, 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 });
-  const extras = await writeOutputs(cfg, { captions, segs, narration: audio.narration, total: events.total }, { log });
+  if (cfg.subtitles === 'burn') burnSubtitles(cfg, audio.narration ?? [], { 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,16 +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', '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'];
+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'];
+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'];
+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', hide: 'any', slide: 'slide', paste: 'type',
 };
 
 const dist = (a, b) => {
@@ -68,8 +69,23 @@ export function check(file, { draft = false } = {}) {
     if (s.hidden && (s.caption || s.say)) warnings.push(`${where}: hidden steps are cut from the video, so caption/say are ignored`);
     if (!Array.isArray(s.actions ?? [])) errors.push(`${where}: actions must be a list`);
     for (const [j, a] of (s.actions ?? []).entries()) checkAction(a, `${where} action ${j + 1}`);
+    if (s.card) unknown(s.card, END, `${where} card`);
+    // 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', '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]);
+      if (s.say && kinds.some((k) => k === 'scroll' || k === 'scrollTo') && !kinds.some((k) => ['mark', 'note', 'click', 'type', 'select', 'move', 'hover'].includes(k)) && !s.zoom) {
+        warnings.push(`${where}: scrolls and talks but points at nothing — on a dense page the viewer can't tell what you mean; \`mark\` or \`note\` the row or value the narration is about (the camera then zooms to it)`);
+      }
+    }
   }
   if (raw.end_card) unknown(raw.end_card, END, 'end_card');
+  if (raw.intro) unknown(raw.intro, END, 'intro');
+  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`);
 
@@ -85,9 +101,24 @@ export function check(file, { draft = false } = {}) {
     if (type === 'number' && typeof v !== 'number') errors.push(`${where}: ${kind} takes milliseconds, e.g. "${kind}: 800"`);
     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') {
@@ -104,7 +135,7 @@ export function check(file, { draft = false } = {}) {
   let summary = '';
   if (cfg) {
     const visible = cfg.steps.filter((s) => !s.hidden);
-    const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0);
+    const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0) + (cfg.intro?.say ? 1 : 0);
     if (cfg.voice && !says) warnings.push('voice is set but no step has a `say:` line');
     if (!cfg.voice && says) warnings.push('steps have `say:` lines but there is no `voice:` block, so they will not be spoken');
     if (!draft && cfg.voice && ['elevenlabs', 'openai'].includes(cfg.voice.provider)) {
@@ -126,7 +157,7 @@ export function check(file, { draft = false } = {}) {
     const fixed = visible.filter((s) => s.duration !== 'auto').reduce((a, s) => a + s.duration, 0);
     const auto = visible.filter((s) => s.duration === 'auto').length;
     const ec = cfg.endCard ? (cfg.endCard.duration === 'auto' ? null : cfg.endCard.duration) : 0;
-    const length = auto ? `${fixed ? `${fixed.toFixed(1)}s fixed + ` : ''}${auto} steps timed to narration${cfg.endCard ? ' + end card' : ''}`
+    const length = auto ? `${fixed ? `${fixed.toFixed(1)}s fixed + ` : ''}${auto} steps timed to narration${cfg.endCard ? ' + end card' : ''}${cfg.intro ? ' + intro' : ''}`
       : `${fixed.toFixed(1)}s of steps${cfg.endCard ? ` + ${ec ?? 'auto'}s end card` : ''}${ec != null ? ` = ${(fixed + ec).toFixed(1)}s total` : ''}`;
     summary = `${cfg.name}: purpose ${cfg.purpose}, ${visible.length} visible steps, ${length}` +
       (cfg.voice ? `, voice ${cfg.voice.provider}` : '') + ` → ${cfg.out}`;