storyshot 0.10.0 → 0.11.0

package/README.md

@@ -1,19 +1,94 @@
 # Storyshot
 
-Ask your coding agent for a video of your web app, and get a polished 1080p
-MP4: a promo clip, a narrated tutorial, a lesson, or step-by-step GIFs for your
-docs.
+Ask your coding agent for a video, and get a polished 1080p MP4. Two kinds of
+film come out of one tool:
 
+- **An explainer of an idea** — no web app, no footage, nothing recorded. Every
+  scene is an animation the agent writes and times to the narration: a
+  mechanism, a diagram that builds, a number that lands. Chinese or English.
+  *This is what most people come for.*
+- **A video of your web app** — a promo, a narrated tutorial, a lesson, or
+  step-by-step GIFs for your docs. A real browser clicks through your site, and
+  the recording gets a smooth cursor, automatic zoom, captions, an optional
+  voiceover, music and an end card.
+
+The agent plans, writes and fixes the storyboard. Storyshot does the rendering,
+and the same storyboard always renders the same video.
+
+## Install it into your coding agent
+
+**The skill is the front door.** You do not learn a CLI — your agent does.
+
+Open your project in your coding agent (Claude Code, Cursor, Codex, Gemini CLI,
+Copilot in VS Code, Windsurf, Cline) and paste this one line into its chat, with
+your agent's name in place of `claude`:
+
+> Set up Storyshot in this project: run `npx -y storyshot setup claude` and do everything it says.
+
+Agent names: `claude` · `cursor` · `codex` · `gemini` · `vscode` · `windsurf` · `cline`.
+
+That one command installs **the Storyshot skill** into your agent, writes the MCP
+server config, adds `.storyshot/` to `.gitignore`, and downloads the browser it
+needs. The skill is what teaches your agent the whole workflow — how to plan a
+film, write the scenes, read the render back and fix it — so from the next chat
+on you can just ask for a video in plain words.
+
+Restart or reload your agent when `setup` says to. Then:
+
+> *「做一个视频，讲清楚热泵为什么能把一份电变成三份热」*
+>
+> *"make an explainer about how a heat pump moves three units of heat per unit of electricity"*
+>
 > *"make a 15 s promo video of https://myapp.com"*
+>
+> *"make a narrated tutorial showing how to export a report"*
 
-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
-second or two on screen.
+or type `/storyshot`.
 
