storyshot 0.7.3 → 0.9.0

package/README.md

@@ -143,8 +143,12 @@ After your next release, re-render it and you have an up-to-date video.
 |---|---|---|
 | a promo / launch / landing-page clip | `pitch` | short and tightly cut: intro card, the app in a browser frame, music, captions |
 | a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters |
-| a lesson or explainer | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| a lesson | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
 | help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
+| an animated explainer of how something works | `explainer` | no web app: every step is a **scene**, an animation the agent writes and times to the narration (a mechanism, a diagram that grows, a number); calm music, subtitles, chapters |
+
+Tutorials and lessons can use scenes too: a `scene:` step between recorded
+steps explains an idea the app can't show, then the video goes back to the app.
 
 Length follows the purpose and the content, not a target: a promo is as short as
 its message, a tutorial as long as the workflow takes to explain.
@@ -199,6 +203,8 @@ from `storyshot guide`.
 | `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, 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. |
+| `scene_cues` | For scene steps: synthesizes the narration and returns when each phrase is spoken (the times `S.at(k)` gives the scene). |
+| `preview_scene` | Stills of one scene a beat into each phrase, plus HyperFrames lint and its layout check, in 20–40 s, without rendering the video. |
 
 Any other MCP client: run `npx -y storyshot mcp` (stdio), and point the agent at the playbook (`storyshot guide`). When run from a git
 checkout, `setup` points to `node /path/to/checkout/bin/storyshot.mjs mcp` instead.
@@ -222,6 +228,9 @@ Everything the agent does is also a command:
 | `storyshot render videos/acme-promo.yaml [--draft]` | Record, then compose the video and soundtrack. |
 | `storyshot compose videos/acme-promo.yaml [--draft]` | Rebuild from the last recording, in seconds. |
 | `storyshot record videos/acme-promo.yaml` | Only record. |
+| `storyshot init --purpose explainer --topic "how a TaqMan probe works" [--lang zh] [--portrait]` | Write an explainer storyboard of scene steps and a starter scene file for each (`videos/scenes/`). |
+| `storyshot cues videos/<name>.yaml` | When each phrase of each scene's narration is spoken. |
+| `storyshot scene videos/<name>.yaml --step 2 [--at 1.5,4] [--no-check]` | Preview one scene: stills, lint and layout check. |
 | `storyshot guide` | Print the playbook and the reference. |
 | `storyshot setup <agent>` (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf`, `cline`) | Set up the MCP server and the skill in this project, and install or check what Storyshot needs. |
 | `storyshot doctor` | Check Node, ffmpeg (and the filters and encoders Storyshot uses), Chromium and voices; install Chromium if it's missing. |
@@ -268,7 +277,8 @@ pace: slow                                      # fast (pitch) | normal (docs) |
 follow: true                                    # tutorial/course default: the camera zooms in on what each step touches and pans between steps (a step's own zoom wins; follow: false on a step skips it); or { scale: 1.8 }
 article: { title: Export a drawing, intro: … }  # docs: heading and first paragraph of <out>-steps/README.md
 lang: es                                        # language of built-in labels ("Pause and think", chapter "Introduction", "Downloaded"): en, zh, es, pt, fr, de, ja; default: zh if the steps contain Chinese, else en
-cards: auto                                     # intro/section/end cards: auto follows the frame (dark frames get dark cards), or light | dark
+cards: auto                                     # intro/section/end cards: auto follows the film's ground, or light | dark
+ground: auto                                    # is the film light or dark overall? light | dark; auto reads it from the scenes' backgrounds, else from the frame. It sets the colour of burned-in subtitles (ink letters with a white outline on a light film, white letters with an ink outline on a dark one) and the cards' ground
 frame: aurora                                   # the recording sits in a browser window on a backdrop: aurora (dark, grain; pitch default), studio (light, grain; tutorial and course default), dark, pastel, blur (the page itself, blurred); false = full frame; or { style, background: <css>, window, title, icon }
                                                 # window: app draws an installed app's window (its icon and name in the title bar, no address bar) for a PWA or desktop web app; title and icon come from the page's web app manifest unless given
 chapters: false                                 # write <out>.chapters.txt for YouTube
@@ -475,6 +485,62 @@ 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. On HyperFrames cards, text too long for the frame (a title, subtitle, emblem or call to action) wraps and then shrinks until it fits. |
 
