storyshot 0.8.0 → 0.10.0

package/README.md

@@ -259,9 +259,11 @@ by hand.
 ```yaml
 url: https://example.com
 out: acme-promo.mp4                             # relative to this file; default: <file name>.mp4
-viewport: { width: 1600, height: 900 }          # CSS px the site is laid out at
-output: { width: 1920, height: 1080, fps: 30 }  # same aspect ratio; use 1080x1920 with a 900x1600 viewport for vertical
-theme: { accent: "#d9f75b", ink: "#0f172a", font: Inter }
+aspect: landscape                               # landscape (16:9, default) | portrait (9:16, 1080x1920: a phone upright, and most short-video feeds) | square (1:1). 16:9, 9:16 and 1:1 work too,
+                                                # and so does any other ratio: "3:4" is 1080x1440 (what Xiaohongshu fills), "4:5" is 1080x1350. The short side is always 1080
+viewport: { width: 1600, height: 900 }          # CSS px the site is laid out at; leave it out and it follows the output's shape
+output: { width: 1920, height: 1080, fps: 30 }  # an exact size, when `aspect` is not the shape you want; the viewport must share its aspect ratio
+theme: { accent: "#d9f75b", ink: "#0f172a", font: Inter, paper: "#e9ddc4" }   # paper: the film's own background. The intro, section and end cards are built on it instead of the default near-white, which is cold against a warm film. Leave it out and the cards follow `ground:`
 music: { bpm: 120, volume: 1 }                  # or { file: track.mp3 }, or false
 sfx: true                                       # click / whoosh / riser sounds; clicks = no whooshes on cards and page changes, and no rising sound under a riser step, only its chime (tutorial and course default); false = none
 voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceover, see below
@@ -501,7 +503,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,12 +517,38 @@ 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.
+follow it. When the film is drawn on a *colour* rather than on plain light or
+dark, give it as `theme: { paper: "#e9ddc4" }` and the title, section and end
+cards are built on that ground instead of the default near-white, which is a
+cold blue-grey and reads as a different film. The playbook's "The look follows
+the subject" has the styles and what each ground costs.
+
+`aspect: portrait` makes the video 1080x1920 — a phone held upright, and what
+most short-video feeds want (`square` is 1:1, `landscape` 16:9 is the default,
+and `output:` still takes an exact size). The feeds do not all want the same
+tall frame, so any ratio works written out: `aspect: "3:4"` is 1080x1440, which
+is the shape Xiaohongshu's feed fills and the one it crops a 9:16 video down
+to, and `aspect: "4:5"` is 1080x1350 for an Instagram feed. The short side is
+always 1080 and both sides come out even. A portrait film is not a landscape
+film resized: a tall frame reads top to bottom, so a scene that puts an object
+beside its labels stacks them instead, and a side-by-side comparison becomes an
+upper and a lower half. Each scene's root carries `data-width="1080"
+data-height="1920"`, and `storyshot check` says so when it does not match. The
+playbook's "Portrait" has the type scale and the margins a feed covers.
 
 `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

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.10.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
@@ -590,6 +681,17 @@ much cheaper to show one previewed scene in the chosen style and ask.
   - 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`.
+  - But `data-layout-ignore` takes an element out of the check entirely, so two
+    ignored elements may overlap and nothing will say so. A source credit
+    running under a "schematic" mark in the same corner is the usual way this
+    bites. Read that corner off the still.
+- **A CSS rule beats an SVG presentation attribute.** If your scene CSS says
+  `.fig .ln { fill: none; stroke-width: 4 }`, then `fill="#c00"` or
+  `stroke-width="7"` *as attributes* on a `.ln` element do nothing at all —
+  silently, with no warning. Shapes come out unfilled and strokes come out the
+  wrong weight. Set them as inline **styles** instead, or give the element its
+  own class. This is the single most common reason a drawn scene looks wrong
+  while every check passes.
 - **"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:`.
@@ -597,6 +699,10 @@ much cheaper to show one previewed scene in the chosen style and ask.
   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.
