storyshot 0.8.0 → 0.9.0

package/README.md

@@ -501,7 +501,7 @@ the scene file.
 ```yaml
 purpose: explainer          # scenes only: no url, nothing recorded
 voice: { provider: qwen, voice: dylan }
-subtitles: burn
+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?
@@ -515,6 +515,16 @@ 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "storyshot",
-  "version": "0.8.0",
-  "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

@@ -93,7 +93,7 @@ or stands in for a recording of them.
    | `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; no web app | yes | calm | your scenes in a look chosen for the subject and the audience, .srt or burned-in subtitles, chapters |
+   | `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
@@ -287,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
@@ -417,7 +421,9 @@ with no `say:` needs a `duration`. A scene has no `actions`, `caption` or
    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.
+   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.
@@ -435,6 +441,91 @@ with no `say:` needs a `duration`. A scene has no `actions`, `caption` or
    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
@@ -606,7 +697,11 @@ 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, the better choice for social video and Chinese. Burned-in words take
+  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.

package/src/audio.mjs

@@ -44,29 +44,47 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
     for (let i = 0; i < Math.min(N, f.length / 2); i++) { music[0][i] = f[2 * i] * 0.5; music[1][i] = f[2 * i + 1] * 0.5; }
   } else if (cfg.music?.style === 'calm') {
     // calm (explainers): slow pad chords vi–IV–I–V in C, two bars each, a soft bass under them and a
-    // sparse bell; no drums, nothing on the beat that would pull at the voice
+    // sparse bell; no drums, nothing on the beat that would pull at the voice.
+    // The film has to *end*, not stop. Truncating the loop wherever the video happens to finish leaves
+    // the last chord hanging (and faded down, which a listener hears as "turned off", not "over"), so
+    // the loop is phased to reach IV one chord before the end, the tonic lands there — under the last
+    // spoken line — and rings out through the tail: a plagal cadence, the gentlest full stop there is.
     const BEAT = 60 / cfg.music.bpm, LEN = BEAT * 8;
     const chords = [[57, 60, 64], [53, 57, 60], [48, 52, 55], [55, 59, 62]];
-    for (let b = 0, t0 = 0; t0 < events.total; b++, t0 = b * LEN) {
-      const ch = chords[b % chords.length], len = Math.min(LEN, events.total - t0) + 1.2; // rings into the next chord
+    const CAD = Math.max(0, events.total - LEN);   // where the tonic lands (a clip shorter than one
+                                                   // chord is all cadence, which is the right answer)
+    const before = Math.ceil(CAD / LEN);           // chords before it...
+    const phase = ((2 - before) % 4 + 4) % 4;      // ...phased so the last of them is IV
+    const pad = (ch, t0, len, gain = 1) => {
       for (const [k, note] of [...ch, ch[0] + 12].entries()) {
         for (const det of [-0.06, 0.06]) {
           const f = hz(note + det), filt = svf();
           add(music, t0, len, (t) => {
             const env = Math.min(1, t / 1.4) * Math.min(1, Math.max(0, len - t) / 1.6);
             return filt(saw(f * t) * 0.6 + Math.sin(2 * Math.PI * f * t) * 0.4, 650 + 250 * Math.sin(t * 0.4 + k)).lp * env;
-          }, 0.024, (k - 1.5) * 0.35 + det * 2);
+          }, 0.024 * gain, (k - 1.5) * 0.35 + det * 2);
         }
       }
       const fb = hz(ch[0] - 12);
-      add(music, t0, len, (t) => Math.sin(2 * Math.PI * fb * t) * Math.min(1, t / 0.6) * Math.min(1, Math.max(0, len - t) / 1.2), 0.09);
+      add(music, t0, len, (t) => Math.sin(2 * Math.PI * fb * t) * Math.min(1, t / 0.6) * Math.min(1, Math.max(0, len - t) / 1.2), 0.09 * gain);
+    };
+    for (let b = 0, t0 = 0; t0 < CAD; b++, t0 = b * LEN) {
+      const ch = chords[(b + phase) % chords.length], len = Math.min(LEN, CAD - t0) + 1.2; // rings into the next chord
+      pad(ch, t0, len);
       if (b % 2 === 0) for (const [j, note] of [ch[2] + 12, ch[1] + 24].entries()) {
         const f = hz(note);
         add(music, t0 + j * BEAT * 2, 2.5, (t) => (Math.sin(2 * Math.PI * f * t) + 0.15 * Math.sin(4 * Math.PI * f * t)) * Math.exp(-t * 1.8) * Math.min(1, t / 0.01), 0.03, j ? 0.3 : -0.3);
       }
     }
-    // fade in over 2 s, out over the last 3 s
-    for (const c of music) for (let i = 0; i < N; i++) c[i] *= Math.min(1, i / SR / 2) * Math.min(1, (N - i) / SR / 3);
+    // the cadence: the tonic swells a little louder than the loop ever did, with two bells over it
+    const RING = events.total - CAD, TONIC = [48, 52, 55];
+    pad(TONIC, CAD, RING, 1.15);
+    for (const [j, note] of [TONIC[2] + 12, TONIC[0] + 24].entries()) {
+      const f = hz(note);
+      add(music, CAD + j * BEAT, RING, (t) => (Math.sin(2 * Math.PI * f * t) + 0.2 * Math.sin(4 * Math.PI * f * t)) * Math.exp(-t * 0.9) * Math.min(1, t / 0.01), 0.035, j ? 0.3 : -0.3);
+    }
+    // fade in over 2 s; the cadence is what ends the music, so the fade out only guards the cut
+    for (const c of music) for (let i = 0; i < N; i++) c[i] *= Math.min(1, i / SR / 2) * Math.min(1, (N - i) / SR / 1.2);
   } else if (cfg.music) {
     // I–V–vi–IV in C at `bpm`, resolving on the end card (or fading at the end)
     const BEAT = 60 / cfg.music.bpm, BAR = BEAT * 4;

package/src/check.mjs

@@ -179,12 +179,12 @@ export function check(file, { draft = false } = {}) {
     // scenes: the file is there and keeps the HyperFrames contract (the full lint runs in `storyshot scene`)
     for (const [i, s] of cfg.steps.entries()) {
       if (!s.scene || s.hidden) continue;
-      const r = sceneInfo(s.scene.file, cfg.output);
+      const r = sceneInfo(s.scene.file, { ...cfg.output, three: !!cfg.sceneKit?.three });
       errors.push(...r.errors.map((e) => `step ${i + 1}: ${e}`));
       warnings.push(...r.warnings.map((w) => `step ${i + 1}: ${w}`));
       if (!cfg.voice && !(typeof s.duration === 'number')) errors.push(`step ${i + 1}: a scene is as long as its narration, and there is no voice: — add a voice: block, or give the scene a duration`);
     }
-    if (raw.scenes) unknown(raw.scenes, ['css', 'js'], 'scenes');
+    if (raw.scenes) unknown(raw.scenes, ['css', 'js', 'three'], 'scenes');
     for (const f of [...cfg.sceneKit.css, ...cfg.sceneKit.js]) if (!fs.existsSync(f)) errors.push(`scenes: ${f} does not exist`);
     for (const f of cfg.sceneKit.css) if (!/\.css$/i.test(f)) errors.push(`scenes.css: ${path.basename(f)} is not a .css file`);
     for (const f of cfg.sceneKit.js) if (!/\.m?js$/i.test(f)) errors.push(`scenes.js: ${path.basename(f)} is not a .js file`);

package/src/compose.mjs

@@ -659,7 +659,12 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       `[${last}][in]overlay=0:0:eof_action=pass[v${++idx}];\n`;
     last = `v${idx}`;
   }
-  graph += `[${last}]trim=duration=${TOTAL},format=yuv420p[out]`;
+  // The picture needs a full stop too. Without one the file simply ceases on whatever was on screen —
+  // which in an explainer is the recap, the busiest frame of the film, held still and then cut. An end
+  // card is already an ending; otherwise settle to the film's own ground over the last of the tail.
+  const OUTRO = ec ? 0 : Math.min(0.9, TOTAL * 0.02);
+  const outro = OUTRO > 0.05 ? `,fade=out:st=${(TOTAL - OUTRO).toFixed(3)}:d=${OUTRO.toFixed(3)}:color=${filmGround(cfg) === 'light' ? 'white' : 'black'}` : '';
+  graph += `[${last}]trim=duration=${TOTAL},format=yuv420p${outro}[out]`;
   if (clean) graph += `;\n[vclean0]trim=duration=${TOTAL},format=yuv420p[clean]`;
   const graphFile = path.join(cfg.work, 'graph.txt');
   fs.writeFileSync(graphFile, graph);

package/src/config.mjs

@@ -202,7 +202,14 @@ export function loadConfig(file, { draft = false } = {}) {
 
   // scenes: { css: [files], js: [files] } shared by every scene (a palette, drawing helpers), loaded before each one
   const sk = raw.scenes ?? {};
-  const sceneKit = { css: [].concat(sk.css ?? []).map((f) => path.resolve(dir, f)), js: [].concat(sk.js ?? []).map((f) => path.resolve(dir, f)) };
+  // `three: true` adds storyshot's own drawn-3D helpers (three.js + Kit3) before the storyboard's
+  // own kit files, for scenes whose subject is an object rather than a quantity (guide: "3D scenes").
+  if (sk.three != null && typeof sk.three !== 'boolean') throw new Error('scenes.three is true or false (it loads three.js and storyshot\'s Kit3 helpers into every scene)');
+  const sceneKit = {
+    css: [].concat(sk.css ?? []).map((f) => path.resolve(dir, f)),
+    js: [].concat(sk.js ?? []).map((f) => path.resolve(dir, f)),
+    three: sk.three === true,
+  };
   return {
     name,
     purpose,

package/src/hyperframes.mjs

@@ -20,6 +20,7 @@ import { writeSceneProject, sceneAssets, fileHash } from './scenes.mjs';
 
 export const HF_VERSION = '0.8.217';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
+const KIT3D = path.join(HERE, 'scene-kit', 'kit3d.js');
 // families HyperFrames resolves by name; any other needs an @font-face
 const BUNDLED = ['Inter', 'Montserrat', 'Outfit', 'Nunito', 'Oswald', 'League Gothic', 'Archivo Black', 'Space Mono', 'IBM Plex Mono', 'JetBrains Mono',
   'EB Garamond', 'Playfair Display', 'Source Code Pro', 'Noto Sans JP', 'Roboto', 'Open Sans', 'Lato', 'Poppins'];
@@ -591,7 +592,10 @@ blurIn('#try', ${n(ctaAt + 0.85)}, { d: 0.25 });` : ''}
 // --- rendering ---------------------------------------------------------------------------------------
 const hashOf = (...parts) => {
   const h = crypto.createHash('sha1');
-  for (const p of parts) h.update(typeof p === 'string' ? p : JSON.stringify(p));
+  // JSON.stringify(undefined) is undefined, not a string, and Hash.update throws on it. A scene step
+  // with a `duration:` and no `say:` line is legal and hashes `job.say` as undefined, so keep a name
+  // for the empty ones rather than crashing the whole render on them.
+  for (const p of parts) h.update(typeof p === 'string' ? p : JSON.stringify(p) ?? String(p));
   return h.digest('hex').slice(0, 16);
 };
 
