storyshot 0.6.0 → 0.7.0

package/README.md

@@ -153,7 +153,7 @@ Rendering is free and runs locally. Only the voiceover can cost money:
 |---|---|---|
 | none | free | captions only |
 | `kokoro` | free | local, English and Mandarin Chinese (`zf_001`); downloads a ~90 MB model on first use (Chinese: ~130 MB, and needs Python 3.10–3.12) |
-| `qwen` | free | local, Apple Silicon Macs only; the most natural free Chinese voice (`dylan`, `serena`); downloads a ~2.3 GB model and needs Python 3.10–3.12 |
+| `qwen` | free | local, Apple Silicon Macs only; the most natural free Chinese voice (`dylan`, `serena`); every take is checked by a speech recognizer and made again if it comes out wrong; downloads ~3.3 GB of models and needs Python 3.10–3.12 |
 | ElevenLabs | your credits | the most natural voice; many languages including Chinese. Put `ELEVENLABS_API_KEY` in `.env`. |
 | OpenAI | your credits | `OPENAI_API_KEY` |
 
@@ -191,7 +191,7 @@ from `storyshot guide`.
 | `inspect_page` | Verified click targets and a screenshot, for a URL or for the state after step N of a storyboard. Reports login walls. |
 | `login` | Opens a browser window where the **user** logs in, and saves the session. |
 | `init_storyboard` | Writes a starter storyboard with verified targets. |
-| `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file. |
+| `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file, and narration that sounds machine-written ("not just X, but Y", "seamless", 赋能…) or runs on without a breath. |
 | `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. |
 
 Any other MCP client: run `npx -y storyshot mcp` (stdio), and point the agent at the playbook (`storyshot guide`). When run from a git
@@ -248,7 +248,7 @@ viewport: { width: 1600, height: 900 }          # CSS px the site is laid out at
 output: { width: 1920, height: 1080, fps: 30 }  # same aspect ratio; use 1080x1920 with a 900x1600 viewport for vertical
 theme: { accent: "#d9f75b", ink: "#0f172a", font: Inter }
 music: { bpm: 120, volume: 1 }                  # or { file: track.mp3 }, or false
-sfx: true                                       # click / whoosh / riser sounds; clicks = no whooshes on cards and page changes (tutorial and course default); false = none
+sfx: true                                       # click / whoosh / riser sounds; clicks = no whooshes on cards and page changes, and no rising sound under a riser step, only its chime (tutorial and course default); false = none
 voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceover, see below
 storageState: auth.json                         # optional Playwright login state
 ignoreHTTPSErrors: true                         # internal site with a self-signed HTTPS certificate (plain http:// needs nothing)
@@ -287,7 +287,7 @@ steps:
       - click: { role: button, name: Try it }
   - caption: AI does the work
     duration: 1.3
-    sfx: riser                                        # rising sound + chime (or `chime`)
+    sfx: riser                                        # rising sound + chime (or `chime`); a tutorial or lesson plays only the 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
@@ -332,15 +332,15 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | `waitForUrl` | `waitForUrl: "**/dashboard"` |
 | `networkIdle` | `networkIdle: true` |
 | `goto` | `goto: /pricing` |
-| `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` |
+| `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` scrolls the target to the top of the window, below a sticky header |
 | `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. |