+  `ground` only picks light or dark, so a film drawn on a *colour* — warm
+  paper, a blueprint blue — still opens on storyshot's near-white, which reads
+  as cold and as a different film. Give that colour as `theme: { paper:
+  "#e9ddc4" }` and every card tone is mixed from it and the ink instead.
 
 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
@@ -606,7 +712,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.
@@ -620,6 +730,47 @@ 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.
 
+### Portrait
+
+`aspect: portrait` makes the video 1080×1920 — a phone held upright, which is
+what most short-video feeds want. `square` is 1:1 and `landscape` (16:9) is
+the default; `output:` still takes an exact size when none of them fits, and
+`viewport:` now follows the output's shape unless it is given.
+
+**Ask which feed it is for before you pick 9:16.** The tall frames are not
+interchangeable. Any ratio can be written out — `aspect: "3:4"` is 1080×1440,
+`aspect: "4:5"` is 1080×1350 — the short side is always 1080. 9:16 is right for
+TikTok, Reels, Shorts and Douyin. **Xiaohongshu (RED) fills its feed with 3:4**
+and crops a 9:16 video to it, so a 9:16 film posted there loses the top and
+bottom of every frame — which, in a film that stacks its beats down a column, is
+where the first and last beat live. 3:4 is a different staging problem again:
+the frame is only 1.33× taller than wide while the type still has to grow for a
+1080-wide frame, so it holds *less* than 16:9 did. Cut harder.
+
+A portrait film is **not a 16:9 film resized**. The frame is 1.8× taller than
+it is wide, so rebuild each scene rather than scaling it:
+
+- **One column, read top to bottom.** A 16:9 scene puts the object on one side
+  and its labels on the other. In portrait that side-by-side has nowhere to go:
+  stack it instead — the object, then the label under it, then the next beat
+  under that. A scene that is a left-to-right comparison in 16:9 becomes a
+  top-and-bottom one.
+- **Fewer things, bigger.** 1080 px of width is half what you had. Carry one
+  idea per screenful, and give the subject the middle of the frame, where a
+  thumb is not.
+- **Type goes up, not down.** The 28 px floor is measured at 1080p, so in
+  portrait it is a *width* floor: 28 px across 1080 px reads like 50 px across
+  1920. Titles 92–120 px, leads 52–64 px, labels 36–40 px.
+- **Keep the ends clear.** Feeds put a caption, a handle and buttons over the
+  bottom fifth and a status bar over the top. Hold the content between about
+  12% and 80% of the height. With `subtitles: burn`, `S.safeBottom` is already
+  22% in portrait (16% in landscape) — keep above it.
+- **Burn the subtitles.** A portrait film is usually watched in a feed that
+  autoplays muted, which is the one case where `subtitles: burn` earns its
+  cost. Say so when you do it.
+- Each scene's root still carries `data-width="1080" data-height="1920"`, and
+  `storyshot check` tells you when it does not match the video.
+
 ## 4. Render, look, fix
 
 1. `render_video` (use `draft: true` while iterating if the voice is

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

@@ -36,7 +36,7 @@ export function narrationLint(text) {
   return { tells, long };
 }
 
-const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'ground', 'lang', 'colorScheme',
+const TOP = ['name', 'url', 'out', 'purpose', 'aspect', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'ground', 'lang', 'colorScheme',
   'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card', 'hyperframes', 'scenes'];
 const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc', 'scene'];
 const SCENE = ['file', 'title', 'lead', 'tail'];
@@ -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

@@ -5,7 +5,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { renderHyperframesCards } from './hyperframes.mjs';
-import { sceneSeconds, filmGround } from './scenes.mjs';
+import { sceneSeconds, filmGround, mixColour, shadeColour } from './scenes.mjs';
 
 const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 const md = (s, accent) => esc(s).replace(/\*\*(.+?)\*\*/g, `<b style="color:${accent};font-weight:700">$1</b>`);
@@ -388,11 +388,18 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // draw on a dark ground get dark cards, so a dark film doesn't cut to a white card; `ground: light |
   // dark` says it outright and `cards: light | dark` overrides the cards alone
   const darkCards = cfg.cards === 'dark' || (cfg.cards !== 'light' && filmGround(cfg) === 'dark');
-  const CK = darkCards
-    ? { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#1e2a44 0%,#111830 60%,#0b1020 100%)`, title: '#f1f5f9', sub: '#cbd5e1', muted: '#94a3b8', item: '#e2e8f0', track: '#26314d',
-      pillBg: '#1a2238', pillFg: '#e2e8f0', pillLine: '1px solid #33405f', ctaBg: accent, ctaFg: ink, shadow: 'rgba(0,0,0,.45)' }
-    : { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#ffffff 0%,#eef2f7 60%,#e2e8f0 100%)`, title: ink, sub: '#334155', muted: '#64748b', item: '#1e293b', track: '#e2e8f0',
-      pillBg: ink, pillFg: '#e2e8f0', pillLine: 'none', ctaBg: ink, ctaFg: '#fff', shadow: 'rgba(15,23,42,.25)' };
+  // `theme.paper`: the film's own ground. Every card tone is then mixed from that paper and the ink,
+  // so a film drawn on warm paper does not open on a cold blue-white title card.
+  const paper = cfg.theme.paper;
+  const CK = paper
+    ? { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,${shadeColour(paper, darkCards ? -0.07 : 0.08)} 0%,${paper} 58%,${shadeColour(paper, darkCards ? 0.05 : -0.07)} 100%)`,
+      title: ink, sub: mixColour(ink, paper, 0.24), muted: mixColour(ink, paper, 0.46), item: mixColour(ink, paper, 0.12), track: mixColour(ink, paper, 0.76),
+      pillBg: ink, pillFg: paper, pillLine: 'none', ctaBg: ink, ctaFg: paper, shadow: `${mixColour(ink, '#000000', 0.3)}40` }
+    : darkCards
+      ? { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#1e2a44 0%,#111830 60%,#0b1020 100%)`, title: '#f1f5f9', sub: '#cbd5e1', muted: '#94a3b8', item: '#e2e8f0', track: '#26314d',
+        pillBg: '#1a2238', pillFg: '#e2e8f0', pillLine: '1px solid #33405f', ctaBg: accent, ctaFg: ink, shadow: 'rgba(0,0,0,.45)' }
+      : { bg: `radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#ffffff 0%,#eef2f7 60%,#e2e8f0 100%)`, title: ink, sub: '#334155', muted: '#64748b', item: '#1e293b', track: '#e2e8f0',
+        pillBg: ink, pillFg: '#e2e8f0', pillLine: 'none', ctaBg: ink, ctaFg: '#fff', shadow: 'rgba(15,23,42,.25)' };
   const card = (c, logoPath, { thinkAt = 0 } = {}) => {
     const image = c.imageFile && fs.existsSync(c.imageFile)
       ? `<img class="a rise" src="data:image/${path.extname(c.imageFile).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(c.imageFile).toString('base64')}" style="animation-delay:.4s;max-width:${W * 0.6}px;max-height:${H * 0.42}px;border-radius:${12 * H / 1080}px;box-shadow:0 ${12 * H / 1080}px ${36 * H / 1080}px rgba(15,23,42,.18)">` : '';
@@ -557,7 +564,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // doesn't render) the built-in ones. A launch outro is drawn with transparency over the last frame,
   // which the ffmpeg pass below zooms into the page.
   const hf = cfg.hyperframes || cards.some((c) => c.scene) ? await renderHyperframesCards(hfJobs(), {
-    W, H, FPS, dark: darkCards, accent, ink, font, lang: cfg.lang, labels: cfg.labels, opts: cfg.hyperframes, work: cfg.work, subs: cfg.subtitles === 'burn',
+    W, H, FPS, dark: darkCards, accent, ink, paper, font, lang: cfg.lang, labels: cfg.labels, opts: cfg.hyperframes, work: cfg.work, subs: cfg.subtitles === 'burn',
     frame: { FX, FY, FW, FH, ...Object.fromEntries([['frameBg', 'frame-bg.png'], ['chrome', 'frame-chrome.png'], ['url', 'frame-url0.png']]
       .map(([k, f]) => [k, cfg.frame && fs.existsSync(path.join(cfg.work, f)) ? path.join(cfg.work, f) : null])) },
   }, { log, warn }) : {};
@@ -659,7 +666,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

@@ -4,7 +4,7 @@ import path from 'node:path';
 import YAML from 'yaml';
 import { VOICE_DEFAULTS, kokoroVoiceFor, qwenVoiceFor } from './voice.mjs';
 import { QWEN_VOICES, qwenSupported, qwenVoice } from './qwen-tts.mjs';
-import { SCENE_DEFAULTS } from './scenes.mjs';
+import { SCENE_DEFAULTS, toRgb } from './scenes.mjs';
 
 // Built-in labels drawn into the video, by `lang` (e.g. es, es-MX); other languages get English
 export const LABELS = {
@@ -54,6 +54,27 @@ export const PACES = {
 
 export const FRAME_STYLES = ['aurora', 'studio', 'dark', 'pastel', 'blur'];
 
+// The shape of the video, as one word in the storyboard: `aspect: portrait`. Portrait is a phone held
+// upright and is what every short-video feed wants; square still plays either way round.
+export const ASPECTS = { landscape: [1920, 1080], portrait: [1080, 1920], square: [1080, 1080] };
+export const ASPECT_ALIASES = {
+  '16:9': 'landscape', wide: 'landscape', horizontal: 'landscape',
+  '9:16': 'portrait', vertical: 'portrait', tall: 'portrait',
+  '1:1': 'square',
+};
+// Any other shape is written as the ratio itself — `aspect: "3:4"` → 1080x1440, `aspect: "4:5"` →
+// 1080x1350 — because the feeds do not all want the same tall frame: a 9:16 video is cropped in
+// Xiaohongshu's feed, where 3:4 is what fills it. The short side is always 1080, and both sides come
+// out even, which h.264 requires.
+export function aspectFrame(ratio) {
+  const m = String(ratio).match(/^\s*(\d+(?:\.\d+)?)\s*[:x/]\s*(\d+(?:\.\d+)?)\s*$/);
+  const [w, h] = [Number(m?.[1]), Number(m?.[2])];
+  if (!m || !(w > 0) || !(h > 0)) return null;
+  const even = (n) => 2 * Math.round(n / 2);
+  return w >= h ? [even((1080 * w) / h), 1080] : [1080, even((1080 * h) / w)];
+}
+export const orientationOf = (w, h) => (h > w ? 'portrait' : h === w ? 'square' : 'landscape');
+
 export const VIDEO_DIR = 'videos';
 export const KINDS = { pitch: 'promo', tutorial: 'tutorial', course: 'lesson', docs: 'docs', explainer: 'explainer' };
 // pxgenius.ai → pxgenius; an IP or a port is kept whole so two internal apps don't share a name
@@ -94,11 +115,29 @@ export function loadConfig(file, { draft = false } = {}) {
   // only a storyboard made entirely of scenes has nothing to record
   if (!raw.url && !raw.steps.every((s) => s?.scene || s?.hidden)) throw new Error('demo.yaml: `url` is required (only a storyboard whose steps are all scenes can leave it out)');
 
-  const viewport = { width: 1600, height: 900, ...raw.viewport };
-  const output = { width: 1920, height: 1080, fps: 30, ...raw.output };
+  // aspect: the shape of the video in one word — landscape (16:9, the default), portrait (9:16: a
+  // phone held upright, and most short-video feeds) or square (1:1) — or as a ratio, `3:4` for the
+  // shape Xiaohongshu's feed fills. `output` still wins when it is given outright, so an unusual
+  // size stays possible.
+  const aspectName = raw.aspect == null ? null : (ASPECT_ALIASES[String(raw.aspect).toLowerCase()] ?? String(raw.aspect).toLowerCase());
+  const aspectSize = aspectName == null ? null : (ASPECTS[aspectName] ?? aspectFrame(aspectName));
+  if (aspectName && !aspectSize) throw new Error(`aspect must be one of ${Object.keys(ASPECTS).join(', ')}, or a ratio like "3:4" (16:9, 9:16 and 1:1 also work)`);
+  const [AW, AH] = aspectSize ?? ASPECTS.landscape;
+  const output = { width: AW, height: AH, fps: 30, ...raw.output };
+  // The browser viewport is only what a recording is captured at, and it has to share the output's
+  // aspect ratio. Unless it is given, it follows the output — so a portrait or square video never
+  // asks for that arithmetic, and a storyboard of scenes (which records nothing) never mentions it.
+  const long = 1600;
+  const viewport = {
+    ...(output.width >= output.height
+      ? { width: long, height: Math.round((long * output.height) / output.width) }
+      : { width: Math.round((long * output.width) / output.height), height: long }),
+    ...raw.viewport,
+  };
   const scale = output.width / viewport.width;
   if (Math.abs(viewport.height * scale - output.height) > 1) {
-    throw new Error(`viewport ${viewport.width}x${viewport.height} and output ${output.width}x${output.height} must have the same aspect ratio`);
+    throw new Error(`viewport ${viewport.width}x${viewport.height} and output ${output.width}x${output.height} must have the same aspect ratio`
+      + ' (leave `viewport` out and it follows the output)');
   }
 
   const purpose = raw.purpose ?? 'pitch';
@@ -199,10 +238,18 @@ export function loadConfig(file, { draft = false } = {}) {
   for (const c of clips) if (!['gif', 'webm', 'mp4', 'png'].includes(c)) throw new Error('clips must be gif, webm, mp4 or png (or a list of them)');
   if (music?.file) music.file = path.resolve(dir, music.file);
   if (music?.style && !['calm'].includes(music.style)) throw new Error('music.style must be calm (or leave it out for the upbeat synth)');
+  if (raw.theme?.paper != null && !toRgb(raw.theme.paper)) throw new Error('theme.paper is the film\'s background colour, as a hex or rgb() value (e.g. "#e9ddc4")');
 
   // 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,
@@ -224,7 +271,13 @@ export function loadConfig(file, { draft = false } = {}) {
     scrollOffset: raw.scrollOffset ?? 40,
     // burned-in subtitles sit at the bottom, so captions move to the top
     captionPosition: raw.captionPosition ?? (pick('subtitles') === 'burn' ? 'top' : 'bottom'),
-    theme: { accent: '#d9f75b', ink: '#0f172a', font: 'Inter', ...raw.theme },
+    // theme.paper: the film's own background colour. The title, section and end cards are built on it
+    // instead of storyshot's default near-white, which is a cold blue-grey and cuts badly against a
+    // film drawn on warm paper. Leave it out and the cards keep the default ground for `ground:`.
+    theme: { accent: '#d9f75b', ink: '#0f172a', font: 'Inter', paper: null, ...raw.theme },
+    // landscape | portrait | square, for anything that lays out by the shape rather than the pixels
+    // which way up the finished video is, whatever got it there: a named aspect, a ratio or `output`
+    aspect: orientationOf(output.width, output.height),
     setup: raw.setup ?? [],
     steps,
     endCard,

package/src/hyperframes.mjs

@@ -16,10 +16,11 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { writeSceneProject, sceneAssets, fileHash } from './scenes.mjs';
+import { writeSceneProject, sceneAssets, fileHash, mixColour, shadeColour } 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'];
@@ -151,6 +152,9 @@ const isCmd = (cta) => /^\$?\s*(npx|npm|pnpm|yarn|bun|pip|pipx|uv|brew|curl|git|
 const lum = (hex) => { const m = /^#?([0-9a-f]{6})$/i.exec(hex ?? ''); if (!m) return 0.5; const n = parseInt(m[1], 16); return (0.299 * (n >> 16) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255)) / 255; };
 // a light accent (a highlighter colour) made dark enough to draw lines and text with on white: same
 // hue, lightness capped (lower for yellows and greens, which read light at any lightness)
+// Fine noise, laid over a flat or near-flat card ground so an 8-bit gradient does not contour.
+const GRAIN = `url('data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200"><filter id="n"><feTurbulence type="fractalNoise" baseFrequency=".9" numOctaves="2" stitchTiles="stitch"/><feColorMatrix values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 .055 0"/></filter><rect width="200" height="200" filter="url(#n)"/></svg>')}')`;
+
 const deepen = (hex) => {
   const m = /^#?([0-9a-f]{6})$/i.exec(hex ?? ''); if (!m) return '#4f46e5';
   const n = parseInt(m[1], 16), [r, g, b] = [n >> 16, (n >> 8) & 255, n & 255].map((c) => c / 255);
@@ -300,9 +304,16 @@ function lesson(job, ctx) {
   const { W, H, dark, font, opts } = ctx, u = Math.min(H, W * 1.15) / 1080, D = job.seconds, c = job.card, accent = ctx.accent, ink = ctx.ink;
   // portrait with burned-in subtitles: the subtitles sit above the bottom fifth, so the card keeps above them
   const lift = ctx.subs && H > W ? H * 0.22 : 0;
-  const P = dark
-    ? { ground: '#0c1222', ground2: '#070b16', glow: '#1b2744', text: '#eef2f8', muted: '#9aa8bd', line: '#2a3550', chip: '#131c31', chipLine: '#26324d', band: 0.14, shadow: 'rgba(0,0,0,.35)' }
-    : { ground: '#eef2f7', ground2: '#dfe6ef', glow: '#ffffff', text: ink, muted: '#56667d', line: '#c6d0dc', chip: '#ffffff', chipLine: '#d6dee8', band: 0.17, shadow: 'rgba(13,27,46,.08)' };
+  // `theme.paper`: the film's own ground, which every card tone is then mixed from, so a film drawn on
+  // warm paper opens on that paper instead of storyshot's default cold blue-white.
+  const paper = ctx.paper;
+  const P = paper
+    ? { ground: paper, ground2: shadeColour(paper, dark ? 0.035 : -0.045), glow: shadeColour(paper, dark ? -0.045 : 0.05), text: ink,
+      muted: mixColour(ink, paper, 0.44), line: mixColour(ink, paper, 0.7), chip: shadeColour(paper, dark ? 0.07 : 0.06),
+      chipLine: mixColour(ink, paper, 0.74), band: dark ? 0.14 : 0.17, shadow: `${mixColour(ink, '#000000', 0.35)}1f` }
+    : dark
+      ? { ground: '#0c1222', ground2: '#070b16', glow: '#1b2744', text: '#eef2f8', muted: '#9aa8bd', line: '#2a3550', chip: '#131c31', chipLine: '#26324d', band: 0.14, shadow: 'rgba(0,0,0,.35)' }
+      : { ground: '#eef2f7', ground2: '#dfe6ef', glow: '#ffffff', text: ink, muted: '#56667d', line: '#c6d0dc', chip: '#ffffff', chipLine: '#d6dee8', band: 0.17, shadow: 'rgba(13,27,46,.08)' };
   const strong = dark ? accent : deepen(accent); // accent as text/line on this ground
   const bandText = opts.band ? String(opts.band).replace(/\s+/g, '') : null;
   const colorOf = (ch) => (opts.bandColors === 'aminoacid' ? RES[ch] : opts.bandColors === 'nucleotide' ? NUC[ch] : null) ?? strong;
@@ -345,7 +356,9 @@ function lesson(job, ctx) {
 
   const css = `${fontFaces(font)}
 #stage{font-family:'${font}','StoryshotCJK',sans-serif;color:${P.text}}
-.bg{background:radial-gradient(${W * 0.73}px ${H * 0.88}px at 50% 40%, ${P.glow} 0%, ${P.ground} 52%, ${P.ground2} 100%)}
+/* the grain is what keeps a wide, low-saturation gradient (warm paper above all) from banding into
+   visible rings once the frames are written as JPEG */
+.bg{background:${paper ? `${GRAIN}, ` : ''}radial-gradient(${W * 0.73}px ${H * 0.88}px at 50% 40%, ${P.glow} 0%, ${P.ground} 52%, ${P.ground2} 100%)}
 .backdrop{object-fit:cover;opacity:${dark ? 0.16 : 0.1};-webkit-mask-image:radial-gradient(ellipse 60% 60% at 50% 50%,#000 35%,transparent 100%)}
 .band-wrap{position:absolute;left:0;right:0;height:${80 * u}px;overflow:hidden;opacity:${P.band};-webkit-mask-image:linear-gradient(90deg,transparent,#000 18%,#000 82%,transparent)}
 .band{position:absolute;left:0;top:0;white-space:nowrap;font:500 ${54 * u}px 'IBM Plex Mono',monospace;letter-spacing:.3em}
@@ -591,7 +604,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 +638,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 ? 'aspect: portrait                                 # 9:16, 1080x1920: a phone held upright, and every short-video feed.\n                                                 # Write every scene as one column: `storyshot guide` ("Portrait").\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,12 +138,18 @@ 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>
 <div id="root" data-composition-id="main" data-start="0" data-duration="${D}" data-width="${W}" data-height="${H}">
-<div id="${info.id}" class="clip" data-composition-id="${info.id}" data-composition-src="compositions/scene.html" data-start="0" data-duration="${D}" data-track-index="1" data-width="${W}" data-height="${H}"></div>
+<!-- The host the scene mounts into carries no \`id\`, only \`data-composition-id\`, which is what
+     HyperFrames matches on. It used to carry the scene's id as well, and since the scene's own root
+     element must have that same id, every scene then had TWO elements with it in one document:
+     document.getElementById('<id>') returned this empty host, and a scene that appended to it put
+     everything outside its own styled root and rendered a blank frame. -->
+<div class="clip" data-composition-id="${info.id}" data-composition-src="compositions/scene.html" data-start="0" data-duration="${D}" data-track-index="1" data-width="${W}" data-height="${H}"></div>
 ${job.preview && ctx.subs ? `<div id="storyshot-subtitle-band" data-layout-ignore style="position:absolute;left:0;right:0;bottom:0;height:${Math.round(H > W ? H * 0.22 : H * 0.16)}px;z-index:9999;background:repeating-linear-gradient(135deg,rgba(255,64,64,.18) 0 14px,rgba(255,64,64,.08) 14px 28px);border-top:3px dashed rgba(255,64,64,.9);pointer-events:none"><span style="position:absolute;right:24px;top:10px;font:600 26px/1 sans-serif;color:#ff4040">burned-in subtitles</span></div>` : ''}
 </div>
 <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
@@ -140,15 +160,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 });
@@ -175,11 +200,29 @@ export function formatTimings(list) {
   ].join('\n')).join('\n\n');
 }
 
+// The red, green and blue of a hex or rgb() colour, 0–255. null for anything else (a variable, an
+// image, a colour function).
+export function toRgb(colour) {
+  const hex = String(colour).match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i)?.[1], rgb = String(colour).match(/rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/i);
+  return hex ? (hex.length === 3 ? [...hex].map((h) => parseInt(h + h, 16)) : [0, 2, 4].map((k) => parseInt(hex.slice(k, k + 2), 16))) : rgb ? rgb.slice(1, 4).map(Number) : null;
+}
+const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0');
+
+// Mix two colours: t = 0 is all `a`, t = 1 is all `b`. Returns a hex colour, or null if either side
+// can't be read. This is how a film's own `theme.paper` becomes a whole set of card tones instead of
+// storyshot's default near-white ones, which are cold against warm paper.
+export function mixColour(a, b, t) {
+  const [x, y] = [toRgb(a), toRgb(b)];
+  if (!x || !y) return null;
+  return `#${x.map((v, i) => hex2(v + (y[i] - v) * t)).join('')}`;
+}
+// Lighten (amount > 0) or darken (amount < 0) a colour, 0–1.
+export const shadeColour = (c, amount) => mixColour(c, amount >= 0 ? '#ffffff' : '#000000', Math.abs(amount));
+
 // How light a hex or rgb() colour is, 0 (black) to 1 (white). null for anything else (a variable, an
 // image, a colour function).
 export function luminance(colour) {
-  const hex = String(colour).match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i)?.[1], rgb = String(colour).match(/rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/i);
-  const c = hex ? (hex.length === 3 ? [...hex].map((h) => parseInt(h + h, 16)) : [0, 2, 4].map((k) => parseInt(hex.slice(k, k + 2), 16))) : rgb ? rgb.slice(1, 4).map(Number) : null;
+  const c = toRgb(colour);
   if (!c) return null;
   const lin = c.map((v) => (v / 255 <= 0.03928 ? v / 255 / 12.92 : ((v / 255 + 0.055) / 1.055) ** 2.4));
   return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];