@@ -622,6 +626,9 @@ export async function renderHyperframesCards(jobs, ctx, { log = console.log, war
       const files = sceneAssets(job.scene.file);
       const key = hashOf(HF_VERSION, ctx.FPS, job.seconds.toFixed(3), job.lead, job.cues, job.say, ctx.W, ctx.H, ctx.accent, ctx.ink, ctx.font, ctx.lang, ctx.subs,
         fs.existsSync(job.scene.file) ? fileHash(job.scene.file) : 'missing', ...Object.entries(files).map(([k, f]) => [k, fileHash(f)]),
+        // the shipped 3D helpers are part of the picture too: upgrading storyshot has to invalidate
+        // the cached frames of every 3D scene, or a fixed engine renders the old frames back
+        job.kit?.three ? ['kit3d', fileHash(KIT3D)] : 'no-three',
         ...[...(job.kit?.css ?? []), ...(job.kit?.js ?? [])].map((f) => [f, fs.existsSync(f) ? fileHash(f) : 'missing']));
       const dir = path.join(root, `${job.name}-${key}`), frames = path.join(dir, 'frames');
       if (fs.existsSync(path.join(dir, 'done'))) { out[job.name] = { dir: frames, ext: 'jpg', alpha: false }; continue; }

package/src/init.mjs

@@ -97,10 +97,21 @@ export function initExplainer({ topic, file, lang = 'en', portrait = false } = {
   const dir = path.dirname(path.resolve(file));
   const zh = /^zh/i.test(lang);
   const [W, H] = portrait ? [1080, 1920] : [1920, 1080];
+  // Four steps, not three: a recap re-counts what the film said and then runs out, which a viewer hears
+  // as the film being cut off. The last step is the ending itself (`storyshot guide`: "How an explainer ends").
   const scenes = [1, 2, 3].map((k) => ({ id: `${name}-s${k}`.replace(/[^a-z0-9-]/gi, '-'), rel: `scenes/${name}-${k}.html` }));
+  scenes.push({ id: `${name}-close`.replace(/[^a-z0-9-]/gi, '-'), rel: `scenes/${name}-close.html` });
   const say = zh
-    ? ['TODO 一个观众会问的问题，一两句话。', 'TODO 用一个具体例子回答，每个短句对应画面上的一个变化。', 'TODO 一句话总结。']
-    : ['TODO the question a viewer would ask, in one or two sentences.', 'TODO answer it with one concrete example, one change on screen per phrase.', 'TODO the idea in one line.'];
+    ? ['TODO 一个观众会问的问题，一两句话。', 'TODO 用一个具体例子回答，每个短句对应画面上的一个变化。', 'TODO 把讲过的再数一遍。',
+       'TODO 结尾：这件事到底意味着什么（一句在第一场说不出来的话）；哪些还没有答案；留给观众的一句话，落在片子自己的那张图上。']
+    : ['TODO the question a viewer would ask, in one or two sentences.', 'TODO answer it with one concrete example, one change on screen per phrase.',
+       'TODO count back over what the film showed, one line each.',
+       'TODO the ending. What this actually means (the sentence you could not have said in scene 1), what is still open, and one thought to leave with, on the film\'s own picture.'];
+  const note = [
+    '\n    # scene: { file: …, title: Chapter title, lead: 0.5, tail: 0.8 }   (lead: seconds before the voice starts)', '', '',
+    zh ? '\n    # 回顾数完就停，所以听起来没有结局；这一场才是结局。最后一下落在最后一句话上，\n    # 而且到最后一帧还在动（一条还在画的线，一道还在合的帘子），别停在一张满画面上。'
+       : '\n    # The recap stops rather than ends; this scene is the ending. Land its last move ON the final words,\n    # and leave something still moving at the last frame — not a held frame of the film\'s fullest moment.',
+  ];
   const yaml = `# Storyshot storyboard (explainer) — every step is a scene: an animation you write as a HyperFrames
 # composition (scenes/*.html), timed to the step's narration. Reference: \`storyshot guide\` ("Scenes and explainers").
 # Loop: write the say: lines → storyshot cues (when each phrase is spoken) → write the scenes with S.at(k)
@@ -109,16 +120,19 @@ name: ${name}
 purpose: explainer
 out: ${name}.mp4
 ${zh ? 'lang: zh\nvoice: { provider: qwen, voice: dylan }      # free, local (Apple Silicon); elsewhere kokoro zf_001' : 'voice: { provider: kokoro }                  # free, local'}
-${portrait ? `output: { width: ${W}, height: ${H} }\nviewport: { width: 900, height: 1600 }\n` : ''}subtitles: burn                                  # or true for an .srt beside the video
+${portrait ? `output: { width: ${W}, height: ${H} }\nviewport: { width: 900, height: 1600 }\n` : ''}subtitles: true                                  # an .srt beside the video, which is the right one for an explainer: the
+                                                 # scenes already carry text, and \`burn\` lights the words up at the bottom
+                                                 # of the picture, pulling the eye off the drawing for the whole film.
+                                                 # Burn them for social video or a feed that autoplays muted, and say so.
 ground: light                                    # light | dark: the film's ground, chosen for the subject and its audience
                                                  # (\`storyshot guide\`: "The look follows the subject"). Paper for a subject that
                                                  # is taught, printed or voted on; dark for a mechanism, an instrument or anything
-                                                 # that glows. Subtitles and cards follow it; paint every scene to match.
-theme: { accent: "#b45309", ink: "#17181b" }     # accent: the one colour that points. It also paints the word being
-                                                 # spoken in the subtitles, so it has to read on the ground above
+                                                 # that glows. The cards follow it; paint every scene to match.
+theme: { accent: "#b45309", ink: "#17181b" }     # accent: the one colour that points (with \`subtitles: burn\`, also the word
+                                                 # being spoken), so it has to read on the ground above
 
 steps:
-${scenes.map((sc, k) => `  - scene: ${sc.rel}${k === 0 ? '\n    # scene: { file: …, title: Chapter title, lead: 0.5, tail: 0.8 }   (lead: seconds before the voice starts)' : ''}
+${scenes.map((sc, k) => `  - scene: ${sc.rel}${note[k] ?? ''}
     say: ${say[k]}`).join('\n\n')}
 `;
   fs.mkdirSync(path.join(dir, 'scenes', 'assets'), { recursive: true });
@@ -145,7 +159,7 @@ function starterScene(id, W, H) {
   <script>
     (function () {
       // S.at(k): when phrase k of this step's say: line starts (S.end(k): ends); S.duration, S.width, S.height,
-      // S.safeBottom (px the burned-in subtitles take), S.cues ([{ text, t, end }]). Run \`storyshot cues\` to see them.
+      // S.safeBottom (px burned-in subtitles take; 0 without \`subtitles: burn\`), S.cues ([{ text, t, end }]). Run \`storyshot cues\`.
       const S = window.__storyshot;
       const tl = gsap.timeline({ paused: true });
       tl.fromTo('#${id}-line', { opacity: 0, filter: 'blur(8px)' }, { opacity: 1, filter: 'blur(0px)', duration: 0.4, ease: 'power3.out' }, S.at(0));

package/src/outputs.mjs

@@ -129,7 +129,12 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
   // letters with an ink outline on a dark film, ink letters with a white outline on a light one, where
   // white letters would need a dark bar under them. The word being spoken is the accent either way.
   const light = filmGround(cfg) === 'light' && isDark(cfg.theme.ink);
-  const restCol = light ? cfg.theme.ink : '#ffffff', edgeCol = light ? '#ffffff' : cfg.theme.ink, sweep = cfg.theme.accent;
+  const restCol = light ? cfg.theme.ink : '#ffffff', sweep = cfg.theme.accent;
+  // The outline is what separates the letters from the picture, so it has to be the OPPOSITE of them.
+  // `theme.ink` is only dark on a light film — a dark film names its light text colour `ink` — and
+  // taking the outline from it there put a near-white edge around the accent-coloured word being
+  // spoken, which reads as a ghosted double of every letter, crawling along the line as it is read.
+  const edgeCol = light ? '#ffffff' : isDark(cfg.theme.ink) ? cfg.theme.ink : '#000000';
   const shade = light ? [255, 255, 255] : [0, 0, 0];
   if (renderer === 'png') {
     // no libass in this ffmpeg: draw each state of each line (the words spoken so far in the accent

package/src/scene-kit/kit3d.js

@@ -0,0 +1,340 @@
+/* Kit3 — drawn 3D for a storyshot scene: solids shaded by which way they face, with ink edges found
+   in a normal/depth pass, so a shape reads as a textbook figure rather than as a render.
+
+   Why not just light it. A lit render says "photograph"; a diagram has to say "drawing". Three things
+   do that, and none of them is a light:
+     1. Flat tone by FACING. Each face gets one of three tones picked from its own normal — no falloff,
+        no specular, no shadows. Curved things step smoothly between tones so they never staircase.
+     2. INK EDGES drawn after the fact. The scene is rendered a second time into a buffer that holds
+        the view normal, a line tone and the depth; a full-screen pass then marks a pixel as a line
+        where the normal turns a corner or the depth jumps. That gives silhouettes AND creases, which
+        is what a draughtsman draws and what a light never produces.
+     3. A LONG LENS. Perspective at fov 18 is nearly axonometric: parallel edges stay parallel, so the
+        figure reads as a diagram instead of as a photograph of an object.
+   The approach is the standard non-photorealistic one and is the same idea Atlas of Physics uses
+   (MIT, nathanliow/atlas-of-physics); this is storyshot's own implementation of it.
+
+   It draws only when asked. Everything on screen is a function of the timeline's time, so a scene
+   calls eng.render() from its GSAP onUpdate and never from a frame loop — frames are rendered by
+   seeking, and a clock of its own would make every render different.
+
+   The UMD build of three.js carries no addons (no EffectComposer, no ShaderPass), so the two passes
+   and the composite here are written against plain render targets.
+
+   Scenes use it like this:
+
+     const eng = Kit3.engine(canvas, { bg: '#0f1218', ink: '#0a0c10' });
+     const flask = eng.part(eng.scene, { explode: [0, 220, 0] });
+     eng.solid(flask, new THREE.CylinderGeometry(1, 1, 2, 48), { ramp: Kit3.RAMP.glass, tone: 'hi' });
+     eng.look({ target: [0, 0.6, 0], az: -0.7, el: 0.42, dist: 26 });
+     ...
+     tl.fromTo(p, { t: 0 }, { t: S.duration, duration: S.duration, ease: 'none',
+       onUpdate() { eng.explode(k(p.t)); eng.render(); } }, 0);
+*/
+window.Kit3 = (function () {
+  /* How dark a line is, the way a draughtsman grades them: a part that is only context gets a faint
+     edge, the one thing being talked about gets the full one. Stored per solid, read by the edge pass. */
+  const TONE = { ghost: 0.15, faint: 0.3, lo: 0.5, mid: 0.7, hi: 0.85, lit: 1.0 };
+
+  /* A ramp is [top, lightSide, darkSide] — the three tones a solid can show. A film gives its own,
+     in its own palette; these are the neutrals every film can fall back on. */
+  const RAMP = {
+    paper: ['#ffffff', '#f2f1ec', '#d8d6cf'],
+    panel: ['#2b313d', '#222834', '#171b23'],
+    glass: ['#39414f', '#2a313d', '#1d222c'],
+    dead: ['#3a3f4a', '#2f343e', '#262a33'],
+  };
+
+  const hex = (c) => new THREE.Color(c);
+
+  /* ---- the beauty pass: three tones chosen by which way the face points ------------------------ */
+  // The side tone comes from the horizontal part of the world normal, so turning the camera does not
+  // repaint the object: a figure that re-shades while the camera moves reads as lit, not as drawn.
+  // The instancing guard is what lets one call draw a flask's worth of cells: three.js defines
+  // USE_INSTANCING for an InstancedMesh, and the normal has to be turned by the instance too.
+  const SHADE_VERT = `
+    varying vec3 vN;
+    void main() {
+      vec3 n = normal;
+      #ifdef USE_INSTANCING
+        n = mat3(instanceMatrix) * n;
+      #endif
+      vN = normalize(mat3(modelMatrix) * n);
+      #include <begin_vertex>
+      #include <project_vertex>
+    }`;
+  const SHADE_FRAG = `
+    uniform vec3 uTop, uLight, uDark;
+    uniform float uOpacity, uLit;
+    varying vec3 vN;
+    void main() {
+      vec3 n = normalize(vN);
+      // sides: blend the two side tones by how much the face turns towards the light direction.
+      // Continuous, so a cylinder steps through the tones instead of banding into facets.
+      float side = clamp(dot(normalize(vec3(-0.55, 0.0, 0.83)), normalize(vec3(n.x, 0.0, n.z) + 1e-5)) * 0.5 + 0.5, 0.0, 1.0);
+      vec3 c = mix(uDark, uLight, side);
+      c = mix(c, uTop, smoothstep(0.55, 0.95, n.y));            // tops catch the page's light
+      c = mix(c, uDark * 0.94, smoothstep(-0.45, -0.95, n.y));  // undersides sit down
+      c = mix(c, uTop, uLit * 0.4);                             // the one thing being named lifts
+      gl_FragColor = vec4(c, uOpacity);
+    }`;
+
+  /* ---- the line pass: view normal (xy), line tone, depth ---------------------------------------- */
+  // Only xy of the view normal is kept: z is recoverable and the blue channel is worth more as the
+  // per-solid line tone, which is what lets one part be drawn heavier than the rest.
+  const NORM_VERT = `
+    varying vec3 vVN; varying float vDepth;
+    void main() {
+      vec3 n = normal;
+      #ifdef USE_INSTANCING
+        n = mat3(instanceMatrix) * n;
+      #endif
+      vVN = normalize(normalMatrix * n);
+      #include <begin_vertex>
+      #include <project_vertex>
+      vDepth = -mvPosition.z;
+    }`;
+  const NORM_FRAG = `
+    uniform float uTone, uFar;
+    varying vec3 vVN; varying float vDepth;
+    void main() {
+      vec3 n = normalize(vVN);
+      gl_FragColor = vec4(n.xy * 0.5 + 0.5, uTone, clamp(vDepth / uFar, 0.0, 1.0));
+    }`;
+
+  /* ---- the composite: find the edges, ink them over the colour --------------------------------- */
+  const EDGE_FRAG = `
+    uniform sampler2D uColor, uNormal;
+    uniform vec2 uTexel;
+    uniform vec3 uInk;
+    uniform float uNormalCut, uDepthCut, uWeight;
+    varying vec2 vUv;
+
+    vec4 nd(vec2 uv) { return texture2D(uNormal, uv); }
+
+    void main() {
+      vec4 c = texture2D(uColor, vUv);
+      vec4 m = nd(vUv);
+      // four neighbours is enough for a 1 px line and keeps the pass cheap at 1920x1080
+      vec4 l = nd(vUv - vec2(uTexel.x, 0.0)), r = nd(vUv + vec2(uTexel.x, 0.0));
+      vec4 d = nd(vUv - vec2(0.0, uTexel.y)), u = nd(vUv + vec2(0.0, uTexel.y));
+
+      // a crease: the normal turns a corner
+      float dn = max(max(length(l.xy - m.xy), length(r.xy - m.xy)),
+                     max(length(d.xy - m.xy), length(u.xy - m.xy)));
+      // a silhouette: the depth jumps. Scaled by distance so a far edge is not thicker than a near one.
+      float dd = max(max(abs(l.a - m.a), abs(r.a - m.a)), max(abs(d.a - m.a), abs(u.a - m.a)));
+      dd = dd / max(m.a, 0.02);
+
+      float edge = max(smoothstep(uNormalCut, uNormalCut * 2.4, dn),
+                       smoothstep(uDepthCut, uDepthCut * 2.6, dd));
+      // the heaviest tone around the pixel wins, so a lit part keeps its full line against a faint one
+      float tone = max(max(l.b, r.b), max(max(d.b, u.b), m.b));
+      gl_FragColor = vec4(mix(c.rgb, uInk, clamp(edge * tone * uWeight, 0.0, 1.0)), 1.0);
+    }`;
+
+  function engine(canvas, opts = {}) {
+    const W = canvas.width, H = canvas.height;
+    const bg = opts.bg ?? '#ffffff', ink = opts.ink ?? '#18181a', FAR = opts.far ?? 200;
+
+    // A diagram's colours are chosen, not photographed: with colour management off and the output
+    // left linear, a hex in the palette lands in the frame as exactly that hex, and two renders of
+    // the same second are the same pixels.
+    THREE.ColorManagement.enabled = false;
+    const renderer = new THREE.WebGLRenderer({ canvas, antialias: false, preserveDrawingBuffer: true });
+    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
+    renderer.setPixelRatio(1);
+    renderer.setSize(W, H, false);
+    renderer.setClearColor(hex(bg), 1);
+    renderer.autoClear = true;
+
+    const scene = new THREE.Scene();
+    // fov 18: a long lens. Parallel edges stay nearly parallel, which is what makes it read as a figure.
+    const camera = new THREE.PerspectiveCamera(opts.fov ?? 18, W / H, 0.1, FAR);
+
+    // Two buffers at the frame's own size: colour, and (normal.xy, tone, depth).
+    const rtOpts = { minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter, depthBuffer: true, stencilBuffer: false };
+    const rtColor = new THREE.WebGLRenderTarget(W, H, rtOpts);
+    const rtNorm = new THREE.WebGLRenderTarget(W, H, { ...rtOpts, type: THREE.HalfFloatType });
+
+    const quadScene = new THREE.Scene();
+    const quadCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    const edgeMat = new THREE.ShaderMaterial({
+      uniforms: {
+        uColor: { value: rtColor.texture }, uNormal: { value: rtNorm.texture },
+        uTexel: { value: new THREE.Vector2(1 / W, 1 / H) }, uInk: { value: hex(ink) },
+        uNormalCut: { value: opts.creaseCut ?? 0.18 }, uDepthCut: { value: opts.silhouetteCut ?? 0.012 },
+        uWeight: { value: opts.inkWeight ?? 1 },
+      },
+      vertexShader: 'varying vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }',
+      fragmentShader: EDGE_FRAG, depthTest: false, depthWrite: false,
+    });
+    quadScene.add(new THREE.Mesh(new THREE.PlaneGeometry(2, 2), edgeMat));
+
+    const parts = [];                 // everything that can be pulled apart
+    const normMats = new Map();       // one line-pass material per tone value
+
+    const normalFor = (tone) => {
+      if (!normMats.has(tone)) normMats.set(tone, new THREE.ShaderMaterial({
+        uniforms: { uTone: { value: tone }, uFar: { value: FAR } },
+        vertexShader: NORM_VERT, fragmentShader: NORM_FRAG,
+      }));
+      return normMats.get(tone);
+    };
+
+    const api = {
+      THREE, scene, camera, renderer, parts,
+
+      /* A group that can be pulled out of the assembly. `at` is where it sits assembled and `explode`
+         where it goes when pulled apart; explode(k) then moves every part along its own vector.
+         Pass `at` rather than setting .position afterwards: the part remembers where home is, and
+         the next explode(k) would otherwise put it back at the origin instead. */
+      part(parent, { at = [0, 0, 0], explode = [0, 0, 0], name = '' } = {}) {
+        const g = new THREE.Group();
+        g.position.set(...at);
+        g.userData.home = g.position.clone();
+        g.userData.out = new THREE.Vector3(...explode);
+        g.userData.name = name;
+        parent.add(g);
+        parts.push(g);
+        return g;
+      },
+
+      /* One drawn solid. `ramp` is its three tones, `tone` how heavy its ink line is. */
+      solid(parent, geometry, { ramp = RAMP.paper, tone = 'mid', opacity = 1, lit = 0 } = {}) {
+        const [top, light, dark] = ramp;
+        const mat = new THREE.ShaderMaterial({
+          uniforms: {
+            uTop: { value: hex(top) }, uLight: { value: hex(light) }, uDark: { value: hex(dark) },
+            uOpacity: { value: opacity }, uLit: { value: lit },
+          },
+          vertexShader: SHADE_VERT, fragmentShader: SHADE_FRAG,
+          transparent: opacity < 1, depthWrite: opacity >= 1,
+        });
+        const m = new THREE.Mesh(geometry, mat);
+        m.userData.tone = typeof tone === 'number' ? tone : (TONE[tone] ?? TONE.mid);
+        m.userData.shade = mat;
+        parent.add(m);
+        return m;
+      },
+
+      /* Many copies of one shape in one draw call — a flask's worth of cells, a rack of guides.
+         Place them with setMatrixAt + instanceMatrix.needsUpdate, and set .count to how many are
+         on screen this frame; the ones past the count are simply not drawn. */
+      instances(parent, geometry, count, { ramp = RAMP.paper, tone = 'mid', opacity = 1, lit = 0 } = {}) {
+        const probe = api.solid(parent, geometry, { ramp, tone, opacity, lit });
+        parent.remove(probe);
+        const inst = new THREE.InstancedMesh(geometry, probe.material, count);
+        inst.userData = probe.userData;
+        inst.count = 0;
+        // An InstancedMesh is culled against ONE bounding sphere: the geometry's, around the mesh's
+        // own origin. Instances placed anywhere else — a field of particles crossing the frame, cells
+        // laid out across a flask — put nothing in that sphere, so the whole batch is culled and
+        // simply never appears. A diagram holds a handful of batches, so stop culling them.
+        inst.frustumCulled = false;
+        parent.add(inst);
+        return inst;
+      },
+
+      /* Light one solid up without changing its colour: the tone lifts and its line goes to full. */
+      lift(mesh, k) {
+        mesh.userData.shade.uniforms.uLit.value = k;
+        mesh.userData.tone = TONE.faint + (TONE.lit - TONE.faint) * k;
+      },
+
+      /* Fading a solid has to take its LINE with it. The line pass draws every mesh with an opaque
+         material of its own, so a solid at opacity 0 keeps a full-strength ink edge and goes on
+         hanging in the frame as a wireframe ghost. Below a hair's width of opacity the mesh leaves
+         both passes. */
+      fade(mesh, o) {
+        mesh.userData.shade.uniforms.uOpacity.value = o;
+        mesh.userData.shade.transparent = o < 1;
+        mesh.userData.shade.depthWrite = o >= 1;
+        mesh.visible = o > 0.004;
+      },
+
+      /* Place the camera the way a figure is staged: look at a point from an angle and a distance.
+         `shift` slides the whole camera sideways afterwards, in world units along the camera's OWN
+         right axis, which is how you leave the left third of the frame for the words. Offsetting the
+         target instead looks right until the azimuth changes: world x is not screen right, so the
+         subject swings and comes towards the lens as the camera turns. Negative shift = subject right. */
+      look({ target = [0, 0, 0], az = -0.7, el = 0.42, dist = 30, shift = 0, rise = 0 } = {}) {
+        const [tx, ty, tz] = target;
+        camera.position.set(tx + Math.sin(az) * Math.cos(el) * dist, ty + Math.sin(el) * dist, tz + Math.cos(az) * Math.cos(el) * dist);
+        camera.lookAt(tx, ty, tz);
+        if (shift || rise) {
+          camera.updateMatrixWorld(true);
+          const right = new THREE.Vector3().setFromMatrixColumn(camera.matrixWorld, 0);
+          const up = new THREE.Vector3().setFromMatrixColumn(camera.matrixWorld, 1);
+          camera.position.addScaledVector(right, shift).addScaledVector(up, rise);
+          camera.updateMatrixWorld(true);
+        }
+      },
+
+      /* 0 = assembled, 1 = fully apart. One number drives the whole exploded view. */
+      explode(k) {
+        for (const g of parts) g.position.copy(g.userData.home).addScaledVector(g.userData.out, k);
+      },
+
+      /* Two passes and the composite. Called from the timeline, never from a loop. */
+      render() {
+        renderer.setRenderTarget(rtColor);
+        renderer.setClearColor(hex(bg), 1);
+        renderer.clear();
+        renderer.render(scene, camera);
+
+        // the line pass: swap every mesh to its tone's normal material, then swap back
+        const saved = [];
+        scene.traverse((o) => {
+          if (o.isMesh) { saved.push([o, o.material]); o.material = normalFor(o.userData.tone ?? TONE.mid); }
+        });
+        renderer.setRenderTarget(rtNorm);
+        // far depth and a normal that matches nothing, so the background never grows an edge of its own
+        renderer.setClearColor(0x000000, 1);
+        renderer.clear();
+        renderer.render(scene, camera);
+        for (const [o, m] of saved) o.material = m;
+
+        renderer.setRenderTarget(null);
+        renderer.render(quadScene, quadCam);
+      },
+    };
+    return api;
+  }
+
+  /* A box with soft corners and a bevelled edge, standing on y = 0. A sharp box drawn with ink edges
+     reads as a crate; most lab plastic is rounded, and the bevel is what gives the silhouette the
+     double line that says "moulded object" rather than "cube". */
+  function slab(w, h, d, r = 0.6, bevel = 0.14) {
+    const x = w / 2, z = d / 2, rr = Math.max(0.01, Math.min(r, x - 0.01, z - 0.01));
+    const s = new THREE.Shape();
+    s.moveTo(-x + rr, -z);
+    s.lineTo(x - rr, -z); s.quadraticCurveTo(x, -z, x, -z + rr);
+    s.lineTo(x, z - rr); s.quadraticCurveTo(x, z, x - rr, z);
+    s.lineTo(-x + rr, z); s.quadraticCurveTo(-x, z, -x, z - rr);
+    s.lineTo(-x, -z + rr); s.quadraticCurveTo(-x, -z, -x + rr, -z);
+    const g = new THREE.ExtrudeGeometry(s, {
+      depth: Math.max(0.01, h - bevel * 2), bevelEnabled: bevel > 0,
+      bevelSize: bevel, bevelThickness: bevel, bevelSegments: 2, curveSegments: 8,
+    });
+    g.rotateX(-Math.PI / 2);   // ExtrudeGeometry grows along +Z; stand it up on +Y
+    g.translate(0, bevel, 0);  // and sit it on the ground rather than straddling it
+    return g;
+  }
+
+  /* A seeded random number generator (mulberry32). A scene is rendered by seeking, and the same
+     second has to come back the same pixels every time, so `Math.random()` is banned outright —
+     scattering cells in a flask or jittering a crowd needs a generator that starts from a number.
+     Give each scattered thing its own seed so adding one does not reshuffle the rest. */
+  function rng(seed = 1) {
+    let a = (seed >>> 0) + 0x6d2b79f5;
+    return function () {
+      a = (a + 0x6d2b79f5) >>> 0;
+      let t = Math.imul(a ^ (a >>> 15), 1 | a);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  return { engine, slab, rng, TONE, RAMP };
+})();

package/src/scene-tools.mjs

@@ -50,15 +50,24 @@ export async function previewScene(cfg, stepNo, { at, check = true, log = consol
       for (const f of j.findings ?? []) {
         // the wrapper is ours: only what is about the scene file counts
         if (f.file && !/scene\.html$/.test(f.file)) continue;
+        // lint reads the composition alone, so it cannot see that `scenes: { three: true }` already
+        // loaded three.js and Kit3 in the page around it
+        if (f.code === 'missing_three_script' && cfg.sceneKit?.three) continue;
         (f.severity === 'error' ? lint.errors : f.severity === 'warning' ? lint.warnings : []).push(`${f.code}: ${f.message}${f.fixHint ? ` — ${f.fixHint}` : ''}`);
       }
     } catch { if (r.code !== 0) lint.errors.push((r.err || r.out).trim().split('\n').slice(-3).join(' | ')); }
   }
 
   // stills: as each phrase is spoken (a beat into it), and the end
-  let times = at?.length ? at : [...local.map((c) => c.t + Math.min(0.9, (c.end - c.t) * 0.6)), seconds - 0.05];
-  times = [...new Set(times.map((t) => +Math.max(0, Math.min(seconds - 0.02, t)).toFixed(2)))].sort((a, b) => a - b);
-  if (times.length > 12) times = Array.from({ length: 12 }, (_, k) => times[Math.round(k * (times.length - 1) / 11)]);
+  // HOLD is a probe, not a shot worth looking at: the same picture at HOLD and at the end means
+  // nothing has moved for the last 2.5 s (see "does the film end, or does it just stop?" below).
+  const HOLD = seconds > 4 ? +(seconds - 2.55).toFixed(2) : null;
+  let times = at?.length ? at : [...local.map((c) => c.t + Math.min(0.9, (c.end - c.t) * 0.6)), HOLD, seconds - 0.05];
+  times = [...new Set(times.filter((t) => t != null).map((t) => +Math.max(0, Math.min(seconds - 0.02, t)).toFixed(2)))].sort((a, b) => a - b);
+  if (times.length > 12) {
+    times = Array.from({ length: 12 }, (_, k) => times[Math.round(k * (times.length - 1) / 11)]);
+    if (HOLD != null && !at?.length && !times.includes(HOLD)) times = [...new Set([...times, HOLD])].sort((a, b) => a - b);
+  }
   const shots = path.join(dir, 'shots');
   const r = await hyperframesRun(['snapshot', dir, '--at', times.join(','), '--no-end', '--output', shots], { log });
   if (r.code !== 0) throw new Error(`the scene did not load in HyperFrames: ${(r.err || r.out).trim().split('\n').filter(Boolean).slice(-4).join(' | ')}`);
@@ -97,7 +106,26 @@ export async function previewScene(cfg, stepNo, { at, check = true, log = consol
       found[k] = [...groups.values()].map((ws) => (ws.length > 1 ? `${ws[0]} (and ${ws.length - 1} more like it)` : ws[0]));
     }
   }
-  return { dir, seconds, cues: local, times, images, sheet, sheets, lint, check: check ? found : null, subs: ctx.subs };
+  // Does the film end, or does it just stop? A recap scene adds and adds, and its last frame — the
+  // fullest of the whole film — is then held until the file runs out. The layout check samples too
+  // few moments to see it, but the stills are already rendered: if the last two are the same picture
+  // and they are seconds apart, the film has no last beat. (Only the film's last scene: a held frame
+  // in the middle is a pause, and a scene handing over to an end card has already done its part.)
+  const last = cfg.steps.map((x, k) => (x.hidden ? -1 : k)).filter((k) => k >= 0).at(-1);
+  const hold = HOLD == null ? -1 : times.indexOf(HOLD);
+  if (images.length === times.length && hold >= 0 && hold < times.length - 1 && last === i && !cfg.endCard) {
+    const same = (a, b) => { try { return fs.readFileSync(a).equals(fs.readFileSync(b)); } catch { return false; } };
+    if (same(images[images.length - 1], images[hold])) {
+      found.warnings.push(
+        `frozen_ending (at ${times[times.length - 1].toFixed(1)}s): nothing has changed on screen since ${times[hold].toFixed(1)}s, ` +
+        `so the film ends on a still frame of its fullest moment. A frozen picture is usually the symptom: check the WORDS first — read this ` +
+        `scene's say: line alone, and if it summarises and stops rather than concluding, the film has no ending to show. An explainer ends on a ` +
+        `closing beat of its own after the recap: what this actually means, what is still open, and one thought to leave with. Then clear everything ` +
+        `except the one thing the viewer should leave holding, land that move ON the final words, and prefer a move still running when the file ends`);
+    }
+  }
+  return { dir, seconds, cues: local, times, images, sheet, sheets, lint,
+    check: check || found.warnings.length ? found : null, subs: ctx.subs };
 }
 
 // What to do about the findings agents meet most in scenes (HyperFrames' own messages point at its docs).