-The agent plans, writes and fixes the storyboard. Storyshot does the
-recording and editing, and the same storyboard always renders the same video.
+`npx storyshot doctor` re-checks everything at any time. Storyshot runs on
+macOS, Linux and Windows. Needs Node 18+ and ffmpeg (setup prints the exact
+install command for your OS if it is missing).
+
+### Explainers, in one paragraph
+
+An explainer has no `url` and records nothing. You ask for a subject; the agent
+writes a storyboard of **scenes**, and each scene is an HTML animation it draws
+and times to the voice, phrase by phrase. It renders a still of every scene,
+looks at it, and fixes what is wrong before it ever renders video. Free local
+voices in English and Chinese, synth music, subtitles and chapters — no API key
+and no per-video cost. Start here:
+[the explainers in the gallery](https://boheling.github.io/storyshot-gallery/#explainer),
+and the ["Scenes and explainers" playbook](#for-agents-tools-and-playbook).
+
+## What `setup` writes, per agent
+
+| 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.
+
+**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
+  `.storyshot/` to `.gitignore`, and downloads the browser it needs.
+- If ffmpeg is missing, setup prints the exact install command for your OS
+  (`brew install ffmpeg`, `winget install --id Gyan.FFmpeg -e`,
+  `sudo apt-get install -y ffmpeg`). The agent runs it after you approve.
+- The agent reads the skill and starts on your video in the same chat, using
+  the CLI.
+
+From the next chat on, the agent uses the Storyshot MCP tools automatically.
 
 https://github.com/user-attachments/assets/05dd9a73-2edc-46af-9b2b-a8e33c7005b4
 
@@ -57,51 +132,6 @@ https://github.com/user-attachments/assets/8d3370ca-7a90-48af-b1c9-88189763e95d
 How each one was made, what we saw, and the caveats:
 [docs/comparison](docs/comparison/README.md).
 
-## Quick start
-
-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.
-
-**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
-  `.storyshot/` to `.gitignore`, and downloads the browser it needs.
-- If ffmpeg is missing, setup prints the exact install command for your OS
-  (`brew install ffmpeg`, `winget install --id Gyan.FFmpeg -e`,
-  `sudo apt-get install -y ffmpeg`). The agent runs it after you approve.
-- The agent reads the skill and starts on your video in the same chat, using
-  the CLI.
-
-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`
-- *"make a narrated tutorial showing how to export a report"*
-- *"make a lesson video explaining how the AI editor works"*
-- *"make docs GIFs for the onboarding flow"*
-
-`npx storyshot doctor` re-checks everything at any time. Storyshot runs on
-macOS, Linux and Windows.
-
 ## What happens when you ask
 
 1. **The agent looks at your site** (about 5 s). It reads the page, and checks
@@ -142,8 +172,8 @@ 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` | 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 | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| 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. `check` holds the narration to a teaching pace too — one job per step, a budget per line, no bolded payoffs — so a slow film doesn't still read as a pitch |
+| a lesson | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters. `check` holds it to the tutorial's teaching pace, and to a lesson's own shape: a card names one idea, a question waits for an answer and its step marks it |
 | help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
 | an animated explainer of how something works | `explainer` | no web app: every step is a **scene**, an animation the agent writes and times to the narration (a mechanism, a diagram that grows, a number); calm music, subtitles, chapters |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Ask your coding agent for a video of your web app: promo clips, narrated tutorials, lessons and docs GIFs from a YAML storyboard.",
   "author": "boheling <boheling@gmail.com>",
   "repository": {

package/skills/storyshot/SKILL.md

@@ -175,7 +175,9 @@ 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:
+small controls are readable. What the tool cannot set for you is the structure
+and the voice. The structure first; "The teaching voice" below is the half that
+decides whether a slow film still sounds like a sales pitch:
 
 - **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
@@ -245,6 +247,86 @@ small controls are readable. Your job is the structure:
   don't pad: if a part is long, split it into more parts rather than
   speeding it up.
 
+#### The teaching voice
+
+`pace: slow` buys time on screen: slower cursor and typing, a beat after every
+click, a hold after every line. It cannot buy time *inside* a sentence. A
+tutorial that still sounds like an ad read slowly is nearly always a writing
+problem, not a timing one — and the usual cause is density, not length.
+`check` holds a `tutorial` or a `course` to the rules below. A promo is held to
+none of them, which is the point: they are different jobs.
+
+1. **One job per step.** A step either names an idea, does an action, or reads
+   a result. Not two of those, and never three. The line that packs all three
+   is the commonest failure, and it reads fine on the page:
+
+   > "The E value is how many hits this good you would expect by pure chance in
+   > a database this size. Smaller is better, and anything below 1e-5 usually
+   > means a real relationship. Here it is 6e-106, essentially zero."
+
+   A definition, a rule of thumb and a reading, in eleven seconds. The viewer
+   is still working out what "expect by chance" means when the number arrives,
+   so they keep none of it. As three steps they keep all three.
+2. **A step's whole `say:` fits in about 35 words (55 Chinese characters).**
+   Past that, split the step.
+3. **A sentence is about 15 words (25 characters).** `check` speaks up past 18
+   (30), so 15 is what to write to, not a line to trip over. Promos are allowed
+   25; a lesson is not.
+4. **At most three figures in one line.** Nobody holds four numbers by ear. Say
+   the one that carries the point, round it out loud ("about eighty percent"),
+   and let the screen carry the exact value — which it can, because you marked
+   the cell.
+5. **Say the number, then what it means, then the rule again.** Teaching
+   repeats. A script that states each fact exactly once reads as a list of
+   facts, however plainly each one is put. The recap at the end repeats them in
+   the same words as the first time.
+6. **Silence is part of the lesson.** After a result appears, the viewer needs a
+   beat to find it on their own screen. Hold the step (`pause: 2000`) and say
+   nothing. Compose's dead-air warning knows the difference: 3 s is too long in
+   a promo, a `tutorial` or `course` is allowed 6 s, and 8 s on a step that
+   asked to hold. Resolve a dead-air warning in a lesson by saying what to look
+   at, not by cutting the beat.
+7. **A new term gets a step of its own**, the first time it appears, before any
+   number is attached to it.
+
+**A tutorial's caption is a label, not a payoff.** A promo bolds the payoff
+because a promo is selling the payoff. Here the caption says where the viewer
+is — "The E value column", "Part 2: read the results" — and the voice does the
+explaining. `Shorter protein, **larger** E value` reaches the conclusion before
+the narration gets there, which is an ad's grammar; `check` warns on `**` in a
+tutorial caption. A `note` works the same way: it labels the control it points
+at in a few words ("FASTA or accession"), it does not recommend it ("Curated,
+fast: good for learning").
+
+#### What a lesson adds
+
+A tutorial teaches the steps; a lesson (`course`) teaches the idea behind them,
+so the clicking is usually done in `hidden` steps and the film is about reading
+what is on the page. It is held to the whole teaching voice above, and to three
+things of its own. `check` warns on each.
+
+1. **A card names one idea.** A concept card's `say:` gets the same budget as a
+   step (about 35 words, 55 Chinese characters), and it is the easiest place to
+   break it, because a card feels like the place for the whole explanation:
+   definition, threshold and example. Put the name and the plain-words meaning
+   on the card. The rule and the number go in the steps after it, where the
+   page can show them and you can `mark` them.
+2. **A question card waits, and its step shows the answer.** A check has three
+   parts: the question, time to answer it (`think: 3`, at least 2), and the
+   answer marked on the page. Without the wait it is a rhetorical question,
+   which a promo asks and a lesson does not. Without the mark, a viewer who
+   guessed wrong is told so and never shown where to look. The step a question
+   card sits on is the reveal: it points at the answer first, and the reason
+   comes in the step after.
+3. **Ask at least once.** A lesson with no question is a lecture: the viewer
+   cannot tell whether they followed it. The best second question is a new case
+   the rule has to be applied to (a different search, another input), not the
+   first one asked again.
+
+The order inside each idea is the one in "Explain in an order the viewer can
+follow" below: a concrete case on screen, then the card that names it, then the
+reading, then the rule, then the question.
+
 ### Writing the narration
 
 Viewers notice three things first: lines that run together, phrasing nobody
@@ -254,7 +336,9 @@ They should sound like one person talking a friend through it.
 
 **Say it like a person.**
 - Short sentences, one idea each: about 15 words at most in English, 25
-  characters in Chinese. If you would run out of breath, split it.
+  characters in Chinese. If you would run out of breath, split it. In a
+  tutorial or lesson `check` enforces this, along with a budget for the whole
+  step — see "The teaching voice".
 - Spoken words: contractions ("you'll", "it's"), "you", present tense, active
   voice. In Chinese, 口语 rather than 书面语: "点一下这里", not "进行点击操作".
 - Use the exact labels on screen, and the same term every time (no synonyms
@@ -314,8 +398,10 @@ Rules of thumb from real renders (promos and tutorials):
     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
-  **fully editable**"). Steps with the same caption keep it on screen.
+- **Captions ≤ 7 words.** In a promo, `**bold**` the payoff ("Every text box is
+  **fully editable**"); in a tutorial or lesson a caption is a label for where
+  the viewer is, with no bold payoff (see "The teaching voice"). Steps with the
+  same caption keep it on screen.
 - **Narration (`say:`) is not a caption.** Write full spoken sentences, one
   instruction or idea per step. Use normal spelling, and put pronunciations in
   `voice.pronounce` (e.g. `pxGenius: P X Genius`, `AI: A I`) so subtitles stay
@@ -380,7 +466,9 @@ Notes:
   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.
+  step, or narrate it. A `tutorial` or `course` is allowed 6 s, and 8 s on a
+  step that asked to hold with `pause`, because a learner needs the beat.
+  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

package/src/check.mjs

@@ -9,6 +9,9 @@ import { sentences } from './voice.mjs';
 import { sceneInfo, filmGround, contrast } from './scenes.mjs';
 import path from 'node:path';
 
+const cjkLen = (s) => (s.match(/[぀-ヿ㐀-鿿가-힯]/g) ?? []).length;
+const wordLen = (s) => s.replace(/[぀-ヿ㐀-鿿가-힯]/g, ' ').split(/\s+/).filter((w) => /\w/.test(w)).length;
+
 // Phrases that mark narration as machine-written, and sentences too long to say in one breath.
 const TELLS = [
   /\bnot (?:just|only|merely) [^.,;!?]{1,40}?,? but(?: also)?\b/i, // "not just X, but Y"
@@ -28,15 +31,41 @@ export function narrationLint(text) {
   }
   let long = null;
   for (const s of sentences(t)) {
-    const cjk = (s.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length;
-    const words = s.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter((w) => /\w/.test(w)).length;
+    const cjk = cjkLen(s), words = wordLen(s);
     if (cjk > 40 && !long) long = `${cjk}-character`;
     else if (!cjk && words > 25 && !long) long = `${words}-word`;
   }
   return { tells, long };
 }
 
-const TOP = ['name', 'url', 'out', 'purpose', 'aspect', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'ground', 'lang', 'colorScheme',
+// How much one step may carry when the viewer is meant to follow along and do it themselves.
+// A promo packs; a tutorial parcels out. The skill has always asked for 15 words a sentence, but the
+// lint above only caught 25, which is a promo's budget — tutorials and lessons are held to the number
+// the skill actually says, and a step gets a budget of its own. Density is the thing nobody notices
+// while writing: three jobs in one breath (name the idea, give the rule, read the number) is what
+// makes a tutorial sound like an ad read at speed, even when every sentence is short.
+// sentenceWords/Chars is the number the skill asks for; the lint only speaks up past the slack, so
+// "about 15 words" stays a target to write to rather than a line to trip over at 16.
+export const TEACH = { words: 35, chars: 55, sentenceWords: 15, sentenceChars: 25, slackWords: 18, slackChars: 30, numbers: 3 };
+const an = (s) => `${/^(?:8|11|18|8\d|11\d|18\d)/.test(s) ? 'an' : 'a'} ${s}`;
+export function teachingLint(text) {
+  const t = String(text).replace(/\*\*/g, '');
+  const c = cjkLen(t), w = wordLen(t);
+  const heavy = c > TEACH.chars ? `${c}-character` : (!c && w > TEACH.words ? `${w}-word` : null);
+  let long = null;
+  for (const s of sentences(t)) {
+    const sc = cjkLen(s), sw = wordLen(s);
+    if (sc > TEACH.slackChars && !long) long = `${sc}-character`;
+    else if (!sc && sw > TEACH.slackWords && !long) long = `${sw}-word`;
+  }
+  // figures the viewer has to hold: a digit that starts a number, so an accession (P68871) or a
+  // version inside a word is not one, and the comma in "1,000" is part of it while the one after
+  // "105," is not. Chinese numerals are spelled out, where the character budget above is what limits them.
+  const numbers = [...new Set(t.match(/(?<![A-Za-z\d])\d(?:,?\d)*(?:\.\d+)?(?:e[-+]?\d+)?%?/gi) ?? [])];
+  return { heavy, long, numbers };
+}
+
+const TOP =['name', 'url', 'out', 'purpose', 'aspect', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'ground', 'lang', 'colorScheme',
   'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card', 'hyperframes', 'scenes'];
 const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc', 'scene'];
 const SCENE = ['file', 'title', 'lead', 'tail'];
@@ -91,6 +120,8 @@ export function check(file, { draft = false } = {}) {
     return { ok: false, errors: [`YAML syntax: ${e.message.split('\n')[0]}`], warnings, summary: '' };
   }
   unknown(raw, TOP, 'top level');
+  const sold = []; // tutorial captions written as a promo's payoff, reported together
+  let questions = 0; // question cards (a card that waits with `think`), which a lesson is expected to have
   for (const [i, a] of (raw.setup ?? []).entries()) checkAction(a, `setup action ${i + 1}`);
   for (const [i, s] of (raw.steps ?? []).entries()) {
     const where = `step ${i + 1}`;
@@ -121,8 +152,42 @@ export function check(file, { draft = false } = {}) {
       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)`);
       }
+      // A promo's caption bolds the payoff, because a promo is selling the payoff. A tutorial's caption
+      // says where the viewer is, and the narration does the explaining: bold it and the caption gets
+      // to the conclusion before the voice does, which is the grammar of an ad, not of a lesson. It is
+      // one decision rather than one mistake per step, so it is reported once.
+      if (typeof s.caption === 'string' && s.caption.includes('**')) sold.push([i + 1, s.caption]);
+      // A callout points at a control and names it. Longer than that and it is arguing for the app.
+      for (const a of (s.actions ?? [])) {
+        const n = a?.note;
+        const t = typeof n === 'string' ? n : n?.text;
+        if (t && (wordLen(t) > 8 || cjkLen(t) > 14)) warnings.push(`${where}: the note reads as a sentence ("${t}") — a callout is a label for the control it points at, a few words at most`);
+      }
+      // A question card is a check, and a check has three parts: the question, time to answer it, and
+      // the answer shown on the page. Without the wait it is a rhetorical question, which a promo asks
+      // and a lesson does not; without something marked, the viewer who guessed wrong is told they
+      // were wrong and never shown where to look.
+      const card = s.card && typeof s.card === 'object' ? s.card : null;
+      const asks = card && /question|quiz|check|问题|提问|思考|想一想|pregunta|frage/i.test(String(card.kicker ?? ''));
+      if (card && (card.think != null || asks)) {
+        questions++;
+        if (card.think == null) warnings.push(`${where} card: asks a question but does not wait for an answer — give it \`think: 3\` (seconds), so the viewer answers before the reveal`);
+        else if (!(card.think >= 2)) warnings.push(`${where} card: think: ${card.think} is too short to answer in — give the viewer at least 2 seconds, 3 to 4 for anything they have to work out`);
+        if (!s.zoom && !kinds.some((k) => ['mark', 'note', 'move', 'hover', 'click', 'slide', 'drag', 'type', 'select'].includes(k))) {
+          warnings.push(`${where}: this step answers the question card before it, but points at nothing — \`mark\` the row, value or line that is the answer, so a viewer who guessed wrong sees why`);
+        }
+      }
     }
   }
+  // A lesson that never asks is a lecture: the viewer cannot tell whether they followed it.
+  if (raw.purpose === 'course' && !questions && (raw.steps ?? []).some((s) => !s.hidden && s.say)) {
+    warnings.push('a lesson with no question card — check understanding at least once: `card: { kicker: Question, title: "…?", think: 3 }` on the step that then marks the answer');
+  }
+  if (sold.length) {
+    const ns = sold.map(([n]) => n);
+    const which = sold.length === 1 ? `step ${ns[0]}` : sold.length > 6 ? `steps ${ns[0]}–${ns.at(-1)} (${sold.length} captions)` : `steps ${ns.join(', ')}`;
+    warnings.push(`${which}: the caption bolds a payoff (${sold.slice(0, 3).map(([, c]) => `"${c}"`).join(', ')}${sold.length > 3 ? ', …' : ''}) — that is a promo's grammar, and it reaches the conclusion before the voice does; in a ${raw.purpose} a caption labels where the viewer is ("The E value column", "Part 2: read the results") and the narration explains`);
+  }
   if (raw.end_card) unknown(raw.end_card, END, 'end_card');
   if (raw.intro) unknown(raw.intro, END, 'intro');
   if (raw.hyperframes && typeof raw.hyperframes === 'object') unknown(raw.hyperframes, HYPERFRAMES, 'hyperframes');
@@ -226,12 +291,29 @@ export function check(file, { draft = false } = {}) {
     }
     // spoken lines that read as machine-written, or run on without a breath (the skill's "Writing the narration")
     if (cfg.voice) {
-      const lines = [...visible.flatMap((s) => [[s.say, `step ${cfg.steps.indexOf(s) + 1}`], [s.card?.say, `step ${cfg.steps.indexOf(s) + 1} card`]]),
-        [cfg.intro?.say, 'intro'], [cfg.endCard?.say, 'end card']].filter(([t]) => t);
-      for (const [text, where] of lines) {
+      const teach = cfg.purpose === 'tutorial' || cfg.purpose === 'course';
+      const lines = [...visible.flatMap((s) => [[s.say, `step ${cfg.steps.indexOf(s) + 1}`, true], [s.card?.say, `step ${cfg.steps.indexOf(s) + 1} card`, 'card']]),
+        [cfg.intro?.say, 'intro', false], [cfg.endCard?.say, 'end card', false]].filter(([t]) => t);
+      for (const [text, where, isStep] of lines) {
         const { tells, long } = narrationLint(text);
         if (tells.length) warnings.push(`${where}: the narration sounds machine-written (${tells.map((x) => `"${x}"`).join(', ')}) — say it plainly, as you would out loud`);
-        if (long) warnings.push(`${where}: a ${long} sentence — split it, so the voice gets a breath between the parts`);
+        // a tutorial's own sentence budget is tighter, and it replaces this one
+        if (long && !teach) warnings.push(`${where}: a ${long} sentence — split it, so the voice gets a breath between the parts`);
+        if (!teach) continue;
+        const t = teachingLint(text);
+        if (isStep === 'card' && t.heavy) {
+          // a concept card names one idea. The rule that goes with it, and the number that shows it,
+          // belong to the steps after the card, where the page can carry them
+          warnings.push(`${where}: ${an(t.heavy)} line on one card — a card names one idea; say the rule and read the number in the steps after it, where the page shows them`);
+        } else if (isStep && t.heavy) {
+          warnings.push(`${where}: ${an(t.heavy)} line for one step — one job per step in a ${cfg.purpose} (name the idea, do the action, or read the result); split it`);
+        }
+        if (t.long) {
+          warnings.push(`${where}: ${an(t.long)} sentence — a ${cfg.purpose} keeps them to about ${TEACH.sentenceWords} words (${TEACH.sentenceChars} Chinese characters), so the viewer holds one idea at a time`);
+        }
+        if (t.numbers.length > TEACH.numbers) {
+          warnings.push(`${where}: ${t.numbers.length} figures in one line (${t.numbers.join(', ')}) — nobody holds that many by ear; say the one that carries the point, round it out loud ("about 80 percent"), and leave the exact values on screen`);
+        }
       }
     }
     // the Chinese Kokoro voice needs a Python for its G2P: say so now, not after the recording

package/src/compose.mjs

@@ -10,6 +10,26 @@ import { sceneSeconds, filmGround, mixColour, shadeColour } from './scenes.mjs';
 const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 const md = (s, accent) => esc(s).replace(/\*\*(.+?)\*\*/g, `<b style="color:${accent};font-weight:700">$1</b>`);
 
+// The camera path as one ffmpeg expression: a value per keyframe interval, smoothstepped between the
+// two ends. Written as a FLAT SUM of gated terms, not a nested if/else chain — ffmpeg's expression
+// parser guards recursion at 100 levels, and each zoom contributes four keyframes, so a tutorial
+// written to "one job per step" (30-odd zooms, 130-odd intervals) silently exceeded it and the whole
+// compose failed with "Missing ')' or too many args". A `+` chain is parsed iteratively, so the depth
+// is constant however long the film is. The gates partition the timeline, so exactly one term is ever
+// non-zero: the first interval also covers everything before it, and the last keyframe holds to the end.
+export function keyframeExpr(kf, get, fps) {
+  const n = kf.length, terms = [];
+  for (let i = 0; i < n - 1; i++) {
+    const t0 = kf[i][0], t1 = kf[i + 1][0], v0 = get(kf[i]), v1 = get(kf[i + 1]);
+    const p = `clip((T-${t0.toFixed(3)})/${Math.max(1e-3, t1 - t0).toFixed(3)},0,1)`;
+    const body = v0 === v1 ? `${v0}` : `(${v0}+(${(v1 - v0).toFixed(4)})*${p}*${p}*(3-2*${p}))`;
+    const gate = i === 0 ? `lt(T,${t1.toFixed(3)})` : `(gte(T,${t0.toFixed(3)})*lt(T,${t1.toFixed(3)}))`;
+    terms.push(`${gate}*${body}`);
+  }
+  terms.push(`gte(T,${kf[n - 1][0].toFixed(3)})*${get(kf[n - 1])}`);
+  return `(${terms.join('+')})`.replaceAll('T', `(on/${fps})`);
+}
+
 export async function compose(cfg, { log = console.log, voiceLens = { steps: {}, endCard: null } } = {}) {
   const warnings = [];
   const warn = (m) => { warnings.push(m); log(`warning: ${m}`); };
@@ -192,11 +212,23 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       ...cards.map((c) => [c.t0, c.t1]),
       ...segs.filter((g) => voiceLens.steps[g.i] != null).map((g) => [g.o0 + g.sayAt, g.o0 + g.sayAt + voiceLens.steps[g.i]]),
     ];
+    // A promo must never stall. A tutorial is the opposite: the viewer is doing this too, and needs a
+    // beat to read the result, find the control on their own screen, and catch up. So a lesson gets a
+    // longer allowance, and a step that asked to hold (`pause`) means it — only a hold long enough to
+    // feel broken is worth a word there.
+    const teach = cfg.purpose === 'tutorial' || cfg.purpose === 'course';
+    const held = (i) => (cfg.steps[i]?.actions ?? []).some((a) => a && (a.pause != null || a.wait != null));
     let from = null;
     const report = (to) => {
-      if (from != null && to - from >= 3) {
+      if (from != null) {
         const ns = segs.filter((x) => x.o1 > from + 1e-6 && x.o0 < to - 1e-6).map((x) => x.i + 1);
-        warn(`${ns.length > 1 ? `steps ${ns[0]}–${ns.at(-1)}` : `step ${ns[0] ?? (segs.at(-1)?.i ?? cfg.steps.length - 1) + 1}`}: ${(to - from).toFixed(1)}s of dead air at ${from.toFixed(1)}–${to.toFixed(1)}s (nothing moves and nothing is said) — shorten the wait or pause, hide the load, or narrate what is happening`);
+        const limit = !teach ? 3 : ns.length && ns.every((k) => held(k - 1)) ? 8 : 6;
+        const fix = teach
+          ? 'say what is happening or what to look at, or let the step hold on purpose with `pause`'
+          : 'shorten the wait or pause, hide the load, or narrate what is happening';
+        if (to - from >= limit) {
+          warn(`${ns.length > 1 ? `steps ${ns[0]}–${ns.at(-1)}` : `step ${ns[0] ?? (segs.at(-1)?.i ?? cfg.steps.length - 1) + 1}`}: ${(to - from).toFixed(1)}s of dead air at ${from.toFixed(1)}–${to.toFixed(1)}s (nothing moves and nothing is said) — ${fix}`);
+        }
       }
       from = null;
     };
@@ -270,16 +302,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   }
   if (kf.at(-1)[0] < TOTAL) kf.push([TOTAL, 1, C0]);
   const S = 2; // supersample to avoid zoompan's integer-pixel jitter
-  const piece = (get) => {
-    let e = String(get(kf.at(-1)));
-    for (let i = kf.length - 2; i >= 0; i--) {
-      const t0 = kf[i][0], t1 = kf[i + 1][0], v0 = get(kf[i]), v1 = get(kf[i + 1]);
-      const p = `clip((T-${t0.toFixed(3)})/${Math.max(1e-3, t1 - t0).toFixed(3)},0,1)`;
-      const body = v0 === v1 ? `${v0}` : `(${v0}+(${(v1 - v0).toFixed(4)})*${p}*${p}*(3-2*${p}))`;
-      e = `if(lt(T,${t1.toFixed(3)}),${body},${e})`;
-    }
-    return e.replaceAll('T', `(on/${FPS})`);
-  };
+  const piece = (get) => keyframeExpr(kf, get, FPS);
   const zExpr = piece((k) => k[1]);
   const cxExpr = piece((k) => +(k[2][0] * S).toFixed(1));
   const cyExpr = piece((k) => +(k[2][1] * S).toFixed(1));

package/src/record.mjs

@@ -423,7 +423,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   }
   const { width: VW, height: VH } = cfg.viewport;
 
-  const browser = await chromium.launch();
+  // STORYSHOT_GPU=1 renders WebGL on the GPU (Metal on macOS) instead of SwiftShader;
+  // 3D pages otherwise record at ~10 fps and every step comes out rushed.
+  const gpu = /^(1|true|yes)$/i.test(process.env.STORYSHOT_GPU || '');
+  const browser = await chromium.launch(gpu ? { args: ['--enable-gpu', '--ignore-gpu-blocklist', ...(process.platform === 'darwin' ? ['--use-angle=metal'] : [])] } : {});
   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`