+### Scenes
+
+A `scene:` step plays an animation you write instead of a recording: one
+[HyperFrames](https://hyperframes.heygen.com) composition (a `<template>` with a
+root whose `id` equals its `data-composition-id`, and one paused GSAP timeline
+registered as `window.__timelines['<id>']`). It is as long as the step's `say:`
+line needs, and reads its timing from `window.__storyshot`: `S.at(k)` is when
+phrase `k` of the line is spoken (phrases end at sentence ends and commas),
+`S.end(k)` when it ends, `S.cues` all of them. It also gets `S.duration`, the
+frame size, `S.safeBottom` (the room the burned-in subtitles take) and the theme
+as CSS variables (`--accent`, `--ink`, `--font`). Media go in `assets/` next to
+the scene file.
+
+```yaml
+purpose: explainer          # scenes only: no url, nothing recorded
+voice: { provider: qwen, voice: dylan }
+subtitles: true             # an .srt beside the video; `burn` puts the words on the picture (social, muted autoplay)
+steps:
+  - scene: scenes/question.html                       # or { file, title, lead: 0.5, tail: 0.8 }
+    say: An intact probe carries a dye. Why doesn't it glow?
+  - scene: { file: scenes/fret.html, title: Quenching }
+    say: The quencher sits right next to the dye, and takes its energy before it can become light.
+```
+
+Files every scene shares (a palette, drawing helpers) are listed once:
+`scenes: { css: scenes/kit.css, js: scenes/kit.js }` loads them before each
+scene. A scene's narration may be a whole paragraph: it is spoken in chunks of
+whole sentences, and `voice.maxPause` caps the pauses inside a line (0.55 s in
+an explainer).
+
+`scenes: { three: true }` adds three.js and storyshot's `Kit3` helpers, for a
+scene whose subject is an **object** rather than a quantity: a solid is shaded
+flat by which way it faces and its edges are found in a second normal/depth
+pass, so it reads as a drawn figure rather than a render, and
+`eng.part(…, { explode })` + `eng.explode(k)` give an exploded view from one
+number. It is for the few scenes that need it — a list, a curve or a count is
+better and sharper in HTML — and it suits a light ground, because the ink edge
+is a drawn line on paper and a rim light on black. See "3D scenes, used
+sparingly" in `storyshot guide`.
+
+Every scene of a film shares one look, and the look belongs to the subject and
+the audience: a dark instrument panel suits a mechanism explained to specialists,
+a warm paper poster suits civics explained to nine-year-olds. Say which ground
+you chose with `ground: light | dark`, and the burned-in subtitles and the cards
+follow it. The playbook's "The look follows the subject" has the styles and what
+each ground costs.
+
+`lead` is how long the scene plays before the voice starts (default 0.5 s), and
+`tail` is how long it holds after the voice ends (default 0.8 s). Consecutive
+scenes cut into each other. Scenes are cached like cards, so `compose`
+re-renders only the ones that changed. `storyshot check` validates the
+contract, and `storyshot scene` runs the full HyperFrames lint and layout check
+on one scene. The playbook's "Scenes and explainers" says how to write scenes
+that explain. `music: { style: calm }` (the explainer default) is a soft pad
+with no drums.
+
 ### HyperFrames cards
 
 Tutorials and lessons render their intro, section and end cards with

package/bin/storyshot.mjs

@@ -11,6 +11,9 @@ Usage:
   storyshot init <url> [--purpose pitch|tutorial|course|docs] [--topic export-pdf] [--storage <site>-login.json]
                                     write a starter storyboard using verified targets from the page,
                                     named by type: videos/<site>-promo|tutorial|lesson|docs[-<topic>].yaml
+  storyshot init --purpose explainer --topic "how a TaqMan probe works" [--lang zh] [--portrait]
+                                    a concept explained with animated scenes (no web app): a storyboard
+                                    of scene steps + starter scene files in videos/scenes/
   storyshot login <url> [--save videos/<site>-login.json]
                                     open a browser window to log in once; saves the session for
                                     \`storageState:\` (and adds it to .gitignore)
@@ -23,6 +26,11 @@ Usage:
   storyshot compose <storyboard.yaml>     re-compose from the last recording
                                     (after changing captions, durations, zoom, music, voice, end card)
   storyshot record  <storyboard.yaml>     only (re-)record the browser session
+  storyshot cues    <storyboard.yaml>     when each phrase of each scene's narration is spoken
+                                    (the times S.at(k) returns in the scene); synthesizes the voice
+  storyshot scene   <storyboard.yaml> --step N [--at 1.5,4] [--no-check]
+                                    preview one scene: stills as each phrase is spoken (or at --at
+                                    seconds), HyperFrames lint and layout check — without a full render
   storyshot guide                   print the agent playbook + storyboard reference
   storyshot setup <agent>          add the MCP server + playbook to this project for your coding agent:
                                     cursor, claude, codex, gemini, vscode (Copilot), windsurf, cline —
@@ -41,8 +49,10 @@ Options:
 const args = process.argv.slice(2);
 const [cmd, arg] = args;
 const flag = (name) => { const i = args.indexOf(`--${name}`); return i > 0 ? args[i + 1] : undefined; };
-const NEEDS_ARG = ['login', 'init', 'inspect', 'check', 'render', 'compose', 'record', 'setup'];
-if (![...NEEDS_ARG, 'mcp', 'guide', 'doctor'].includes(cmd) || (NEEDS_ARG.includes(cmd) && !arg)) {
+const NEEDS_ARG = ['login', 'init', 'inspect', 'check', 'render', 'compose', 'record', 'setup', 'cues', 'scene'];
+// an explainer has no url to start from: `storyshot init --purpose explainer --topic …`
+const explainerInit = cmd === 'init' && flag('purpose') === 'explainer';
+if (![...NEEDS_ARG, 'mcp', 'guide', 'doctor'].includes(cmd) || (NEEDS_ARG.includes(cmd) && !arg && !explainerInit)) {
   process.stdout.write(USAGE);
   process.exit(['--help', '-h', 'help'].includes(cmd) ? 0 : 1);
 }
@@ -92,6 +102,21 @@ try {
     const r = await login(arg, { file: flag('save') ?? authFileFor(arg), viewport: viewport() });
     console.log(`✔ saved the login session to ${r.file} (${r.how}, ${r.cookies} cookies, ${r.siteCookies} for this site${r.sessionStorage ? `, sessionStorage for ${r.sessionStorage} site(s)` : ''})${r.gitignore ? `\n  added it to ${r.gitignore}` : ''}` +
       `\n  use it: \`storageState: ${r.file.split(/[\\/]/).pop()}\` in the storyboard (path relative to the yaml), or \`--storage ${r.file}\` for inspect/init`);