+| `mark` | `mark: "automatic zoom, captions"` sweeps a highlighter over that phrase, even inside a paragraph (scrolling to it only if it's off screen, and below a sticky header). `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 |
+| `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. `value: 3` drags it to that value instead, when the slider reports its range (an `<input type=range>`, or an ARIA slider such as Desmos's; `inspect` shows the range). The target can be the slider or its knob |
 | `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
@@ -375,7 +375,7 @@ In-page anchor links (`href="#..."`) scroll smoothly instead of jumping.
 |---|---|
 | `target` | What to center on: a target, or a point `{ x: 0.5, y: 0.3 }`. If a step action used the same target, its position at that moment is used (so you can zoom on a button that disappears after the click). Otherwise it is measured at the start of the step when the zoom begins in the first half, or at the end of the step otherwise. |
 | `scale` | Zoom factor (default 1.3). 1.2–1.5 works well. |
-| `start`, `end` | Seconds from the start of the step. The camera eases in from 1× at `start` and is back at 1× at `end` (default: the step's end). `end` may run past the step, e.g. to hold the zoom through a click. |
+| `start`, `end` | Seconds from the start of the step. The camera eases in from 1× at `start` and is back at 1× at `end` (default: the step's end). A zoom belongs to its step: an `end` past the step's end stops there, with a warning. |
 | `ramp` | Ease-in / ease-out seconds: `0.5` or `[in, out]`. |
 | `offset` | Moves the camera center from the target's center, in viewport CSS px. `{ y: -120 }` centers 120 px above the target. |
 
@@ -419,14 +419,20 @@ for Chinese tutorials, lessons and docs), `serena` (female, warm; the default fo
 `vivian` (female, bright), `uncle_fu` (male, mellow), `eric` (male, Sichuan accent), and `ryan`, `aiden` (English), `ono_anna` (Japanese), `sohee` (Korean). On
 first use Storyshot creates a venv in `~/.cache/storyshot/qwen-venv` (Python 3.10–3.12, about 400 MB)
 and downloads the ~2.3 GB model into the Hugging Face cache. It speaks at about 2x real time on an M4 Pro
-and peaks at about 8 GB of memory. The model samples its speech, so a line now and then runs on into
-invented words or stops short. Storyshot regenerates such a take (it judges by length) and warns if
-one still looks off. A scientific number like `2e-105` is spelled out in Chinese, because it sets the
+and peaks at about 8 GB of memory. The model samples its speech, so a take now and then garbles a few
+words, drops one, runs on into invented words or stops short. Storyshot listens to every take with
+[Qwen3-ASR 0.6B](https://huggingface.co/Qwen/Qwen3-ASR-0.6B) (Apache-2.0, a ~1 GB model downloaded on
+first use) and compares what it hears with the line: Chinese by sound, so a homophone isn't a mistake, and
+numbers digit by digit. A take that comes out wrong, or far too long or short, is made again with another
+seed (up to 4 tries), and Storyshot warns, quoting what it heard, if a line still doesn't come out right.
+This adds about 0.2 s per line. A scientific number like `2e-105` is spelled out in Chinese, because it sets the
 model babbling. On other machines the same storyboard renders with `kokoro` (`zf_001`, or `draftVoice`),
 with a note.
 
-Other fields: `speed` (default 1), `volume` (default 1), and `pronounce`, a
-map of word → spoken form used only for TTS, e.g.
+Other fields: `speed` (default 1), `volume` (default 1), `pause` (the shortest pause between the
+sentences of a line, in seconds: 0.3 for promos, 0.6 for tutorials and lessons; a voice's own longer pause
+stays, and `0` leaves the voice as it is),
+and `pronounce`, a map of word → spoken form used only for TTS, e.g.
 `pronounce: { pxGenius: P X Genius, PPTX: P P T X }`. Subtitles keep the real
 spelling. Synthesized lines
 are cached in `.storyshot/tts-cache/`, so `compose` only pays for lines you
@@ -459,11 +465,12 @@ usually shouldn't.
 | `say` | Voiceover line played over the end card. |
 | `emblem` | With `hyperframes`: one to three short monospace lines over the title (an alignment, a formula, a line of code); `false` for none. |
 
-### HyperFrames cards (optional)
+### HyperFrames cards
 
-`hyperframes: true` renders the intro, section and end cards with
+Tutorials and lessons render their intro, section and end cards with
 [HyperFrames](https://hyperframes.heygen.com) (HeyGen's open-source HTML-to-video
-renderer, Apache-2.0) for more motion. Two templates, picked by `purpose`:
+renderer, Apache-2.0) for more motion; `hyperframes: false` keeps the built-in
+cards, and `hyperframes: true` turns them on for a promo. Two templates, picked by `purpose`:
 
 - **lesson** (tutorials, courses, docs): the title lands word by word over a
   slowly drifting, blurred view of the page the section leads into; section
@@ -485,7 +492,7 @@ hyperframes:
   backdrop: false         # lesson: plain background instead of the blurred page
 ```
 
-It needs Node 22 or newer. On first use storyshot installs the pinned
+It needs Node 22 or newer; on older Node, tutorials and lessons use the built-in cards. On first use storyshot installs the pinned
 HyperFrames version into `~/.cache/storyshot/hyperframes/` (a local install
 of the `hyperframes` package wins); its telemetry is switched off. Cards are
 cached, so `compose` only re-renders the ones that changed (about 10–25 s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.6.0",
+  "version": "0.7.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

@@ -92,8 +92,11 @@ frames or stock footage presented as a recording of their app.
    best free Chinese voice is `voice: { provider: qwen }` (Qwen3-TTS: `dylan`,
    a male teacher's voice, for tutorials and lessons; `serena`, female, for
    promos; those are the defaults): clearer than
-   zf_001 with English words and letters, about 2x real time, a ~2.3 GB model
-   on first use. Elsewhere a `qwen` storyboard renders with kokoro. For other
+   zf_001 with English words and letters, about 2x real time, ~3.3 GB of
+   models on first use. Storyshot listens to each take and makes it again if
+   it comes out garbled; a `⚠ qwen: … sounds like "…"` warning means a line
+   still came out wrong after 4 tries: rephrase it (spell out a number, say
+   `一格` for `1 格`). Elsewhere a `qwen` storyboard renders with kokoro. For other
    languages, use ElevenLabs.
 3. **Login.** If the flow needs a logged-in page:
    - Tell the user a browser window will open and that they should log in
@@ -184,14 +187,18 @@ small controls are readable. Your job is the structure:
   `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.
-- **More motion on the cards** (when the user asks for livelier titles, or for
-  a launch video): `hyperframes: true` renders the intro, section and end
-  cards with HyperFrames (needs Node 22+; installs itself on first use). For a
-  subject with its own material, give the titles a backdrop from it:
+- **Animated cards that help explain.** Tutorials and lessons render their
+  cards with HyperFrames by default (Node 22+; it installs itself on first
+  use): titles land word by word, and each bullet lights up when the `say`
+  line names it, so write the bullets in the narration's own words. Use them:
+  a concept card for every idea that isn't on screen (the idea as the title,
+  its 2–4 steps as bullets, a formula or a line of code as `emblem`), a
+  question card for each check, and a recap end card. For a subject with its
+  own material, give every title a backdrop from it:
   `hyperframes: { band: <a sequence or formula>, emblem: [<1–3 short lines>] }`.
-  Promos get hand-drawn accents; `hand: true` uses hand lettering. Write the
-  intro's `bullets` and the end card's recap with the same words the `say`
-  line uses: each point lights up when the narration names it.
+  For a promo, `hyperframes: true` gives the launch template with hand-drawn
+  accents (`hand: true` for hand lettering). `hyperframes: false` keeps the
+  built-in cards.
 - **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,
@@ -206,6 +213,59 @@ 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.
 
+### Writing the narration
+
+Viewers notice three things first: lines that run together, phrasing nobody
+says out loud, and an explanation that jumps around. Write the `say:` lines as
+a script before the steps around them, then read them in order on their own.
+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.
+- 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
+  for variety).
+- Each sentence gets a breath after it: Storyshot widens the pause between
+  sentences to at least `voice.pause` (0.3 s for `pitch`, 0.6 s for tutorials
+  and lessons). Commas get no extra pause, so split long lines into sentences
+  rather than chaining clauses with commas.
+- For fixed durations, budget about 2.5 words a second in English and 4
+  characters a second in Chinese, and leave silence while the screen is busy.
+
+**Cut the phrases that mark text as machine-written** (`check` flags the
+common ones):
+- Contrasts that only add weight: "not just X, but Y", "it's not X, it's Y".
+- Inflated words: seamless, effortless, powerful, robust, unlock, elevate,
+  supercharge, revolutionize, leverage, cutting-edge, game-changer, delve;
+  "in today's fast-paced world". In Chinese: 赋能, 助力, 一站式, 全方位, 极致,
+  无缝, 轻松搞定, 不仅……更……, 让我们一起.
+- Openers and closers that say nothing: "Let's dive in", "Ever wondered…?",
+  "And that's it!", "Simple as that."
+- Three adjectives in a row, line after line ("fast, simple and powerful").
+- Filler that talks down to a stuck viewer: basically, simply, just, easily.
+- Dashes (—) in `say:` lines. Voices read them as a run-on; use a period.
+
+**Explain in an order the viewer can follow** (tutorials and lessons):
+1. The question or the goal ("How does b move the line?").
+2. A concrete case on screen first: change the value, show the result.
+3. Then name the idea, in plain words, the first time it appears.
+4. Why it works, in one or two sentences, with a concept card if it isn't on
+   screen (its bullets light up as you name them; a formula goes in `emblem`).
+5. A check: a question card, then the step that reveals the answer.
+6. The recap, in the same words as before.
+
+Every step answers the question the step before it raised. Link them out loud:
+"Now that b has moved the line up, let's see what m does." When the camera
+has to go somewhere else on the page, say why first ("The results are further
+down, in the table."). If a line only makes sense with the video, or the
+script reads as a list of disconnected facts, reorder the steps before you
+render.
+
+(These rules borrow from [humanizer](https://github.com/blader/humanizer) and
+[stop-slop](https://github.com/hardikpandya/stop-slop), both MIT.)
+
 Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
@@ -225,11 +285,15 @@ Rules of thumb from real renders (promos and tutorials):
   `voice.pronounce` (e.g. `pxGenius: P X Genius`, `AI: A I`) so subtitles stay
   correct. For fixed durations, budget about 2.5 words per second.
 - **Isolate long waits** (AI processing, uploads) in their own step: a
-  `waitFor` the finished state, `sfx: riser`, and in `pitch` mode
-  `duration: 1.0–1.5`. Waiting is compressed automatically.
+  `waitFor` the finished state. In `pitch` mode add `sfx: riser` and
+  `duration: 1.0–1.5`. In tutorials and lessons, say what is happening
+  instead; at most `sfx: chime` when the result arrives (a riser there plays
+  only its chime). Waiting is compressed automatically.
 - **Zoom sparingly**, on 2–4 payoff moments (headline, clicked button, result,
   price), with `scale: 1.2–1.5`.
-- **Show the signature interaction.** Use `drag` for sliders and before/after
+- **Show the signature interaction.** Use `slide` for sliders:
+  `slide: { target: <the slider inspect lists>, value: 3 }` lands on that value
+  (`to: 0..1` for sliders that don't report a range). Use `drag` for before/after
   views (`drag: { from: { x: 0.57, y: 0.5 }, by: [{ x: -300 }, { x: 400 }] }`;
   `from` can be a target or a point). Use `type` for inputs: `type: y=x^2`
   types into whatever has focus (for editors and canvases with hidden inputs),

package/src/audio.mjs

@@ -108,7 +108,8 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
         return filt(rand(), 400 + 5000 * Math.sin(Math.PI * p), 1.6).bp * Math.pow(Math.sin(Math.PI * p), 2);
       }, 0.5);
     }
-    for (const [a, b] of events.risers) {
+    // the rising sound under a wait is for promos; tutorials and lessons (sfx: clicks) keep only its chime
+    for (const [a, b] of cfg.sfx.transitions ? events.risers : []) {
       const len = b - a, filt = svf();
       let ph = 0;
       add(sfx, a, len, (t) => {
@@ -133,12 +134,15 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   if (cfg.voice && events.voice?.length) {
     let prevEnd = 0;
     for (const line of events.voice) {
-      let pcm = await speak(cfg, line.text, { log });
+      let { pcm, parts } = await speak(cfg, line.text, { log });
       let dur = pcm.length / 2 / SR;
       const start = Math.max(line.start, prevEnd + 0.12), room = line.until - start - 0.1;
       let sped = 1;
       // a line pushed past its window by the one before has no room left (room <= 0): it plays late, at normal speed
-      if (dur > room && room > 0 && dur / room <= 1.2) { sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR; }
+      if (dur > room && room > 0 && dur / room <= 1.2) {
+        sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR;
+        parts = parts.map((p) => ({ ...p, start: p.start / sped, end: p.end / sped }));
+      }
       else if (dur > room) warn(room > 0
         ? `${line.where}: narration is ${dur.toFixed(1)}s but only ${room.toFixed(1)}s until ${line === events.voice.at(-1) ? 'the video ends' : 'the next line'} — shorten "${line.text}" or give the step more duration`
         : `${line.where}: the narration before it runs ${(start - line.start).toFixed(1)}s past where this line should start, so "${line.text}" plays late — shorten the earlier lines or give their steps more duration`);
@@ -154,7 +158,8 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
         voiceOn[s0 + i] = 1;
       }
       prevEnd = start + dur;
-      narration.push({ start, end: start + dur, text: line.text });
+      // subtitles per sentence, so the pauses between them don't throw off the word timing
+      for (const p of parts) narration.push({ start: start + p.start, end: Math.min(start + p.end, start + dur), text: p.text });
     }
   }
 

package/src/check.mjs

@@ -5,6 +5,34 @@ import { loadConfig } from './config.mjs';
 import { gitIgnored } from './auth.mjs';
 import { isZhVoice, zhVoiceStatus } from './kokoro-zh.mjs';
 import { qwenStatus } from './qwen-tts.mjs';
+import { sentences } from './voice.mjs';
+
+// 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"
+  /\bit'?s not (?:about )?[^.,;!?]{1,30}[,;—–-]+ it'?s\b/i, // "it's not X, it's Y"
+  /\b(?:seamless(?:ly)?|effortless(?:ly)?|supercharg\w*|revolutioni[sz]\w*|game[- ]chang\w*|cutting[- ]edge|elevat(?:e|es|ed|ing)|leverag(?:e|es|ed|ing)|delv(?:e|es|ing))\b/i,
+  /\bin today'?s (?:fast-paced|digital|modern)\b/i,
+  /\blet'?s dive in\b|\bever wondered\b|\bsimple as that\b|\band that'?s it\b/i,
+  /\b(?:basically|simply)\b/i, // ("easily" is too often literal: "binds more easily")
+  /[—–]/,
+  /赋能|助力|一站式|全方位|极致|无缝|轻松搞定|让我们一起|不仅[^。！？]{1,20}更/,
+];
+export function narrationLint(text) {
+  const t = String(text).replace(/\*\*/g, ''), tells = [];
+  for (const re of TELLS) {
+    const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+    for (const m of t.matchAll(g)) if (!tells.includes(m[0].trim())) tells.push(m[0].trim());
+  }
+  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;
+    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', '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', 'hyperframes'];
@@ -107,7 +135,7 @@ export function check(file, { draft = false } = {}) {
     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)`);
+      if (!v?.target || (typeof v?.value !== 'number' && (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) or { target: <slider>, value: <number> }`);
       else target(v.target, `${where} (slide.target)`);
     }
     if (type === 'select') {
@@ -146,7 +174,7 @@ export function check(file, { draft = false } = {}) {
     // estimate from its length; the render measures the real voice)
     if (cfg.voice) {
       const words = (t) => { const x = String(t).replace(/\*\*/g, ''); const c = (x.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length; return { c, w: x.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter(Boolean).length }; };
-      const secs = (t) => { const { c, w } = words(t); return (c / 4.5 + w / 2.8) / (cfg.voice.speed ?? 1); };
+      const secs = (t) => { const { c, w } = words(t); return (c / 4.5 + w / 2.8) / (cfg.voice.speed ?? 1) + (sentences(t).length - 1) * (cfg.voice.pause ?? 0); };
       const vis = visible.map((s) => ({ s, i: cfg.steps.indexOf(s) }));
       for (const [k, { s, i }] of vis.entries()) {
         if (!s.say) continue;
@@ -158,6 +186,16 @@ export function check(file, { draft = false } = {}) {
         if (need > room * 1.4 && need - room > 1) warnings.push(`step ${i + 1}: the say: line takes about ${need.toFixed(1)}s to speak but has ${room.toFixed(1)}s before ${nextK < 0 ? 'the video ends' : 'the next line'} — shorten it or raise duration (the lines after it would play late)`);
       }
     }
+    // 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 { 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`);
+      }
+    }
     // the Chinese Kokoro voice needs a Python for its G2P: say so now, not after the recording
     const v = draft && cfg.voice ? loadConfig(file, { draft }).voice : cfg.voice;
     if (v?.provider === 'kokoro' && isZhVoice(v.voice)) {

package/src/compose.mjs

@@ -235,6 +235,11 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       g.zoomBox = null;
     } else if (z && !g.zoomBox) warn(`step ${g.i + 1}: zoom target not found on the page, zoom skipped`);
     if (!z || !g.zoomBox) continue;
+    {
+      // measured off screen (e.g. before the step scrolled to it): the camera can only frame what's in the window
+      const b = g.zoomBox, cx = b.x + b.width / 2, cy = b.y + b.height / 2, { width: VW, height: VH } = cfg.viewport;
+      if (cx < 0 || cx > VW || cy < 0 || cy > VH) warn(`step ${g.i + 1}: the zoom target was off screen when it was measured (${cy > VH ? `${Math.round(cy - VH)}px below` : cy < 0 ? `${Math.round(-cy)}px above` : 'beside'} the window), so the zoom frames the edge of the page instead — zoom on something an action in this step moves to, or use a point target`);
+    }
     g.zoomPeak = g.o0 + (z.start ?? 0) + (Array.isArray(z.ramp) ? z.ramp[0] : z.ramp ?? 0.5) + 0.1;
     const b = g.zoomBox, off = z.offset ?? {};
     const c = [(b.x + b.width / 2 + (off.x ?? 0)) * K, (b.y + b.height / 2 + (off.y ?? 0)) * K];

package/src/config.mjs

@@ -31,10 +31,10 @@ export function loadEnv(dir) {
 
 // What the video is for sets sensible defaults; anything in the YAML overrides them.
 export const PURPOSES = {
-  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false },
-  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
-  course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
-  docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false },
+  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false, hyperframes: false },
+  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
+  course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
+  docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false, hyperframes: false },
 };
 
 // Where storyboards and their videos go, and how they're named: <site>-<kind>[-<topic>].yaml →
@@ -43,9 +43,10 @@ export const PURPOSES = {
 // follow each action and to read its result before the next one starts.
 export const PACES = {
   //        cursor ms  typing ms/char  beat after a click (ms)  hold after narration (s)  waits shown up to (s)  voice speed
-  fast:   { cursor: 700,  type: 55,  beat: 0,   tail: 0.4, maxWait: 1.0, voiceSpeed: 1 },
-  normal: { cursor: 900,  type: 70,  beat: 350, tail: 0.8, maxWait: 1.5, voiceSpeed: 1 },
-  slow:   { cursor: 1200, type: 95,  beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92 },
+  //        shortest pause between the sentences of one line (s)
+  fast:   { cursor: 700,  type: 55,  beat: 0,   tail: 0.4, maxWait: 1.0, voiceSpeed: 1,    sentencePause: 0.3 },
+  normal: { cursor: 900,  type: 70,  beat: 350, tail: 0.8, maxWait: 1.5, voiceSpeed: 1,    sentencePause: 0.45 },
+  slow:   { cursor: 1200, type: 95,  beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92, sentencePause: 0.6 },
 };
 
 export const FRAME_STYLES = ['aurora', 'studio', 'dark', 'pastel', 'blur'];
@@ -138,8 +139,9 @@ export function loadConfig(file, { draft = false } = {}) {
   if (frame?.icon) frame.iconFile = path.resolve(dir, frame.icon);
 
   // hyperframes: true | { template: lesson | launch, band, bandColors, emblem, hand, backdrop } — cards
-  // rendered by HyperFrames (see hyperframes.mjs); promos get the launch template, the rest the lesson one
-  const hf0 = raw.hyperframes;
+  // rendered by HyperFrames (see hyperframes.mjs); promos get the launch template, the rest the lesson one.
+  // On by default for tutorials and lessons, where Node can run it (22+); else the built-in cards
+  const hf0 = raw.hyperframes !== undefined ? raw.hyperframes : P.hyperframes && Number(process.versions.node.split('.')[0]) >= 22;
   const hyperframes = hf0 ? { template: purpose === 'pitch' ? 'launch' : 'lesson', backdrop: true, ...(typeof hf0 === 'object' ? hf0 : {}) } : null;
   if (hyperframes && !['lesson', 'launch'].includes(hyperframes.template)) throw new Error('hyperframes.template must be lesson or launch');
   if (hyperframes?.bandColors && !['aminoacid', 'nucleotide', 'accent'].includes(hyperframes.bandColors)) throw new Error('hyperframes.bandColors must be aminoacid, nucleotide or accent');
@@ -152,7 +154,8 @@ export function loadConfig(file, { draft = false } = {}) {
     // kokoro's and qwen's default voices follow the narration's language (zf_001 / serena for Chinese)
     const kokoroVoice = kokoroVoiceFor(raw);
     const byLang = { kokoro: kokoroVoice, qwen: qwenVoiceFor(raw) }[provider];
-    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...raw.voice, provider };
+    voice = { speed: pace0.voiceSpeed, volume: 1, pause: pace0.sentencePause, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...raw.voice, provider };
+    if (!(typeof voice.pause === 'number' && voice.pause >= 0 && voice.pause <= 3)) throw new Error('voice.pause is the shortest pause between the sentences of a line, in seconds, 0–3 (0 leaves the voice as it is)');
     if (provider === 'qwen') {
       const v = qwenVoice(voice.voice);
       if (!v) throw new Error(`voice: qwen has no voice "${voice.voice}" (one of ${QWEN_VOICES.join(', ')})`);
@@ -214,8 +217,8 @@ export function loadConfig(file, { draft = false } = {}) {
     follow,
     music,
     voice,
-    // sfx: true (clicks and transition whooshes), 'clicks' (no whooshes: tutorials and lessons, where a
-    // sound at every card soon grates), or false
+    // sfx: true (clicks, transition whooshes and risers), 'clicks' (no whooshes or risers: tutorials and
+    // lessons, where a sound at every card soon grates), or false
     sfx: pick('sfx') === false ? false : { clicks: true, transitions: pick('sfx') !== 'clicks' },
     draft,
     out: path.resolve(dir, raw.out ?? `${name}.mp4`).replace(/(\.[^./]+)?$/, (ext) => (draft ? `.draft${ext || '.mp4'}` : ext)),

package/src/doctor.mjs

@@ -81,8 +81,8 @@ export async function doctor({ log = console.log } = {}) {
       : '· Chinese voice (kokoro zf_001) needs Python 3.10–3.12 — optional: brew install python@3.12, or uv python install 3.12 (or set STORYSHOT_PYTHON)');
   const q = qwenStatus();
   lines.push(!q.supported ? '· Qwen3-TTS voice (provider: qwen) needs an Apple Silicon Mac; storyboards that use it fall back to kokoro here'
-    : q.ready ? `✔ Qwen3-TTS voice (provider: qwen): venv in ${q.venv}${q.model ? ', model downloaded' : '; the model (~2.3 GB) downloads on first use'}`
-      : q.python ? `· Qwen3-TTS voice (provider: qwen): Python ${q.python.version} found; storyshot sets up its venv in ${q.venv} and downloads the model (~2.3 GB) on first use`
+    : q.ready ? `✔ Qwen3-TTS voice (provider: qwen): venv in ${q.venv}${q.model ? ', models downloaded' : '; the models (~3.3 GB: the voice, and a speech recognizer that checks each take) download on first use'}`
+      : q.python ? `· Qwen3-TTS voice (provider: qwen): Python ${q.python.version} found; storyshot sets up its venv in ${q.venv} and downloads the models (~3.3 GB) on first use`
         : '· Qwen3-TTS voice (provider: qwen) needs Python 3.10–3.12 — optional: brew install python@3.12, or uv python install 3.12 (or set STORYSHOT_PYTHON)');
   const hf = hyperframesCli();
   lines.push(hf.error ? `· HyperFrames cards (hyperframes: true) unavailable — optional: ${hf.error}`

package/src/init.mjs

@@ -7,6 +7,14 @@ import { PURPOSES, defaultStoryboard } from './config.mjs';
 import { loginAdvice } from './auth.mjs';
 
 const q = (s) => JSON.stringify(String(s));
+// The product's name from the page title: its first part ("Squoosh | Image compressor" → "Squoosh"),
+// or the repo on a code host ("GitHub - boheling/storyshot: Ask…" → "storyshot"). Only spaced
+// separators split, so a hyphenated name (Tic-Tac-Toe) stays whole.
+export function productName(title, host) {
+  const segs = String(title ?? '').split(/\s+[|—–·-]\s+|:\s+/).map((s) => s.trim()).filter(Boolean);
+  const repo = segs.find((s) => /^[\w.-]+ ?\/ ?[\w.-]+$/.test(s));
+  return repo ? repo.split('/')[1].trim() : segs[0] ?? host;
+}
 const tgt = (t) => (typeof t === 'string' ? q(t) : `{ ${Object.entries(t).map(([k, v]) => `${k}: ${typeof v === 'string' ? q(v) : v}`).join(', ')} }`);
 
 export async function initStoryboard(url, { purpose = 'pitch', topic, file, storageState, ignoreHTTPSErrors = false, viewport = { width: 1600, height: 900 } } = {}) {
@@ -41,7 +49,7 @@ out: ${name}.mp4
 ${storageState ? `storageState: ${path.relative(path.dirname(path.resolve(file)), path.resolve(storageState)).split(path.sep).join('/')}   # saved login (never commit it)\n` : ''}${ignoreHTTPSErrors ? 'ignoreHTTPSErrors: true   # internal site with a self-signed certificate\n' : ''}${narrated ? 'voice: { provider: kokoro }        # free, local, English. For the final: { provider: elevenlabs, voice: <voice id> } + ELEVENLABS_API_KEY' : '# voice: { provider: kokoro }      # optional voiceover; add `say:` lines to steps'}
 
 ${purpose === 'pitch' ? `intro:                             # title card before the recording (promos; optional for tutorials/lessons)
-  title: ${q(page.title.split(/[|—–-]/)[0].trim() || host)}
+  title: ${q(productName(page.title, host))}
   subtitle: TODO the one-line promise, with the **key words** in bold
 ${PURPOSES[purpose]?.frame ? '# frame: false                     # the recording sits in a browser window on a backdrop; false = full frame\n' : ''}
 ` : purpose === 'tutorial' || purpose === 'course' ? `# intro: { title: TODO, subtitle: TODO }   # optional title card (e.g. "How to export a report")
@@ -65,7 +73,7 @@ steps:
   # run \`storyshot inspect ${file} --after <step>\` to list verified targets at that point.
 
 end_card:
-  title: ${q(page.title.split(/[|—–-]/)[0].trim() || host)}
+  title: ${q(productName(page.title, host))}
   cta: ${q(`Try it at ${host}`)}${narrated ? `\n  say: ${q(`Try it at ${host}.`)}` : ''}
 
 # ── Verified targets on ${page.url} (each matches exactly one visible element) ──

package/src/inspect.mjs

@@ -44,7 +44,8 @@ function collect() {
   const clean = (s) => (s || '').replace(/\s+/g, ' ').trim();
   // a short CSS selector (tag + classes, or #id) — the last-resort target when names don't resolve
   const cssOf = (el) => {
-    if (el.id && !/^[0-9:]|:/.test(el.id)) return `#${CSS.escape(el.id)}`;
+    const id = el.getAttribute('id'); // not el.id: a form with an <input name=id> has that input as its .id
+    if (id && !/^[0-9:]|:/.test(id)) return `#${CSS.escape(id)}`;
     const cls = [...el.classList].filter((c) => !/^(css|sc|jsx|svelte|tw)-|\d{3,}|__/.test(c)).slice(0, 2).map((c) => `.${CSS.escape(c)}`).join('');
     return cls ? `${el.tagName.toLowerCase()}${cls}` : null;
   };
@@ -68,10 +69,17 @@ function collect() {
   // a label's own text, without the links/buttons inside it (e.g. a "Clear" link)
   const labelText = (lab) => { if (!lab) return null; const c = lab.cloneNode(true); c.querySelectorAll('a,button,select,input,textarea').forEach((x) => x.remove()); return clean(c.innerText) || null; };
   // styled checkboxes and radios hide the real input and draw their label instead: list them where the label is
+  // a slider's range and value, when it says (an <input type=range>, or aria-valuemin/max/now)
+  const sliderRange = (el) => {
+    const n = (a) => (el.getAttribute(a) == null ? NaN : Number(el.getAttribute(a)));
+    const [lo, hi, now] = el.type === 'range' ? [Number(el.min || 0), Number(el.max || 100), Number(el.value)] : [n('aria-valuemin'), n('aria-valuemax'), n('aria-valuenow')];
+    return [lo, hi, now].every(Number.isFinite) ? { lo, hi, now } : null;
+  };
   const shownBy = (el) => (el.tagName === 'INPUT' && ['checkbox', 'radio'].includes(el.type) && !vis(el) ? [...(el.labels ?? [])].find(vis) : null);
   const interactive = [...document.querySelectorAll(NATIVE)]
     .filter((el) => (vis(el) || shownBy(el)) && el.tagName !== 'LABEL' && !isAd(el) && !(el.isContentEditable && el.parentElement?.isContentEditable))
     .map((el) => ({ kind: 'role', role: roleOf(el), name: (el.isContentEditable || el.tagName === 'TEXTAREA' ? editorName(el) : nameOf(el)).slice(0, 80), shows: clean(el.innerText).slice(0, 60), alt: clean(el.querySelector('img[alt]')?.alt) || null, href: el.getAttribute('href'), label: labelText(el.labels?.[0]),
+      range: roleOf(el) === 'slider' ? sliderRange(el) : null,
       options: el.tagName === 'SELECT' ? [...el.options].map((o) => ({ text: clean(o.text), on: o.selected })).filter((o) => o.text).slice(0, 12) : null, ...pos(shownBy(el) ?? el) }));
   // custom clickables: outermost cursor:pointer elements that aren't native controls
   const pointer = [];
@@ -85,11 +93,11 @@ function collect() {
   return {
     title: document.title,
     height: scroller ? scroller.scrollHeight : document.documentElement.scrollHeight,
-    scroller: scroller ? (scroller.id ? `#${scroller.id}` : scroller.tagName.toLowerCase() + (scroller.className && typeof scroller.className === 'string' ? '.' + scroller.className.trim().split(/\s+/)[0] : '')) : null,
+    scroller: scroller ? (scroller.getAttribute('id') ? `#${scroller.getAttribute('id')}` : scroller.tagName.toLowerCase() + (scroller.className && typeof scroller.className === 'string' ? '.' + scroller.className.trim().split(/\s+/)[0] : '')) : null,
     headings: [...document.querySelectorAll('h1, h2, h3')].filter(vis).map((h) => ({ tag: h.tagName.toLowerCase(), text: clean(h.innerText).slice(0, 100), ...pos(h) })),
     anchors: [...document.querySelectorAll('[id]')].filter((el) => vis(el) && el !== scroller && el.getBoundingClientRect().height > 150 &&
-      el.getBoundingClientRect().height < document.documentElement.scrollHeight * 0.8 && !/^(__|radix|headlessui|:)/.test(el.id))
-      .map((el) => ({ id: el.id, ...pos(el) })).slice(0, 30),
+      el.getBoundingClientRect().height < document.documentElement.scrollHeight * 0.8 && !/^(__|radix|headlessui|:)/.test(el.getAttribute('id')))
+      .map((el) => ({ id: el.getAttribute('id'), ...pos(el) })).slice(0, 30),
     images: [...document.querySelectorAll('img[alt]')].filter((el) => vis(el) && el.alt.trim()).map((el) => ({ alt: clean(el.alt).slice(0, 80), ...pos(el) })).slice(0, 30),
     interactive: [...interactive, ...pointer],
   };
@@ -160,7 +168,7 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
     '',
     '## Clickable elements — verified targets (each matches exactly one visible element) for click/move/zoom',
     '   Copy targets exactly; `name` is the accessible name, which may differ from the on-screen label.',
-    ...elements.map((e) => `${fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.role === 'slider' ? '  (slider — `slide: { target: …, to: 0..1 }`)' : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}`),
+    ...elements.map((e) => `${fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.role === 'slider' ? (e.range ? `  (slider ${e.range.lo}…${e.range.hi}, now ${e.range.now} — \`slide: { target: …, value: ${e.range.now} }\`)` : '  (slider — `slide: { target: …, to: 0..1 }`)') : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}`),
     '',
     '## Images with alt text (target: { alt: "..." })',
     ...(info.images.length ? info.images.map((i) => `${fold(i.y)} y=${i.y}\t"${i.alt}"`) : ['(none)']),

package/src/qwen-tts.mjs

@@ -22,15 +22,20 @@ const REPO = 'mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-bf16';
 const REVISION = '6415d95f88be018ff9e46813119dc3bc12261328';
 // 0.9 (the model's default) now and then runs on into made-up words; 0.7 keeps the same voice steadier
 const TEMPERATURE = 0.7;
+// Each take is checked by ear: Qwen3-ASR (Apache-2.0, ~1 GB) transcribes it, and a line it hears
+// differently is sampled again (pypinyin compares Chinese by sound, so homophones don't count)
+const ASR_REPO = 'mlx-community/Qwen3-ASR-0.6B-8bit';
+const ASR_REVISION = '89e96d92ba34aca20b3e29fb10cc284097d1219f';
 const REQUIREMENTS = ['mlx-audio==0.6.3', 'mlx==0.32.4', 'mlx-metal==0.32.4', 'transformers==5.22.0', 'huggingface-hub==2.4.0',
-  'tokenizers==0.23.3', 'safetensors==0.8.0', 'numpy==2.5.4'];
+  'tokenizers==0.23.3', 'safetensors==0.8.0', 'numpy==2.5.4', 'pypinyin==0.55.0'];
 // Part of every cached line's hash: change it when the model, the packages or qwen_tts.py's sampling change.
-export const QWEN_TTS_ID = `${REPO}@${REVISION.slice(0, 7)}|${REQUIREMENTS[0]}|t${TEMPERATURE}|guard-1`;
+export const QWEN_TTS_ID = `${REPO}@${REVISION.slice(0, 7)}|${REQUIREMENTS[0]}|t${TEMPERATURE}|guard-2|${ASR_REPO}@${ASR_REVISION.slice(0, 7)}`;
 const CACHE = path.join(os.homedir(), '.cache', 'storyshot');
 export const QWEN_VENV = path.join(CACHE, 'qwen-venv');
 const HELPER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'qwen_tts.py');
 const HUB = process.env.HF_HUB_CACHE ?? path.join(process.env.HF_HOME ?? path.join(os.homedir(), '.cache', 'huggingface'), 'hub');
 const MODEL_FILE = path.join(HUB, `models--${REPO.replace('/', '--')}`, 'snapshots', REVISION, 'model.safetensors');
+const ASR_FILE = path.join(HUB, `models--${ASR_REPO.replace('/', '--')}`, 'snapshots', ASR_REVISION, 'model.safetensors');
 
 // --- text (TTS only: subtitles keep the original) --------------------------------------------------
 // The model reads = + 2个 第2行 x² itself; a minus sign before a number it drops, and a number like
@@ -66,7 +71,7 @@ const NO_PYTHON = () => 'the Qwen3-TTS voice needs Python 3.10–3.12 to run (br
 // For doctor and check: can this machine use it, and what's still to come on first use?
 export function qwenStatus() {
   if (!qwenSupported()) return { supported: false };
-  const model = fs.existsSync(MODEL_FILE);
+  const model = fs.existsSync(MODEL_FILE) && fs.existsSync(ASR_FILE);
   if (venvReady()) return { supported: true, ready: true, venv: QWEN_VENV, model };
   const python = findPython();
   return { supported: true, ready: false, venv: QWEN_VENV, model, python, problem: python ? null : NO_PYTHON() };
@@ -74,13 +79,22 @@ export function qwenStatus() {
 
 function ensureVenv(log) {
   if (venvReady()) return venvPython(QWEN_VENV);
-  const py = findPython();
-  if (!py) throw new Error(NO_PYTHON());
-  log(`setting up the Qwen3-TTS voice (one time): a Python ${py.version} venv in ${QWEN_VENV} with mlx-audio (~400 MB, 1–2 min)…`);
   const run = (cmd, args, what) => {
     const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
     if (r.status !== 0) throw new Error(`${what} failed: ${(r.stderr || r.stdout || r.error?.message || '').trim().split('\n').slice(-6).join('\n')}`);
   };
+  if (fs.existsSync(venvPython(QWEN_VENV))) {
+    // a venv from an older storyshot: bring its packages up to date in place, rebuild it only if that fails
+    log(`updating the Qwen3-TTS venv in ${QWEN_VENV}…`);
+    try {
+      run(venvPython(QWEN_VENV), ['-m', 'pip', 'install', '--disable-pip-version-check', '--no-input', '-q', ...REQUIREMENTS], 'updating the venv');
+      fs.writeFileSync(path.join(QWEN_VENV, STAMP), REQUIREMENTS.join('\n'));
+      return venvPython(QWEN_VENV);
+    } catch (e) { log(`  ${e.message.split('\n')[0]} — rebuilding it`); }
+  }
+  const py = findPython();
+  if (!py) throw new Error(NO_PYTHON());
+  log(`setting up the Qwen3-TTS voice (one time): a Python ${py.version} venv in ${QWEN_VENV} with mlx-audio (~400 MB, 1–2 min)…`);
   fs.rmSync(QWEN_VENV, { recursive: true, force: true });
   fs.mkdirSync(CACHE, { recursive: true });
   run(py.exe, ['-m', 'venv', QWEN_VENV], `creating the venv with ${py.exe} -m venv`);
@@ -96,12 +110,13 @@ export async function synthQwen(v, entries, { log = console.log } = {}) {
   if (!qwenSupported()) throw new Error('the Qwen3-TTS voice runs on Apple Silicon Macs only (it uses MLX)');
   const py = ensureVenv(log);
   if (!fs.existsSync(MODEL_FILE)) log(`downloading the Qwen3-TTS model (one time, ~2.3 GB) into ${HUB}…`);
+  if (!fs.existsSync(ASR_FILE)) log(`downloading the Qwen3-ASR model that listens to each take (one time, ~1 GB) into ${HUB}…`);
   const lines = entries.map((e) => ({
     text: e.text, file: `${e.file}.raw.wav`, voice: v.voice, lang: qwenLang(e.text),
     // the same line gets the same take: a seed from the text
     seed: parseInt(crypto.createHash('sha1').update(e.text).digest('hex').slice(0, 7), 16),
   }));
-  const job = JSON.stringify({ repo: REPO, revision: REVISION, temperature: TEMPERATURE, lines });
+  const job = JSON.stringify({ repo: REPO, revision: REVISION, temperature: TEMPERATURE, asr: { repo: ASR_REPO, revision: ASR_REVISION }, lines });
   const { code, stdout, tail } = await new Promise((resolve, reject) => {
     const p = spawn(py, ['-I', HELPER], { env: { ...process.env, HF_HUB_DISABLE_TELEMETRY: '1', TRANSFORMERS_VERBOSITY: 'error' } });
     let out = '', err = '', buf = '';
@@ -121,9 +136,15 @@ export async function synthQwen(v, entries, { log = console.log } = {}) {
     p.stdin.end(job);
   });
   if (code !== 0) throw new Error(`Qwen3-TTS failed (${py} ${HELPER}): ${tail.trim().split('\n').slice(-8).join('\n')}`);
-  const { results } = JSON.parse(stdout);
+  const { results, asr } = JSON.parse(stdout);
+  if (asr) log(`  ⚠ qwen: the speech check couldn't load (${asr}), so these takes were checked by length only`);
   for (const [i, e] of entries.entries()) {
-    if (results[i]?.suspect) log(`  ⚠ qwen: "${e.text}" still sounds off after ${results[i].tries} tries (${results[i].seconds.toFixed(1)}s) — listen to it, or rephrase the line / add a pronounce entry`);
+    const r = results[i];
+    if (r?.suspect) {
+      log(r.heard != null && r.mismatch > 0
+        ? `  ⚠ qwen: "${e.text}" still doesn't come out right after ${r.tries} tries — it sounds like "${r.heard}". Listen to it; rephrase the line or add a pronounce entry`
+        : `  ⚠ qwen: "${e.text}" still sounds off after ${r.tries} tries (${r.seconds.toFixed(1)}s) — listen to it, or rephrase the line / add a pronounce entry`);
+    }
     const raw = lines[i].file, tmp = `${e.file}.tmp.wav`;
     // the model has no speed control: ffmpeg's pitch-preserving atempo does it
     if ((v.speed ?? 1) !== 1) execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', raw, '-af', `atempo=${v.speed}`, tmp]);

package/src/qwen_tts.py

@@ -1,13 +1,15 @@
 # Qwen3-TTS CustomVoice through mlx-audio (Apple Silicon), for `voice: { provider: qwen }`. Runs in
 # storyshot's own venv (qwen-tts.mjs), one process per render: the model loads once for all lines.
 #
-# stdin:  {"repo", "revision", "temperature", "lines": [{"text", "file", "voice", "lang", "seed"}]}
+# stdin:  {"repo", "revision", "temperature", "asr": {"repo", "revision"} | null,
+#          "lines": [{"text", "file", "voice", "lang", "seed"}]}
 # stderr: "line i/n <seconds>s [<tries> tries]" per line, plus whatever the libraries log
-# stdout: {"results": [{"seconds", "tries", "suspect"}]}
+# stdout: {"results": [{"seconds", "tries", "suspect", "heard", "mismatch"}], "asr": null | "why it didn't load"}
 #
-# The model samples its speech tokens, so now and then a line runs on into made-up words (a
-# scientific number like 2e-105 does it) or stops early. A take far longer or shorter than the text
-# should need is sampled again with another seed, and the closest one is kept.
+# The model samples its speech tokens, so now and then a take garbles a few words, drops one, runs on
+# into made-up words (a scientific number like 2e-105 does it) or stops early. Each take is checked:
+# its length against the text, and what a speech recognizer (Qwen3-ASR) hears in it against the text.
+# A take that fails is sampled again with another seed, and the best one is kept.
 import contextlib
 import json
 import os
@@ -18,6 +20,10 @@ os.environ.setdefault('HF_HUB_DISABLE_TELEMETRY', '1')
 os.environ.setdefault('TRANSFORMERS_VERBOSITY', 'error')
 
 TRIES = 4
+# a take is sampled again when the recognizer hears this share of the line differently, or this long a run
+# of mistakes in a row (a garble: 负 2 x → 负二长方荡 is 2.5); a warning if every take is still off
+RETRY_AT, RETRY_RUN = 0.10, 2
+WARN_AT, WARN_RUN = 0.15, 2
 
 
 def expected(text):
@@ -32,6 +38,87 @@ def plausible(seconds, est):
     return 0.35 * est - 0.5 <= seconds <= 2.0 * est + 2.0
 
 
+# --- what was said vs. what was meant ---------------------------------------------------------------
+# Chinese is compared by sound (toneless pinyin), so a homophone the recognizer picks (交点/焦点) is no
+# mistake; numbers are read out first (0.5 → 零点五, 2 → 二), since the recognizer writes either form.
+DIGITS = '零一二三四五六七八九'
+
+
+def cn_int(n):
+    if n >= 10 ** 8:
+        return ''.join(DIGITS[int(c)] for c in str(n))
+
+    def four(x):
+        out, zero = '', False
+        for i, c in enumerate(f'{x:04d}'):
+            d = int(c)
+            if d == 0:
+                zero = bool(out)
+            else:
+                out += ('零' if zero else '') + DIGITS[d] + ['千', '百', '十', ''][i]
+                zero = False
+        return out
+
+    if n < 10:
+        return DIGITS[n]
+    hi, lo = divmod(n, 10000)
+    out = (four(hi) + '万' if hi else '') + (('零' if hi and lo < 1000 else '') + four(lo) if lo else '')
+    return re.sub('^一十', '十', out)
+
+
+def cn_number(m):
+    whole, _, frac = m.group().partition('.')
+    return cn_int(int(whole)) + ('点' + ''.join(DIGITS[int(c)] for c in frac) if frac else '')
+
+
+def units(text, chinese, pinyin):
+    """The line as a list of sounds: pinyin syllables, digits, and Latin words as '#word' (m x and mx as '#m', '#x')."""
+    t = text.lower().replace('−', '-')
+    if chinese:
+        t = re.sub(r'\d+(?:\.\d+)?', cn_number, t)
+    out = []
+    for tok in re.findall(r'[㐀-鿿]|[a-z]+|\d+', t):
+        if chinese and re.match(r'[㐀-鿿]', tok):
+            out += [{'liang': 'er'}.get(p, p) for p in pinyin(tok)]
+        elif tok.isdigit():
+            out += list(tok)  # digit by digit: a wrong number (260 → 45) is several mistakes in a row, not one
+        else:
+            out += ['#' + c for c in tok] if len(tok) <= 2 else ['#' + tok]
+    return out
+
+
+def mismatch(text, heard, chinese, pinyin):
+    """(share of the line heard differently, the longest run of mistakes in a row), both in units of the
+    text. A garbled take has a run of several; a homophone or a misheard letter is one on its own."""
+    a, b = units(text, chinese, pinyin), units(heard, chinese, pinyin)
+    letter = lambda u: len(u) == 2 and u[0] == '#'
+    d = {(0, 0): (0, None)}
+    for i in range(len(a) + 1):
+        for j in range(len(b) + 1):
+            if i == j == 0:
+                continue
+            ways = []
+            if i:
+                ways.append((d[i - 1, j][0] + 1, (i - 1, j, 1)))
+            if j:
+                ways.append((d[i, j - 1][0] + 1, (i, j - 1, 1)))
+            if i and j:
+                x, y = a[i - 1], b[j - 1]
+                # a variable (m, b, x) the recognizer wrote as a character is half a mistake
+                cost = 0 if x == y else 0.5 if letter(x) or letter(y) else 1
+                ways.append((d[i - 1, j - 1][0] + cost, (i - 1, j - 1, cost)))
+                # a name in Latin letters in a Chinese line (Desmos) can come back as a few syllables: one mistake
+                if chinese and len(x) > 3 and x[0] == '#':
+                    ways += [(d[i - 1, j - k][0] + 1, (i - 1, j - k, 1)) for k in range(2, min(5, j) + 1)]
+            d[i, j] = min(ways, key=lambda w: w[0])
+    i, j, run, worst = len(a), len(b), 0, 0
+    while (i, j) != (0, 0):
+        i, j, cost = d[i, j][1]
+        run = run + cost if cost else 0
+        worst = max(worst, run)
+    return d[len(a), len(b)][0] / max(1, len(a)), worst
+
+
 def main():
     job = json.load(sys.stdin)
     out = sys.stdout
@@ -45,6 +132,28 @@ def main():
         from mlx_audio.tts.utils import load_model
 
         model = load_model(snapshot_download(job['repo'], revision=job['revision']))
+        asr, asr_error, pinyin = None, None, None
+        if job.get('asr'):
+            try:
+                from mlx_audio.stt.utils import load_model as load_stt
+                from pypinyin import lazy_pinyin as pinyin
+                asr = load_stt(snapshot_download(job['asr']['repo'], revision=job['asr']['revision']))
+            except Exception as e:  # offline before the first download, say: check by length only
+                asr_error = f'{type(e).__name__}: {e}'.splitlines()[0][:300]
+
+        def hear(audio, line):
+            """(what the recognizer heard, mismatch), or (None, None) for a line it can't check."""
+            chinese = line['lang'] == 'chinese'
+            if asr is None or not (chinese or (line['lang'] == 'auto' and not re.search(r'[㐀-鿿]', line['text']))):
+                return None, None
+            tmp = line['file'] + '.check.wav'
+            write(tmp, audio, model.sample_rate)
+            try:
+                heard = asr.generate(tmp, language='Chinese' if chinese else 'English').text.strip()
+            finally:
+                os.remove(tmp)
+            return heard, mismatch(line['text'], heard, chinese, pinyin)
+
         results, n = [], len(job['lines'])
         for i, line in enumerate(job['lines']):
             est = expected(line['text'])
@@ -55,15 +164,22 @@ def main():
                                        temperature=job['temperature'])
                 audio = np.concatenate([np.array(r.audio, dtype=np.float32) for r in parts])
                 seconds = len(audio) / model.sample_rate
-                score = abs(math.log(max(seconds, 0.1) / est))
-                if best is None or score < best[0]:
-                    best = (score, audio, seconds)
-                if plausible(seconds, est):
+                fits = plausible(seconds, est)
+                heard, m = hear(audio, line) if fits else (None, None)
+                # how far off the recognizer heard it: up to 1 is fine (0 when it couldn't check)
+                worse = max(m[0] / RETRY_AT, m[1] / RETRY_RUN) if m else 0
+                # a take of the right length that says the line beats one that doesn't; then the closest length
+                rank = (not fits, worse if worse > 1 else 0, abs(math.log(max(seconds, 0.1) / est)))
+                if best is None or rank < best['rank']:
+                    best = {'rank': rank, 'audio': audio, 'seconds': seconds, 'fits': fits, 'heard': heard, 'm': m}
+                if fits and worse <= 1:
                     break
-            write(line['file'], best[1], model.sample_rate)
-            results.append({'seconds': best[2], 'tries': k + 1, 'suspect': not plausible(best[2], est)})
-            print(f'line {i + 1}/{n} {best[2]:.1f}s' + (f' {k + 1} tries' if k else ''), file=sys.stderr, flush=True)
-    out.write(json.dumps({'results': results}))
+            write(line['file'], best['audio'], model.sample_rate)
+            m = best['m']
+            results.append({'seconds': best['seconds'], 'tries': k + 1, 'heard': best['heard'], 'mismatch': m and m[0],
+                            'suspect': not best['fits'] or bool(m and (m[0] > WARN_AT or m[1] > WARN_RUN))})
+            print(f'line {i + 1}/{n} {best["seconds"]:.1f}s' + (f' {k + 1} tries' if k else ''), file=sys.stderr, flush=True)
+    out.write(json.dumps({'results': results, 'asr': asr_error}))
 
 
 if __name__ == '__main__':

package/src/record.mjs

@@ -55,19 +55,60 @@ function pageScript({ scrollOffset }) {
     for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) if (scrollable(p)) return p;
     return docEl();
   };
+  // `behavior: 'instant'` on every frame: with `scroll-behavior: smooth` in the page's CSS (GitHub has it),
+  // plain scrollTop writes each start a smooth scroll of their own, so the page lags behind and is still
+  // moving after the step that scrolled it is over
   window.__demoScrollBy = (dy, ms = 1200, sc = mainScroller()) => new Promise((done) => {
     const start = sc.scrollTop, t0 = performance.now();
     const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
     const step = (now) => {
-      const k = Math.min(1, (now - t0) / ms);
-      sc.scrollTop = start + dy * ease(k);
+      const k = ms > 0 ? Math.min(1, Math.max(0, (now - t0) / ms)) : 1;
+      sc.scrollTo({ top: start + dy * ease(k), behavior: 'instant' });
       if (k < 1) requestAnimationFrame(step); else done();
     };
     requestAnimationFrame(step);
   });
+  // How far down a header will cover the window once `el` is scrolled to the top: bars fixed at the top,
+  // and sticky ones that stick inside a box holding `el` (GitHub's README bar sticks within the README).
+  const headerCover = (el) => {
+    let cover = 0;
+    for (const h of document.querySelectorAll('body *')) {
+      if (h.getAttribute('id')?.startsWith('__demo') || h.contains(el)) continue; // not h.id: a form with an <input name=id> has that input as its .id
+      const cs = getComputedStyle(h);
+      if (cs.position !== 'fixed' && cs.position !== 'sticky') continue;
+      const r = h.getBoundingClientRect();
+      if (!r.height || r.height > innerHeight * 0.3 || r.width < innerWidth * 0.3 || cs.visibility === 'hidden' || cs.opacity === '0') continue;
+      if (cs.position === 'fixed' && r.top <= 1) cover = Math.max(cover, r.bottom);
+      const stick = parseFloat(cs.top);
+      if (cs.position === 'sticky' && !Number.isNaN(stick) && stick < innerHeight * 0.3 && h.parentElement?.contains(el)) cover = Math.max(cover, stick + r.height);
+    }
+    return cover;
+  };
+  // the element's top lands `scrollOffset` px down, or just below a header that would cover it there
   window.__demoScrollTo = (el, ms) => {
-    const sc = scrollerFor(el), top = sc === docEl() ? 0 : sc.getBoundingClientRect().top;
-    return window.__demoScrollBy(el.getBoundingClientRect().top - top - scrollOffset, ms, sc);
+    const sc = scrollerFor(el), docs = sc === docEl(), top = docs ? 0 : sc.getBoundingClientRect().top;
+    const offset = docs ? Math.max(scrollOffset, headerCover(el) + 12) : scrollOffset;
+    return window.__demoScrollBy(el.getBoundingClientRect().top - top - offset, ms, sc);
+  };
+  // resolves once nothing has scrolled for a few frames (the page's own smooth scrolling included)
+  window.__demoScrollIdle = (max = 2000) => new Promise((done) => {
+    const sc = mainScroller(), pos = () => `${scrollX},${scrollY},${sc.scrollTop}`;
+    const end = performance.now() + max;
+    let last = pos(), still = 0;
+    const check = () => {
+      const now = pos();
+      still = now === last ? still + 1 : 0; last = now;
+      if (still >= 3 || performance.now() > end) done(); else requestAnimationFrame(check);
+    };
+    requestAnimationFrame(check);
+  });
+  // a slider's value and range: an <input type=range>, or an ARIA slider (Desmos: [role=slider] on its knob)
+  window.__demoSliderValue = (el) => {
+    const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
+    if (r) return { now: Number(r.value), lo: Number(r.min || 0), hi: Number(r.max || 100), native: r };
+    const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
+    const now = Number(aria?.getAttribute('aria-valuenow'));
+    return aria && Number.isFinite(now) ? { now, lo: Number(aria.getAttribute('aria-valuemin') ?? 0), hi: Number(aria.getAttribute('aria-valuemax') ?? 100) } : null;
   };
   // Tutorial callouts: spotlight a target, show a pressed key combo.
   window.__demoSpot = (r) => {
@@ -86,9 +127,10 @@ function pageScript({ scrollOffset }) {
     Object.assign(el.style, { left: `${r.x - pad}px`, top: `${r.y - pad}px`, width: `${r.width + 2 * pad}px`, height: `${r.height + 2 * pad}px` });
     requestAnimationFrame(() => { el.style.opacity = '1'; });
   };
-  window.__demoSpotOff = () => {
+  window.__demoSpotOff = (instant) => {
     const el = document.getElementById('__demo_spot');
-    if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
+    if (el && instant) el.remove();
+    else if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
   };
   window.__demoKeys = (label) => {
     const el = document.createElement('div');
@@ -424,7 +466,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await sleep(280);
     return true;
   }
-  const spotOff = () => page.evaluate(() => window.__demoSpotOff()).catch(() => {});
+  const spotOff = (instant) => page.evaluate((i) => window.__demoSpotOff(i), !!instant).catch(() => {});
   const keyLabel = (k) => k.split('+').map((p) => ({ Meta: '⌘', ControlOrMeta: '⌘', Control: 'Ctrl', Shift: '⇧', Alt: '⌥', Enter: '↵ Enter', Escape: 'Esc', Backspace: '⌫', Tab: '⇥ Tab' })[p] ?? (p.length === 1 ? p.toUpperCase() : p)).join(' ');
 
   async function runAction(action) {
@@ -473,6 +515,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       case 'scrollTo': {
         const h = await locate(page, spec).elementHandle({ timeout: opt.timeout ?? 15000 });
         await page.evaluate(([el, ms]) => window.__demoScrollTo(el, ms), [h, opt.ms ?? 1200]);
+        // where it landed: a zoom on the same target frames it there, not where it was before the scroll
+        const b = await h.boundingBox().catch(() => null);
+        if (b) boxes.set(keyOf(spec), b);
         break;
       }
       case 'scroll': await page.evaluate(([dy, ms]) => window.__demoScrollBy(dy, ms), [value.y ?? value, value.ms ?? 1000]); break;
@@ -570,25 +615,28 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       }
       case 'slide': {
         // slide: { target: <slider>, to: 0.2 } — drag a slider to a position along its track (0 = start,
-        // 1 = end), found from the element instead of pixel positions that break when the layout moves
-        if (!value?.target || typeof value?.to !== 'number') throw new Error('slide needs { target: <slider>, to: 0..1 }');
+        // 1 = end), or { target, value: 3 } — to a value, for sliders that report their range; found from
+        // the element instead of pixel positions that break when the layout moves
+        if (!value?.target || (typeof value?.to !== 'number' && typeof value?.value !== 'number')) throw new Error('slide needs { target: <slider>, to: 0..1 } or { target: <slider>, value: <number> }');
         const p = await pointOf(value.target, value);
-        const b = p.box;
-        const from = await locate(page, value.target).evaluate((el) => {
-          const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
-          if (r) return (Number(r.value) - Number(r.min || 0)) / ((Number(r.max || 100) - Number(r.min || 0)) || 1);
-          const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
-          if (aria) {
-            const now = Number(aria.getAttribute('aria-valuenow')), lo = Number(aria.getAttribute('aria-valuemin') ?? 0), hi = Number(aria.getAttribute('aria-valuemax') ?? 100);
-            if (Number.isFinite(now)) return (now - lo) / ((hi - lo) || 1);
+        const s = await locate(page, value.target).evaluate((el) => {
+          // a knob (Desmos's [role=slider] is its 38 px thumb): slide along its track, the nearest wide parent
+          let track = el;
+          const w = el.getBoundingClientRect().width;
+          for (let a = el.parentElement, i = 0; w < 60 && a && i < 4; a = a.parentElement, i++) if (a.getBoundingClientRect().width >= 3 * w) { track = a; break; }
+          const t = track.getBoundingClientRect(), v = window.__demoSliderValue(el);
+          let from = v ? (v.now - v.lo) / ((v.hi - v.lo) || 1) : null;
+          if (from == null) {
+            // custom sliders: start where the knob is drawn, so the value doesn't jump first
+            const knob = [...track.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
+              .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
+            from = knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
           }
-          // custom sliders (e.g. Desmos): start where the knob is drawn, so the value doesn't jump first
-          const t = el.getBoundingClientRect();
-          const knob = [...el.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
-            .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
-          return knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
-        }).catch(() => 0.5);
-        const x0 = b.x + b.width * from, x1 = b.x + b.width * Math.max(0, Math.min(1, value.to)), y = b.y + b.height / 2;
+          return { box: { x: t.x, y: t.y, width: t.width, height: t.height }, from, range: v && { lo: v.lo, hi: v.hi } };
+        }).catch(() => ({ box: p.box, from: 0.5, range: null }));
+        if (typeof value.value === 'number' && !s.range) throw new Error('slide value: this slider doesn\'t report its range (no aria-valuemin/max, not an <input type=range>) — use to: 0..1');
+        const to = typeof value.value === 'number' ? (value.value - s.range.lo) / ((s.range.hi - s.range.lo) || 1) : value.to;
+        const b = s.box, x0 = b.x + b.width * s.from, x1 = b.x + b.width * Math.max(0, Math.min(1, to)), y = b.y + b.height / 2;
         await moveTo(x0, y, value.ms ?? cfg.pace.cursor);
         await sleep(120);
         clicks.push(now());
@@ -596,6 +644,19 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         await moveTo(x1, y, value.dragMs ?? 900);
         await sleep(120);
         await page.mouse.up();
+        if (typeof value.value === 'number') {
+          // a native range's thumb doesn't reach the ends of its box, so the drag can land a step off: set it
+          const got = await locate(page, value.target).evaluate((el, want) => {
+            const v = window.__demoSliderValue(el), r = v?.native;
+            if (r && v.now !== want) {
+              Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(r, String(want));
+              r.dispatchEvent(new Event('input', { bubbles: true })); r.dispatchEvent(new Event('change', { bubbles: true }));
+              return Number(r.value);
+            }
+            return v?.now;
+          }, value.value).catch(() => null);
+          if (got != null && Math.abs(got - value.value) > 1e-9) log(`  ⚠ ${acting}: slide stopped at ${got}, not ${value.value} — the slider snaps to its step`);
+        }
         await settle();
         await beat();
         break;
@@ -608,11 +669,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         let box = null;
         const phraseOnly = v.text && Object.keys(v).every((k) => ['text', 'exact'].includes(k));
         if (phraseOnly) {
+          await page.evaluate(() => window.__demoScrollIdle()).catch(() => {}); // judge "in view" where the page ends up
           const found = await page.evaluate((t) => window.__demoFind(t), v.text);
-          if (found && !found.inView) {
-            await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
-            await sleep(fast ? 50 : 950);
-          }
+          if (found && !found.inView) await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
           if (found) box = await page.evaluate(([ms, color, b]) => window.__demoMark('found', { ms, color, box: b }), [ms, color, opt.box ?? false]);
         }
         if (!box) {
@@ -659,7 +718,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
 
   // --- setup (not recorded) -----------------------------------------------------------
   // Run a list of actions; on failure, say exactly which one and save a screenshot.
+  let acting = '';
   async function runAll(actions, where) {
+    acting = where;
     for (const [j, a] of actions.entries()) {
       try {
         // watchdog: an action that hangs (a frozen page, a stalled browser) fails with a clear message
@@ -759,9 +820,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const n = Math.min(inspectAfter, cfg.steps.length);
     for (const [i, s] of cfg.steps.slice(0, n).entries()) {
       stepHighlight = false;
-      // like the recording: marks and notes end with their step (the last step's stay in the screenshot)
-      if (i > 0) await page.evaluate(() => { window.__demoUnmark(); window.__demoUnnote(); }).catch(() => {});
+      // like the recording: marks, notes and spotlights end with their step (the last step's stay in the screenshot)
+      if (i > 0) await page.evaluate(() => { window.__demoUnmark(true); window.__demoUnnote(true); window.__demoSpotOff(true); }).catch(() => {});
       await runAll(s.actions, `step ${i + 1}`);
+      await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     }
     await sleep(800);
     const shot = path.join(cfg.work, `inspect-after-${n}.jpg`);
@@ -804,10 +866,14 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const zoomTarget = s.zoom?.target && !isPoint(s.zoom.target);
     const startBox = zoomTarget ? await boxNow() : null;
     await runAll(s.actions, `step ${i + 1}`);
+    // a scroll still running (the page's own smooth scrolling) ends in this step, not in the next one's first shot
+    await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     const end = now(); // before clearing: a step that is held for its narration keeps its marks
-    await spotOff();
-    // docs clips start where the step starts: clear at once, so no fading callout leaks into the next clip
-    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, cfg.clips.length > 0).catch(() => {});
+    // docs clips start where the step starts, and a hidden step is cut: clear at once, so no fading
+    // callout leaks into the next shot
+    const instant = cfg.clips.length > 0 || !!s.hidden;
+    await spotOff(instant);
+    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, instant).catch(() => {});
     let zoomBox = null;
     if (s.zoom?.target) {
       if (isPoint(s.zoom.target)) {

package/src/voice.mjs

@@ -118,8 +118,29 @@ function cached(cfg, line) {
   return { text, file: path.join(dir, `${hash}.${ext}`), zh, qwen };
 }
 
-// Returns stereo Float32 PCM at 48 kHz with leading/trailing silence trimmed.
-export async function speak(cfg, line, { log = console.log } = {}) {
+// A line's sentences, so each is spoken on its own with a pause after it (TTS engines run the
+// sentences of one line together with barely a breath). Latin text breaks after . ! ? when a capital,
+// digit or quote follows, but not after e.g., Dr., a lone initial (N. P. X.), 2.5 or myapp.com;
+// Chinese and Japanese after 。！？.
+const ABBREV = /^(e\.g|i\.e|etc|vs|approx|incl|cf|Mr|Mrs|Ms|Dr|Prof|St|No|Fig)\.$/i;
+export function sentences(text) {
+  const s = String(text).replace(/\s+/g, ' ').trim(), out = [];
+  const re = /([.!?…]+["'”’)\]]*) +(?=["'“‘(\[]?[\p{Lu}\p{N}\p{Lo}])|([。！？]+[”’」』)）]*) */gu;
+  let from = 0;
+  for (let m; (m = re.exec(s));) {
+    if (m[1]) {
+      const word = s.slice(from, m.index + 1).match(/(\S+)$/)?.[1] ?? '';
+      if (ABBREV.test(word) || /^\p{Lu}\.$/u.test(word)) continue;
+    }
+    const piece = s.slice(from, m.index + (m[1] ?? m[2]).length).trim();
+    if (piece) out.push(piece);
+    from = re.lastIndex;
+  }
+  if (s.slice(from).trim()) out.push(s.slice(from).trim());
+  return out;
+}
+// One line as stereo Float32 PCM at 48 kHz, leading and trailing silence trimmed.
+async function speakLine(cfg, line, log) {
   const v = cfg.voice;
   const { text, file, zh, qwen } = cached(cfg, line);
   if (!fs.existsSync(file)) {
@@ -135,6 +156,80 @@ export async function speak(cfg, line, { log = console.log } = {}) {
   return new Float32Array(pcm.buffer, pcm.byteOffset, pcm.length / 4);
 }
 
+// Where a line's sentences meet in its audio. Every break in the text (sentence ends, and commas,
+// which voices pause at too) gets an expected time from the letters spoken before it; each quiet
+// stretch belongs to the break it is nearest, and a sentence end takes the longest stretch that is
+// its own, so a long pause at a comma is never mistaken for it. [start, end] in samples per channel,
+// or null when the voice runs straight on (no quiet there to widen).
+const WIN = SR / 100; // 10 ms
+const letters = (s) => (s.match(/[\p{L}\p{N}]/gu) ?? []).length;
+export function sentenceGaps(pcm, sents) {
+  const n = Math.floor(pcm.length / 2 / WIN), env = new Float32Array(n);
+  let peak = 0;
+  for (let w = 0; w < n; w++) {
+    let e = 0;
+    for (let i = w * WIN; i < (w + 1) * WIN; i++) e = Math.max(e, Math.abs(pcm[2 * i]), Math.abs(pcm[2 * i + 1]));
+    env[w] = e; peak = Math.max(peak, e);
+  }
+  const quiet = [], thr = peak * 0.02;
+  for (let w = 0; w < n;) {
+    if (env[w] >= thr) { w++; continue; }
+    const a = w;
+    while (w < n && env[w] < thr) w++;
+    if (w - a >= 4 && a > 0 && w < n) quiet.push([a, w]); // ≥ 40 ms, not the trimmed ends
+  }
+  // breaks in the text, at the share of letters spoken before them: { at, end: k } for the end of sentence k
+  const total = letters(sents.join(' ')) || 1, breaks = [];
+  let before = 0;
+  for (const [k, s] of sents.entries()) {
+    for (const m of s.matchAll(/[,;:，、；：]/g)) breaks.push({ at: (before + letters(s.slice(0, m.index))) / total });
+    before += letters(s);
+    if (k < sents.length - 1) breaks.push({ at: before / total, end: k });
+  }
+  const mine = sents.slice(0, -1).map(() => []);
+  for (const q of quiet) {
+    const mid = (q[0] + q[1]) / 2 / n;
+    const b = breaks.reduce((x, y) => (Math.abs(y.at - mid) < Math.abs(x.at - mid) ? y : x));
+    if (b.end != null && Math.abs(b.at - mid) < 0.25) mine[b.end].push(q);
+  }
+  let after = 0;
+  return mine.map((qs) => {
+    const best = qs.filter((q) => q[0] >= after).reduce((x, q) => (!x || q[1] - q[0] > x[1] - x[0] ? q : x), null);
+    if (!best) return null;
+    after = best[1];
+    return [best[0] * WIN, best[1] * WIN];
+  });
+}
+
+// A line as stereo Float32 PCM at 48 kHz, spoken in one go (so the voice keeps its flow from sentence
+// to sentence), with each pause between sentences widened to at least `voice.pause` seconds: voices
+// often run sentences together with barely a breath. parts: where each sentence is, in seconds (for
+// subtitles).
+export async function speak(cfg, line, { log = console.log } = {}) {
+  const raw = await speakLine(cfg, line, log), pause = cfg.voice.pause ?? 0;
+  const sents = pause > 0 ? sentences(line) : [];
+  if (sents.length < 2) return { pcm: raw, parts: [{ text: line, start: 0, end: raw.length / 2 / SR }] };
+  const gaps = sentenceGaps(raw, sents), want = Math.round(pause * SR);
+  const add = gaps.map((g) => (g ? Math.max(0, want - (g[1] - g[0])) : 0));
+  const pcm = new Float32Array(raw.length + 2 * add.reduce((a, b) => a + b, 0));
+  const parts = [];
+  let from = 0, to = 0, startAt = 0;
+  for (const [k, g] of gaps.entries()) {
+    if (!g) continue; // no quiet stretch: this sentence runs on into the next
+    const mid = Math.round((g[0] + g[1]) / 2);
+    pcm.set(raw.subarray(2 * from, 2 * mid), 2 * to);
+    to += mid - from; from = mid;
+    const end = to - (mid - g[0]);
+    to += add[k]; // silence: the array is zero-filled
+    parts.push({ text: sents.slice(parts.length ? parts.at(-1).next : 0, k + 1).join(' '), start: startAt / SR, end: end / SR, next: k + 1 });
+    startAt = to + (g[1] - mid);
+  }
+  pcm.set(raw.subarray(2 * from), 2 * to);
+  const last = parts.length ? parts.at(-1).next : 0;
+  parts.push({ text: sents.slice(last).join(' '), start: startAt / SR, end: pcm.length / 2 / SR, next: sents.length });
+  return { pcm, parts: parts.map(({ next, ...p }) => p) };
+}
+
 // Speed a clip up (factor > 1) with ffmpeg's pitch-preserving atempo.
 export function tempo(pcm, factor) {
   if (!(factor >= 0.5 && factor <= 100)) throw new Error(`internal: speed factor ${factor} is outside what ffmpeg's atempo accepts (0.5–100)`);
@@ -146,6 +241,7 @@ export function tempo(pcm, factor) {
 // Synthesize every narration line up front and return their lengths (seconds),
 // so `duration: auto` steps can be timed to the voice.
 export async function measureVoice(cfg, { log = console.log } = {}) {
+  const seconds = ({ pcm }) => pcm.length / 2 / SR;
   const lens = { steps: {}, endCard: null, intro: null, cards: {} };
   if (!cfg.voice) return lens;
   if (cfg.voice.fallback) log(`note: ${cfg.voice.fallback}`);
@@ -157,10 +253,10 @@ export async function measureVoice(cfg, { log = console.log } = {}) {
     await (zh ? synthZh : synthQwen)(cfg.voice, [...todo.values()], { log });
   }
   for (const [i, s] of cfg.steps.entries()) {
-    if (s.say && !s.hidden) lens.steps[i] = (await speak(cfg, s.say, { log })).length / 2 / SR;
-    if (s.card?.say && !s.hidden) lens.cards[i] = (await speak(cfg, s.card.say, { log })).length / 2 / SR;
+    if (s.say && !s.hidden) lens.steps[i] = seconds(await speak(cfg, s.say, { log }));
+    if (s.card?.say && !s.hidden) lens.cards[i] = seconds(await speak(cfg, s.card.say, { log }));
   }
-  if (cfg.intro?.say) lens.intro = (await speak(cfg, cfg.intro.say, { log })).length / 2 / SR;
-  if (cfg.endCard?.say) lens.endCard = (await speak(cfg, cfg.endCard.say, { log })).length / 2 / SR;
+  if (cfg.intro?.say) lens.intro = seconds(await speak(cfg, cfg.intro.say, { log }));
+  if (cfg.endCard?.say) lens.endCard = seconds(await speak(cfg, cfg.endCard.say, { log }));
   return lens;
 }