storyshot 0.5.0 → 0.7.0

package/README.md

@@ -153,6 +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`); 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` |
 
@@ -190,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
@@ -247,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)
@@ -286,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
@@ -331,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
@@ -374,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. |
 
@@ -394,9 +395,10 @@ mix is normalized to -14 LUFS.
 | provider | key (env or `.env`) | notes |
 |---|---|---|
 | `kokoro` (default) | none | Local and free. English voices (`af_heart`, `am_michael`, `bf_emma`, …) and Mandarin Chinese ones (`zf_001`, see below). Needs `npm i kokoro-js`; the first run downloads an ~90 MB model. |
+| `qwen` | none | Local and free, Apple Silicon Macs only: Qwen3-TTS, the most natural free Chinese voice here (`dylan`, `serena`, see below). |
 | `elevenlabs` | `ELEVENLABS_API_KEY` | Most natural, many languages including Chinese. `voice` is a voice ID; `model` defaults to `eleven_multilingual_v2`. The key needs Text to Speech access, plus Voices → Read to list voices. |
 | `openai` | `OPENAI_API_KEY` | `voice: alloy`, `model: gpt-4o-mini-tts`; optional `instructions` for tone. |
-| `say` | none | macOS built-in voices, robotic; fine for drafts. For Chinese, use `kokoro` with `zf_001` rather than `Tingting`. |
+| `say` | none | macOS built-in voices, robotic; fine for drafts. For Chinese, use `qwen` (Apple Silicon) or `kokoro` with `zf_001` rather than `Tingting`. |
 
 **Chinese narration.** `voice: { provider: kokoro, voice: zf_001 }` speaks Mandarin with Kokoro
 v1.1-zh, free and local, and is what `kokoro` uses when the `say:` lines are Chinese and no voice is
@@ -409,8 +411,28 @@ whether it's ready. English words and letters in a line (`GeoGebra`, `y 等于 m
 English, a 2 before a measure word is read 两 (`2 个单位`), and `=`, `+`, `×`, `÷`, `²` are spoken;
 subtitles keep the line as written. Known issue: with every Kokoro voice, 逗号 can sound like 度号.
 
-Other fields: `speed` (default 1), `volume` (default 1), and `pronounce`, a
-map of word → spoken form used only for TTS, e.g.
+**Chinese on an Apple Silicon Mac: Qwen3-TTS.** `voice: { provider: qwen }` speaks with
+[Qwen3-TTS 0.6B CustomVoice](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice) (Apache-2.0)
+through [mlx-audio](https://github.com/Blaizzy/mlx-audio). It reads English words, letters and numbers
+in a Chinese line more reliably than `zf_001`. Voices: `dylan` (male, Beijing accent; the default
+for Chinese tutorials, lessons and docs), `serena` (female, warm; the default for Chinese promos),
+`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 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), `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
@@ -443,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
@@ -469,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.5.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

@@ -88,8 +88,16 @@ frames or stock footage presented as a recording of their app.
    and Mandarin Chinese: for Chinese lines use `voice: { provider: kokoro,
    voice: zf_001 }` (the default for Chinese `say:` lines), not macOS `say -v
    Tingting`, which sounds robotic. It needs Python 3.10–3.12 and sets up its
-   own venv on first use (`doctor` reports it). For other languages, use
-   ElevenLabs.
+   own venv on first use (`doctor` reports it). On an Apple Silicon Mac, the
+   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, ~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
      there, preferably with a demo account (the video shows whatever is on
@@ -179,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,
@@ -201,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.**
@@ -220,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

@@ -4,6 +4,35 @@ import YAML from 'yaml';
 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'];
@@ -106,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') {
@@ -145,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;
@@ -157,12 +186,27 @@ 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)) {
       const zh = zhVoiceStatus();
       if (zh.problem) errors.push(zh.problem);
     }
+    if (v?.provider === 'qwen') {
+      const q = qwenStatus();
+      if (q.problem) errors.push(q.problem);
+    }
+    if (v?.fallback) warnings.push(v.fallback);
     if (!draft && cfg.voice && ['elevenlabs', 'openai'].includes(cfg.voice.provider)) {
       const env = cfg.voice.provider === 'elevenlabs' ? 'ELEVENLABS_API_KEY' : 'OPENAI_API_KEY';
       if (!process.env[env]) errors.push(`voice provider ${cfg.voice.provider} needs ${env} (environment or a .env file next to the storyboard) — or render with draft mode to use the free local 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

@@ -2,7 +2,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
-import { VOICE_DEFAULTS, kokoroVoiceFor } from './voice.mjs';
+import { VOICE_DEFAULTS, kokoroVoiceFor, qwenVoiceFor } from './voice.mjs';
+import { QWEN_VOICES, qwenSupported, qwenVoice } from './qwen-tts.mjs';
 
 // Built-in labels drawn into the video, by `lang` (e.g. es, es-MX); other languages get English
 export const LABELS = {
@@ -30,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 →
@@ -42,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'];
@@ -137,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');
@@ -148,10 +151,23 @@ export function loadConfig(file, { draft = false } = {}) {
     const provider = raw.voice.provider ?? 'kokoro';
     if (!VOICE_DEFAULTS[provider]) throw new Error(`voice.provider must be one of ${Object.keys(VOICE_DEFAULTS).join(', ')}`);
     const pace0 = PACES[pick('pace')] ?? PACES.normal;
-    // kokoro's default voice follows the narration's language (zf_001 for Chinese, af_heart otherwise)
+    // kokoro's and qwen's default voices follow the narration's language (zf_001 / serena for Chinese)
     const kokoroVoice = kokoroVoiceFor(raw);
-    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...(provider === 'kokoro' ? { voice: kokoroVoice } : {}), ...raw.voice, provider };
-    if (draft && provider !== 'kokoro') {
+    const byLang = { kokoro: kokoroVoice, qwen: qwenVoiceFor(raw) }[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(', ')})`);
+      voice.voice = v;
+      // MLX needs Apple Silicon: anywhere else the same storyboard renders with kokoro
+      if (!qwenSupported()) {
+        const k = raw.voice.draftVoice ?? kokoroVoice;
+        voice = { ...voice, provider: 'kokoro', voice: k, fallback: `the qwen voice needs an Apple Silicon Mac; using kokoro ${k} instead` };
+      }
+    }
+    // free local voices stay; a paid one is swapped for kokoro
+    if (draft && !['kokoro', 'qwen'].includes(voice.provider)) {
       voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? kokoroVoice, model: undefined };
     }
   }
@@ -201,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

@@ -7,6 +7,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { hasFilter, hasEncoder, NEEDED, OPTIONAL } from './ffmpeg.mjs';
 import { zhVoiceStatus } from './kokoro-zh.mjs';
+import { qwenStatus } from './qwen-tts.mjs';
 import { hyperframesCli, HF_VERSION } from './hyperframes.mjs';
 
 const has = (cmd, args = ['--version']) => { try { execFileSync(cmd, args, { stdio: 'ignore' }); return true; } catch { return false; } };
@@ -78,6 +79,11 @@ export async function doctor({ log = console.log } = {}) {
   lines.push(zh.ready ? `✔ Chinese voice (kokoro zf_001): Python ${zh.python?.version ?? '?'} venv in ${zh.venv}`
     : zh.python ? `· Chinese voice (kokoro zf_001): Python ${zh.python.version} found; storyshot sets up its venv in ${zh.venv} on first use`
       : '· 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 ? ', 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}`
     : hf.missing ? `· HyperFrames cards (hyperframes: true): ${HF_VERSION} installs itself on first use`

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)']),