+  } else if (explainerInit) {
+    const { initExplainer } = await import('../src/init.mjs');
+    const r = initExplainer({ topic: flag('topic'), file: flag('file'), lang: flag('lang'), portrait: args.includes('--portrait') });
+    console.log(`✔ wrote ${r.file}\n${r.scenes.map((f) => `  + ${f}`).join('\n')}\n  next: write the say: lines, then \`storyshot cues ${r.file}\` and the scenes; preview one with \`storyshot scene ${r.file} --step 1\``);
+  } else if (cmd === 'cues') {
+    const { sceneCues } = await import('../src/scene-tools.mjs');
+    const r = await sceneCues(loadConfig(arg, { draft: args.includes('--draft') }));
+    console.log(`${r.text || 'no scene steps in this storyboard'}\n\n✔ ${r.file}`);
+  } else if (cmd === 'scene') {
+    const { previewScene, formatPreview } = await import('../src/scene-tools.mjs');
+    const step = Number(flag('step'));
+    if (!(step >= 1)) throw new Error('which scene? --step N (the step number in the storyboard, from 1)');
+    const at = flag('at') ? flag('at').split(',').map(Number).filter((x) => x >= 0) : null;
+    const r = await previewScene(loadConfig(arg, { draft: args.includes('--draft') }), step, { at, check: !args.includes('--no-check') });
+    console.log(formatPreview(r, step));
   } else if (cmd === 'init') {
     const { initStoryboard } = await import('../src/init.mjs');
     const r = await initStoryboard(arg, { purpose: flag('purpose') ?? 'pitch', topic: flag('topic'), file: flag('file'), storageState: flag('storage'), ignoreHTTPSErrors: args.includes('--insecure'), viewport: viewport() });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "storyshot",
-  "version": "0.7.3",
-  "description": "Turn a short YAML storyboard into a polished product demo video of your web app — smooth cursor, auto zoom, captions, music.",
+  "version": "0.9.0",
+  "description": "Ask your coding agent for a video of your web app: promo clips, narrated tutorials, lessons and docs GIFs from a YAML storyboard.",
   "author": "boheling <boheling@gmail.com>",
   "repository": {
     "type": "git",
@@ -26,10 +26,25 @@
   },
   "keywords": [
     "demo",
+    "demo-video",
+    "product-demo",
+    "promo-video",
     "video",
-    "playwright",
     "screen-recording",
-    "product-demo"
+    "screencast",
+    "tutorial",
+    "gif",
+    "storyboard",
+    "playwright",
+    "ffmpeg",
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "cursor",
+    "codex",
+    "coding-agent",
+    "ai-agent",
+    "agent-skill"
   ],
   "license": "MIT",
   "dependencies": {

package/skills/storyshot/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: storyshot
-description: Make videos of a web app with Storyshot — promo/demo clips, narrated how-to tutorials, teaching walkthroughs, or per-step GIFs for docs (smooth cursor, auto zoom, captions, voiceover, music). Use when the user asks for a demo video, promo or launch clip, product walkthrough, tutorial or onboarding video, course/lesson video, or GIFs of their website or web app.
+description: Make videos of a web app with Storyshot — promo/demo clips, narrated how-to tutorials, teaching walkthroughs, or per-step GIFs for docs (smooth cursor, auto zoom, captions, voiceover, music) — and narrated explainers of a concept told with animated scenes. Use when the user asks for a demo video, promo or launch clip, product walkthrough, tutorial or onboarding video, course/lesson video, GIFs of their website or web app, or an animated explainer video of how something works.
 ---
 
 # Making videos with Storyshot
 
 Storyshot drives a real browser through a site according to a YAML storyboard,
 then retimes, zooms, captions, narrates and scores the recording into an MP4.
+A step can also be a **scene**: an animation you write (a HyperFrames
+composition) that explains an idea, timed to its narration. A storyboard of
+scenes only is an **explainer** (`purpose: explainer`, no url); see
+"Scenes and explainers" below.
 Your job: **look → confirm the brief with the user → write the storyboard →
 check → render → look at the preview → fix → repeat**, then deliver.
 
 A render takes 1–3 minutes and a paid voice costs credits, so a wrong guess
 about what the user wants is the most expensive mistake. Confirm the brief
-once, up front, before writing anything.
+once, up front, before writing anything (unless the user said not to ask:
+then state your choices in the reply).
 
 ## Tools
 
@@ -30,6 +35,9 @@ Use the `storyshot` MCP tools if they are available. Otherwise use the CLI:
 | record + render (1–3 min) | `render_video` → `render_status` if it returns a `job_id` | `storyshot render videos/<name>.yaml` |
 | re-render without re-recording | `render_video` mode `compose` | `storyshot compose videos/<name>.yaml` |
 | free draft voice | `render_video` `draft: true` | `--draft` |
+| starter explainer (scene steps + starter scene files) | `init_storyboard` `purpose: explainer`, `topic` | `storyshot init --purpose explainer --topic "how X works" [--lang zh]` |
+| when each phrase of each scene's narration is spoken | `scene_cues` | `storyshot cues videos/<name>.yaml` |
+| stills + lint + layout check of one scene (20–40 s) | `preview_scene` (`step`) | `storyshot scene videos/<name>.yaml --step 2` |
 
 Always pass **absolute paths** to MCP tools.
 
@@ -42,7 +50,9 @@ everything.
 the browser can't start (an agent sandbox that blocks it, a missing Chromium),
 or the tools keep failing, stop and tell the user what blocked it and how to
 allow it. Never produce a substitute: no mock-ups, redrawn screens, scripted
-frames or stock footage presented as a recording of their app.
+frames or stock footage presented as a recording of their app. A scene explains
+an idea (a mechanism, a diagram, a number); it never redraws the app's screens
+or stands in for a recording of them.
 
 ## 1. Look, then confirm the brief
 
@@ -83,6 +93,13 @@ frames or stock footage presented as a recording of their app.
    | `tutorial` | every step of the workflow, each explained, plus a second example; as long as that takes | yes | soft | step numbers, spotlight, camera follows, part cards, recap, .srt, chapters |
    | `course` | the concepts to teach: each idea, shown in the app, checked with a question | yes | none | spotlight, camera follows, concept and question cards, recap, .srt, chapters |
    | `docs` | one clip per step, each just long enough to see its result | none | none | step numbers, spotlight, cropped GIFs + PNGs, README.md article |
+   | `explainer` | the questions the viewer has about the concept, each answered by one scene, then a closing scene after the recap ("How an explainer ends"); no web app | yes | calm | your scenes in a look chosen for the subject and the audience, an .srt beside the video (burned in only for social or muted autoplay), chapters |
+
+   An explainer has no site to look at, so the plan carries one more line: the
+   **look** — who the viewer is, and the style that suits them and the subject
+   ("3rd–5th graders, so a classroom poster: warm paper, dark ink, chunky
+   shapes"). See "The look follows the subject" in step 3. It is much cheaper to
+   agree on it now than to repaint ten finished scenes.
 
    Captions match the site's language. `kokoro` (free, local) speaks English
    and Mandarin Chinese: for Chinese lines use `voice: { provider: kokoro,
@@ -270,6 +287,10 @@ common ones):
    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.
+7. A last word, which the recap is not: what the viewer can do now that they
+   could not do at the start, and the one thing to keep. A film that stops on
+   its recap sounds cut off, whatever its type — see "How an explainer ends"
+   below, which is where that is spelled out.
 
 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
@@ -365,6 +386,335 @@ Notes:
 - `.storyshot/` next to the YAML is a cache of recordings, screenshots and
   voice lines. Add it to `.gitignore`.
 
+### Scenes and explainers
+
+A **scene** is a step whose picture you write instead of recording: an
+animation that shows an idea the app can't, such as how a probe lights up, why an
+algorithm scores a match, or what a number means. It is a HyperFrames
+composition, an HTML file with a GSAP timeline, and it plays as long as the
+step's `say:` line needs. Use it two ways:
+
+- **`purpose: explainer`**: the whole video is scenes, with no `url` and nothing
+  recorded. Use it for "explain how X works" when there is no web app to show.
+- **Inside a tutorial or lesson**: a `scene:` step between recorded steps
+  explains the why ("what does this score mean?"), then the video goes back to
+  the app. Keep these to 10–30 s.
+
+```yaml
+- scene: scenes/fret.html          # or { file: …, title: Chapter title, lead: 0.5, tail: 0.8 }
+  say: The quencher sits right next to the dye. Its energy is passed across before it can become light.
+```
+
+`lead` is how long the scene plays before the voice starts (default 0.5 s).
+`tail` is how long it holds after the voice ends (default 0.8 s). A scene
+with no `say:` needs a `duration`. A scene has no `actions`, `caption` or
+`zoom`, because it draws its own picture and text.
+
+**Workflow.** Write the words first, then the pictures:
+1. **Facts.** Every claim, number and sequence on screen comes from a source
+   you checked: a paper, the official docs, a database. Put the source on
+   screen in small type where its number appears, and list the sources in your
+   reply. Mark drawings that are schematic ("示意", "illustrative"). A
+   beautiful wrong diagram is worse than none. (A credit line may be smaller
+   than the 28 px text floor: put `data-layout-ignore` on it.)
+2. **Story.** Start from something the viewer knows: a real case, their own
+   question, one concrete example that runs through the whole video (one
+   gene, one request, one dataset). Then one question per scene, answered by
+   one picture. Follow "Writing the narration" above: short spoken sentences;
+   question → concrete case → name the idea → why → recap → **a closing scene**
+   ("How an explainer ends" below). The arc does not end on the recap: plan the
+   closing scene here, with the others, not after the first render.
+3. **Lines.** Write the `say:` lines: one idea per scene, usually 2–5
+   sentences (about 60 English words or 120 Chinese characters at most).
+   Commas are cue points: each phrase can trigger one change on screen.
+4. **Cues.** Run `storyshot cues` (MCP `scene_cues`). It synthesizes the voice
+   and prints each scene's length and when each phrase is spoken. These are
+   the times `S.at(k)` returns inside the scene.
+5. **Look.** Choose the film's style from its subject and its audience, write
+   it down (ground, palette, type, how objects are drawn), and put it in the
+   scene kit before any scene is written. "The look follows the subject" below.
+6. **Scenes.** Write each scene file (contract below). Then preview it with
+   `storyshot scene … --step N` (MCP `preview_scene`), which gives stills a beat
+   into each phrase, HyperFrames lint, and a layout check. Look at every still,
+   fix the scene, and preview again until it is right.
+7. **Render**, look at `preview.jpg` (one frame per scene), and fix. After
+   editing only scenes or lines, `compose` re-renders just the scenes that
+   changed.
+
+**How an explainer ends.** A recap is not an ending. A recap re-counts what the
+film already said and then runs out, and a viewer hears that as the film being
+cut off — "像没有结局一样，很突兀". Storyshot resolves the music and settles the
+picture, but a full stop is something only the script has: a conclusion, what is
+still open, and one thought to leave with. **Write the last scene as a scene of
+its own, after the recap**, and give it the four or five sentences the rest of
+the film earned:
+
+- **What this actually means.** Not a summary — the thing that is true now that
+  the viewer has seen all of it. Often it is the one sentence you could not have
+  said in scene 1: *the lesson is not "keep going", it is that a guess got
+  treated as a proof while an old algorithm waited for hardware.*
+- **What is still open.** Name it plainly, with the same honesty as the body. A
+  film that admits its limit ends; a film that trails off into a caveat stops.
+- **One thought to leave with**, in the film's own images, not a new one. Land
+  the final words on it. *The brake was all you had; now you can also hand over
+  the picture of who to chase.*
+
+Then the picture follows the words:
+
+- **The closing frame shows less than the one before it.** Let the recap build,
+  then take it away: clear everything except the one object, number or sentence
+  the film was about. A viewer leaves holding one thing, so choose which.
+- **Keep the last 2 s alive.** Land the closing move *on* the final words, and
+  prefer a move that is still running when the file ends — a line still being
+  drawn, a curtain still closing — over one that finished and is being held.
+- Three or more seconds of a motionless frame is the defect the layout check
+  calls `dead_stretch`; it does not see the `tail`, so check that yourself, and
+  `preview_scene` reports `frozen_ending` when the last scene is already frozen.
+- A recap that now has a closing scene after it should stop holding a long
+  `tail` for an ending it no longer has: shorten it and let the recap dissolve
+  as its last words land, so it reads as a page turn.
+- An `end_card` is an alternative ending, not an extra one: with a card the last
+  scene hands over to it, and storyshot leaves the picture to the card.
+
+One practical trap when you time that scene: **the voice breaks cues on commas,
+not just full stops**, so "一个线，一道帘子，一张纸" is three cues, not one. Run
+`cues` (or `preview_scene`) and key the beats to the list it prints, never to
+the sentences you counted in the `say:` line.
+
+**3D scenes, used sparingly.** `scenes: { three: true }` loads three.js and
+storyshot's own `Kit3` into every scene of the film. Kit3 does not light a
+scene, it *draws* one: flat tone chosen by which way a face points, ink edges
+found in a second normal/depth pass, and a long lens (fov 18) so parallel edges
+stay parallel. The result reads as a figure in a textbook, not as a render.
+
+**Most scenes should not use it.** Reach for 3D only when the form itself
+carries the meaning:
+
+- it is a **real object** the viewer could hold or stand next to (a culture
+  flask, an instrument, a ballot box);
+- the point is **how the parts fit together**, so an exploded view *is* the
+  answer (`eng.part(parent, { at, explode })`, then `eng.explode(k)`);
+- the point is **spatial**: something is inside, under or behind something
+  else, or how densely a volume is filled is the fact;
+- the idea needs **two angles** before it lands.
+
+Leave everything else in 2D — it is sharper, smaller, faster to write, and the
+type stays type. A quantity, a sequence, a list, a curve, a year, a name, and
+any object that is really a figure of speech (a "barcode", a "reading frame", a
+brake) all belong in HTML and SVG. Extruding a bar chart into boxes adds a third
+dimension with no information in it. Keep 3D to roughly **a third of a film's
+scenes at most**, on the one object the film keeps coming back to; a film where
+every scene is a rendered object stops reading as an explanation and starts
+reading as a product demo.
+
+**Prefer a light ground for it.** The edge pass finds a silhouette and draws it
+*dark*, which on paper is a drawn line and on a dark ground has to become a pale
+rim — that is a light, which is the one thing the technique exists to avoid. On
+a dark film, translucency also stops working: glass reads as a hole. Pick the
+film's ground for its subject as always, but if the film will carry 3D, that is
+an argument for paper. And remember a ground change is a **palette** change: a
+signal colour chosen to glow on blue-black usually fails contrast on paper (a
+`#ff5c8a` that sang on `#0f1218` reads at 2.6:1 on `#f4f1ea`).
+
+Keep the words in HTML over the canvas, not in the 3D scene: text drawn in WebGL
+is soft, cannot be checked for contrast or the 28 px floor, and does not pick up
+the film's fonts. The scene renders from the timeline — `eng.render()` inside a
+GSAP `onUpdate`, never a frame loop — and uses `Kit3.rng(seed)` where it needs
+scatter, because frames are rendered by seeking and `Math.random` would give a
+different picture every render. `storyshot guide` prints Kit3's full API in
+`src/scene-kit/kit3d.js`; a scene that calls `Kit3` or `THREE` without
+`scenes: { three: true }` is a `check` error, because it would otherwise render
+an empty frame.
+
+**The scene file contract** (`storyshot check` and `preview_scene` enforce it):
+
+```html
+<template>
+  <style>
+    #fret { position: absolute; inset: 0; overflow: hidden; background: #121110; font-family: var(--font); }
+    #fret-dye { position: absolute; left: 600px; top: 420px; width: 120px; height: 120px; border-radius: 50%; background: #f4a62a; }
+  </style>
+  <div id="fret" data-composition-id="fret" data-width="1920" data-height="1080">
+    <div id="fret-dye"></div>
+  </div>
+  <script>
+    (function () {
+      const S = window.__storyshot;               // this scene's timing, size and theme
+      const tl = gsap.timeline({ paused: true });
+      tl.fromTo('#fret-dye', { scale: 0 }, { scale: 1, duration: 0.6, ease: 'expo.out' }, S.at(0));
+      tl.fromTo('#fret-dye', { opacity: 1 }, { opacity: 0.25, duration: 0.4 }, S.at('passed across'));
+      window.__timelines['fret'] = tl;
+    })();
+  </script>
+</template>
+```
+
+- One `<template>` holds the styles, markup and script. The root element's
+  `id` equals its `data-composition-id`, is unique among the scenes, and
+  prefixes every other id in the file. `data-width`/`data-height` match the
+  video (1920×1080, or 1080×1920 for portrait).
+- One paused GSAP timeline, registered as `window.__timelines['<id>']`. Use
+  `fromTo` (not `from`). No `Date`, timers, `requestAnimationFrame`,
+  `repeat: -1`, or unseeded `Math.random`: frames are rendered by seeking the
+  timeline.
+- Media go in `assets/` next to the scene file, referenced as `assets/x.png`.
+- **A look shared by every scene** (a palette, fonts, a helper that draws
+  your recurring objects): put it in files and list them once at the top of
+  the storyboard, `scenes: { css: scenes/kit/kit.css, js: scenes/kit/kit.js }`.
+  They load before each scene's own script, so a scene can call your helpers
+  and use your CSS variables.
+- **`window.__storyshot`** (`S`) gives you:
+  - `S.at(k, offset)`: when phrase `k` starts. `k` counts from 0, `-1` is the
+    last phrase, and a string means the phrase that contains it.
+  - `S.end(k)`: when phrase `k` ends.
+  - `S.cues`: `[{ text, t, end }]` for every phrase.
+  - `S.duration`, `S.width`, `S.height`, `S.lead`.
+  - `S.safeBottom`: the pixels at the bottom that burned-in subtitles take
+    (16% of the height, 22% in portrait, 0 without `subtitles: burn`); keep
+    content above it. The same value is available as the CSS variable
+    `var(--safe-bottom)`. `preview_scene` draws this band on its stills as a
+    striped red strip.
+  - `S.theme`: `{ accent, ink, font }`, also available as `var(--accent)`,
+    `var(--ink)` and `var(--font)`. The font falls back to the machine's CJK
+    font for Chinese.
+
+  Time every reveal from `S.at`, never from hard-coded seconds, so the
+  animation stays on the words when a line changes.
+
+**The look follows the subject and the audience.** There is no house style, and
+the last explainer's look is not a default. A film for eight-year-olds about
+voting and a film for biologists about pooled screens should not look alike:
+choose the style, say so in the plan, and put it in the scene kit
+(`scenes: { css: …, js: … }`) before the first scene is written, so ten scenes
+can't disagree about it.
+
+Two questions decide it. **Who is watching?** Children and general audiences
+need big friendly drawings, few colours and a light ground; specialists read
+dense instrument-like pictures and are at home on a dark panel. **What is the
+subject made of?** A thing that glows, fluoresces, counts or signals wants a
+dark ground to light up on; a thing that is printed, taught, filled in or voted
+on wants paper. Starting points, not a menu to pick blindly:
+
+| subject, and who it is for | the look | made of |
+|---|---|---|
+| a mechanism, molecule, instrument or pipeline, for people who work on it | instrument panel | near-black ground, one or two signal colours that light up, hairlines, mono labels, counters, glows |
+| anything for children; civics, history and everyday subjects for everyone | classroom poster | warm paper, dark ink, chunky rounded shapes, thick strokes, big plain type, drawings with visible hand |
+| money, policy, a market, a result, for a general adult or professional audience | clean report | white ground, one accent, wide margins, one typeface, real numbers, nothing decorative |
+| a machine, a building, a physical process | blueprint | deep blue or sepia ground, a faint grid, dimension and leader lines, small-caps part labels |
+| a person, a place, a historical event | storybook | a tinted ground that is neither black nor white, illustrated figures, soft shapes, one warm accent |
+
+**Then tell Storyshot which ground you chose**: `ground: light` or
+`ground: dark` in the storyboard. Burned-in subtitles and the intro/section/end
+cards follow it — ink letters with a white outline on a light film, white
+letters with an ink outline on a dark one — so the words read without a bar
+drawn under them. Left out, `auto` reads the ground from the scenes — their own
+background, or the kit rule for a class on their root (`<div id="x"
+class="world">`). When it is a variable or an image, nothing can be read:
+`check` warns, and the subtitles stay white until you say which the film is.
+
+**What a ground costs.** The choice is not only a colour; it changes what works:
+- **On a light ground**, a glow is a smudge: make it a flat tinted panel, a ring
+  or nothing. Keep shadows at `rgba(<ink>, .12)` or less, or they look dirty. A
+  cream card that floated on black becomes a *white* sheet, which needs its own
+  shadow and some real structure inside (rules, a divider) or it reads as a
+  blank rectangle. A saturated accent that sang on black usually fails the
+  contrast check as text on paper (amber `#f4a62a` on white is about 2:1):
+  darken it for text, keep the bright one for fills, or give the words a thin
+  ink outline — and settle that in the kit, once.
+- **On a dark ground**, thin dark lines and dark figures vanish: every object
+  needs a light value of its own, and faint white strokes (`rgba(255,255,255,.06)`)
+  that carry structure there have no quiet equivalent on paper.
+- **Either way**, a colour used as a *fill* can be bright, while the same colour
+  as *text* has to pass the contrast check (the layout check measures it, 3:1
+  for large text and 4.5:1 for normal). Watch a colour sitting inside a panel
+  of its own hue (teal dots on a teal wing): it measures against the panel, not
+  against the ground, and that is where contrast is usually lost.
+
+**Repaint before the scenes exist, not after.** Converting a finished ten-scene
+film to the other ground is an hour or more of work with nothing new to show
+for it: the colour swap is mechanical, but every glow, shadow, faint stroke and
+floating card needs a judgement, and the contrast findings all change. It is
+much cheaper to show one previewed scene in the chosen style and ask.
+
+**Pictures that explain** (what the preview stills should show):
+- **The object is the explanation.** Draw the actual thing, such as the
+  molecule, the queue or the circuit, big enough to be the hero: at least 40%
+  of the frame's width or height. Use the real data where it exists: a real
+  sequence, real numbers. Never show a small icon floating in an empty frame:
+  if a still is mostly empty ground, scale the diagram up until it fills the
+  frame.
+- **One diagram that grows.** Start from the simplest true picture and add one
+  part per phrase, each when the voice names it, with its label on it (a
+  leader line, not a legend). Never put the finished diagram on screen at
+  once.
+- **Motion.** One hero move per beat, and something new every 2–4 s.
+  Arrivals ease out (`expo.out`, 0.5–0.7 s) and exits are shorter. Text lands
+  and then stays still while it is read.
+- **Text.** At least 28 px at 1080p, and nothing under `S.safeBottom`. Never
+  repeat the narration word for word on screen (the subtitles do that).
+  Avoid bullet slides and rows of three cards.
+- **Colour.** Rationed: one accent, plus one colour per thing the story
+  tracks (for example, allele G amber and allele A green everywhere: dye,
+  dot, label).
+- **Seams.** Consecutive scenes cut straight into each other. End a scene on
+  a state the next one starts from (the same object in the same place), or
+  on a clean hold. The video's first frame is its thumbnail: show the subject
+  there, never an empty ground.
+- **Look before you move on.** Read `preview_scene`'s stills like a stranger
+  would. Is every object recognisable without explanation, does each part
+  appear when it is named, and does nothing overlap, crop or sit under the
+  subtitles? Fix every ✖ from lint and the layout check.
+
+**Gotchas** (each one cost a real run several previews):
+- **Several tweens on one property.** Several `fromTo`s on the same property
+  of one element (fade a label in, later fade it out) are fine: Storyshot
+  gives every later one `immediateRender: false`, so it does not show its
+  start state from the first frame. With `to()` or `from()`, or a position
+  that is not a number, set `immediateRender: false` yourself.
+- **SVG sizes.** Animate them with `attr: { width: 300 }`. A CSS transform
+  on an SVG `<rect>` (`scaleX` with `transform-origin`) can render nothing.
+- **Lines that draw themselves.** Give the path `pathLength="1"`,
+  `stroke-dasharray: 1`, and tween `strokeDashoffset` from 1 to 0 with
+  `autoRound: false`. Without it, GSAP rounds the offset to whole pixels and
+  the line pops in instead of drawing.
+- **Layout check findings that are intended.**
+  - A glow that spills out of its box: `data-layout-allow-overflow` on the box.
+  - A label sitting on its object: `data-layout-allow-overlap` on the container.
+  - Small credits or texture: `data-layout-ignore`.
+- **"The film's last line needs 2 s".** Only the video's last scene must hold
+  its final words. Elsewhere, reveal text on an earlier phrase or raise
+  `tail:`.
+- **The ground under the cards.** Intro and end cards follow the film's ground,
+  so they come out dark when the scenes do; `ground: light | dark` settles the
+  whole film and `cards: light | dark` overrides the cards alone. Keep
+  end-card bullets short: about 10 Chinese characters or 5 English words each.
+
+Long narration is fine: a scene's `say:` is spoken in chunks of whole
+sentences, and in an explainer no pause inside a line lasts longer than
+`voice.maxPause` (0.55 s by default), so the voice keeps moving.
+
+Explainer defaults:
+- **Music:** `music: { style: calm }`, soft pads with no drums;
+  `music: false` for none.
+- **Subtitles:** `subtitles: true` writes an .srt; `burn` puts them on the
+  video. `true` is the default and the right one for an explainer watched on a
+  screen: the scenes already carry text, and a burned-in line lighting up word
+  by word at the bottom pulls the eye off the drawing for the whole film. Burn
+  them for social video, for a feed that autoplays muted, or when asked — and
+  then say so, because it is a trade, not a free addition. Burned-in words take
+  their colour from `ground:` (see "The look follows the subject"), so set it.
+- **Ground:** `ground: light | dark`, chosen for the subject and the audience,
+  not inherited from the last film.
+- **Chapters:** come from the scenes' `title`s.
+- **Cards:** an `intro` and an `end_card` work as in lessons.
+
+Long explainers (more than about 6 scenes) build fastest if each scene is
+written by its own sub-agent, all from the same lines, cues, scene contract and
+scene kit — and from the same written description of the look, or they will
+each invent one. Settle anything they disagree about (a colour that fails
+contrast, an object drawn two ways) in the kit, once, not scene by scene.
+Review every scene's stills yourself afterwards.
+
 ## 4. Render, look, fix
 
 1. `render_video` (use `draft: true` while iterating if the voice is
@@ -407,6 +757,9 @@ Notes:
    - Draft looks right: `compose` with `draft: false` for the final voice.
      Only lines not yet synthesized cost credits. `draft` only matters with
      a paid voice; with `kokoro`, it is the same voice either way.
+   - Changed only scenes (their files, lines or assets): `compose`; only the
+     scenes that changed render again. An explainer has nothing to record,
+     so `render` and `compose` do the same.
 
 ## 5. Deliver