package/src/scenes.mjs

@@ -12,9 +12,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 export const SCENE_DEFAULTS = { lead: 0.5, tail: 0.8 };
 export const GSAP_URL = 'https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js';
+// r160 is the last three.js with a classic-script build; everything after it is ESM only, and a
+// module script in a scene would run after HyperFrames has already collected the timelines.
+export const THREE_URL = 'https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js';
+// That build announces its own deprecation the moment it loads, and the layout check reports every
+// console warning, so a 3D scene would carry one forever. Drop that one line and nothing else.
+const THREE_QUIET = `(function () { const w = console.warn; console.warn = function (m) { if (typeof m === 'string' && /build\\/three(\\.min)?\\.js" are deprecated/.test(m)) return; return w.apply(console, arguments); }; })();`;
 
 // How long a scene plays: a fixed `duration`, else its narration plus a lead-in and a tail.
 export function sceneSeconds(step, voiceLen) {
@@ -24,7 +33,7 @@ export function sceneSeconds(step, voiceLen) {
 }
 
 // What a scene file declares, and what is wrong with it (errors stop the render, warnings don't).
-export function sceneInfo(file, { width, height } = {}) {
+export function sceneInfo(file, { width, height, three = null } = {}) {
   const errors = [], warnings = [];
   if (!fs.existsSync(file)) return { errors: [`the scene ${file} does not exist — write it (\`storyshot init --purpose explainer\` writes a starter)`], warnings };
   const html = fs.readFileSync(file, 'utf8');
@@ -46,6 +55,11 @@ export function sceneInfo(file, { width, height } = {}) {
   if (/repeat\s*:\s*-1/.test(html)) errors.push(`${name}: repeat: -1 never ends; repeat a fixed number of times`);
   if (!/__storyshot/.test(html)) warnings.push(`${name}: times nothing from window.__storyshot — read them from its cues (S.at(k)) so the animation stays on the words when the narration changes`);
   if (/["'(]\/assets\//.test(html)) errors.push(`${name}: asset paths are relative: "assets/…", not "/assets/…"`);
+  // A 3D scene whose storyboard forgot `scenes: { three: true }` throws on its first line and
+  // renders an empty frame — the scene still "works" everywhere except in the video.
+  if (three === false && /\b(THREE|Kit3)\s*\./.test(html)) {
+    errors.push(`${name}: uses ${/\bKit3\s*\./.test(html) ? 'Kit3' : 'THREE'} but the storyboard does not load it — add \`scenes: { three: true }\` (with your css/js kit, if any)`);
+  }
   return { id, html, errors, warnings };
 }
 
@@ -124,7 +138,8 @@ html,body{width:${W}px;height:${H}px;overflow:hidden;background:#000}
 #root{position:relative;width:100%;height:100%;font-family:var(--font)}
 </style>
 <script>${sceneRuntime(job, ctx)}
-${GSAP_GUARD}</script>
+${GSAP_GUARD}${job.kit?.three ? `\n${THREE_QUIET}` : ''}</script>
+${job.kit?.three ? `<script src="${THREE_URL}"></script>\n<script src="kit3d.js"></script>` : ''}
 ${(job.kit?.css ?? []).map((f, k) => `<link rel="stylesheet" href="kit/${k}-${path.basename(f)}">`).join('\n')}
 ${(job.kit?.js ?? []).map((f, k) => `<script src="kit/${k}-${path.basename(f)}"></script>`).join('\n')}
 </head><body>
@@ -140,15 +155,20 @@ export const fileHash = (f) => crypto.createHash('sha1').update(fs.readFileSync(
 
 // Write a scene's project into `dir` (index.html, the scene, its assets). Returns the scene info.
 export function writeSceneProject(job, ctx, dir) {
-  const info = sceneInfo(job.scene.file, { width: ctx.W, height: ctx.H });
+  const info = sceneInfo(job.scene.file, { width: ctx.W, height: ctx.H, three: !!job.kit?.three });
   if (info.errors.length) throw new Error(info.errors.join('; '));
   fs.mkdirSync(path.join(dir, 'compositions'), { recursive: true });
   fs.writeFileSync(path.join(dir, 'index.html'), sceneDoc(job, ctx, info));
   fs.writeFileSync(path.join(dir, 'compositions', 'scene.html'), info.html);
+  // `scenes: { three: true }`: storyshot's own drawn-3D helpers, loaded before the storyboard's kit
+  if (job.kit?.three) fs.copyFileSync(path.join(HERE, 'scene-kit', 'kit3d.js'), path.join(dir, 'kit3d.js'));
   // the storyboard's scene kit, shared by every scene
-  for (const [kind, list] of Object.entries(job.kit ?? {})) for (const [k, f] of list.entries()) {
-    fs.mkdirSync(path.join(dir, 'kit'), { recursive: true });
-    fs.copyFileSync(f, path.join(dir, 'kit', `${k}-${path.basename(f)}`));
+  for (const [kind, list] of Object.entries(job.kit ?? {})) {
+    if (!Array.isArray(list)) continue;
+    for (const [k, f] of list.entries()) {
+      fs.mkdirSync(path.join(dir, 'kit'), { recursive: true });
+      fs.copyFileSync(f, path.join(dir, 'kit', `${k}-${path.basename(f)}`));
+    }
   }
   for (const [k, f] of Object.entries(sceneAssets(job.scene.file))) {
     fs.mkdirSync(path.dirname(path.join(dir, 'assets', k)), { recursive: true });