storyshot 0.9.0 → 0.11.0

package/README.md

@@ -1,19 +1,94 @@
 # Storyshot
 
-Ask your coding agent for a video of your web app, and get a polished 1080p
-MP4: a promo clip, a narrated tutorial, a lesson, or step-by-step GIFs for your
-docs.
+Ask your coding agent for a video, and get a polished 1080p MP4. Two kinds of
+film come out of one tool:
 
+- **An explainer of an idea** — no web app, no footage, nothing recorded. Every
+  scene is an animation the agent writes and times to the narration: a
+  mechanism, a diagram that builds, a number that lands. Chinese or English.
+  *This is what most people come for.*
+- **A video of your web app** — a promo, a narrated tutorial, a lesson, or
+  step-by-step GIFs for your docs. A real browser clicks through your site, and
+  the recording gets a smooth cursor, automatic zoom, captions, an optional
+  voiceover, music and an end card.
+
+The agent plans, writes and fixes the storyboard. Storyshot does the rendering,
+and the same storyboard always renders the same video.
+
+## Install it into your coding agent
+
+**The skill is the front door.** You do not learn a CLI — your agent does.
+
+Open your project in your coding agent (Claude Code, Cursor, Codex, Gemini CLI,
+Copilot in VS Code, Windsurf, Cline) and paste this one line into its chat, with
+your agent's name in place of `claude`:
+
+> Set up Storyshot in this project: run `npx -y storyshot setup claude` and do everything it says.
+
+Agent names: `claude` · `cursor` · `codex` · `gemini` · `vscode` · `windsurf` · `cline`.
+
+That one command installs **the Storyshot skill** into your agent, writes the MCP
+server config, adds `.storyshot/` to `.gitignore`, and downloads the browser it
+needs. The skill is what teaches your agent the whole workflow — how to plan a
+film, write the scenes, read the render back and fix it — so from the next chat
+on you can just ask for a video in plain words.
+
+Restart or reload your agent when `setup` says to. Then:
+
+> *「做一个视频，讲清楚热泵为什么能把一份电变成三份热」*
+>
+> *"make an explainer about how a heat pump moves three units of heat per unit of electricity"*
+>
 > *"make a 15 s promo video of https://myapp.com"*
+>
+> *"make a narrated tutorial showing how to export a report"*
 
-Storyshot gives coding agents (Cursor, Claude Code, Codex, Gemini CLI, Copilot in VS Code, Windsurf, Cline) what they need to
-do this well. A real browser clicks through your site, and the recording gets
-a smooth cursor, automatic zoom, captions, an optional AI voiceover, music
-and an end card. Loading time is squeezed out, so a 30-second AI job takes a
-second or two on screen.
+or type `/storyshot`.
 
-The agent plans, writes and fixes the storyboard. Storyshot does the
-recording and editing, and the same storyboard always renders the same video.
+`npx storyshot doctor` re-checks everything at any time. Storyshot runs on
+macOS, Linux and Windows. Needs Node 18+ and ffmpeg (setup prints the exact
+install command for your OS if it is missing).
+
+### Explainers, in one paragraph
+
+An explainer has no `url` and records nothing. You ask for a subject; the agent
+writes a storyboard of **scenes**, and each scene is an HTML animation it draws
+and times to the voice, phrase by phrase. It renders a still of every scene,
+looks at it, and fixes what is wrong before it ever renders video. Free local
+voices in English and Chinese, synth music, subtitles and chapters — no API key
+and no per-video cost. Start here:
+[the explainers in the gallery](https://boheling.github.io/storyshot-gallery/#explainer),
+and the ["Scenes and explainers" playbook](#for-agents-tools-and-playbook).
+
+## What `setup` writes, per agent
+
+| agent | what `setup` writes |
+|---|---|
+| Cursor | `.cursor/mcp.json` and the skill in `.cursor/skills/storyshot/` |
+| Claude Code | `.mcp.json` and the skill in `.claude/skills/storyshot/` |
+| Codex | the skill in `.agents/skills/storyshot/`, a short section in `AGENTS.md` pointing to it, and the MCP server through `codex mcp add` (in `~/.codex/config.toml`, for your user). Storyshot launches a browser, which Codex's sandbox blocks: approve it when Codex asks, or run Codex with `--sandbox danger-full-access` |
+| Gemini CLI | `.gemini/settings.json`, a section in `GEMINI.md`, the skill in `.agents/skills/storyshot/` (trust the folder when Gemini asks, or it ignores project settings) |
+| Copilot in VS Code (`vscode`) | `.vscode/mcp.json`, a section in `.github/copilot-instructions.md`, the skill in `.agents/skills/storyshot/` |
+| Windsurf | `.windsurf/rules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in `~/.codeium/windsurf/mcp_config.json` (for your user) |
+| Cline | `.clinerules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in Cline's own settings in each editor it is installed in (for your user) |
+
+Existing files are merged, not replaced: other MCP servers stay, and instruction files get one marked
+Storyshot section that a second `setup` updates instead of duplicating.
+
+**Tested end to end** (setup, then an agent making a real video from a plain request): **Claude Code,
+Cursor and Codex**. Gemini CLI, Copilot in VS Code, Windsurf and Cline get the configuration their docs
+describe, but haven't been tested with a real session yet; reports are welcome.
+
+The agent does the rest:
+- `setup` writes the MCP server config and the Storyshot skill, adds
+  `.storyshot/` to `.gitignore`, and downloads the browser it needs.
+- If ffmpeg is missing, setup prints the exact install command for your OS
+  (`brew install ffmpeg`, `winget install --id Gyan.FFmpeg -e`,
+  `sudo apt-get install -y ffmpeg`). The agent runs it after you approve.
+- The agent reads the skill and starts on your video in the same chat, using
+  the CLI.
+
+From the next chat on, the agent uses the Storyshot MCP tools automatically.
 
 https://github.com/user-attachments/assets/05dd9a73-2edc-46af-9b2b-a8e33c7005b4
 
@@ -57,51 +132,6 @@ https://github.com/user-attachments/assets/8d3370ca-7a90-48af-b1c9-88189763e95d
 How each one was made, what we saw, and the caveats:
 [docs/comparison](docs/comparison/README.md).
 
-## Quick start
-
-Open your project in your coding agent and paste this into its chat, with your
-agent's name (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf` or `cline`):
-
-> Set up Storyshot in this project: run `npx -y storyshot setup cursor` and do
-> everything it says. Then make a short promo video of https://myapp.com
-
-| agent | what `setup` writes |
-|---|---|
-| Cursor | `.cursor/mcp.json` and the skill in `.cursor/skills/storyshot/` |
-| Claude Code | `.mcp.json` and the skill in `.claude/skills/storyshot/` |
-| Codex | the skill in `.agents/skills/storyshot/`, a short section in `AGENTS.md` pointing to it, and the MCP server through `codex mcp add` (in `~/.codex/config.toml`, for your user). Storyshot launches a browser, which Codex's sandbox blocks: approve it when Codex asks, or run Codex with `--sandbox danger-full-access` |
-| Gemini CLI | `.gemini/settings.json`, a section in `GEMINI.md`, the skill in `.agents/skills/storyshot/` (trust the folder when Gemini asks, or it ignores project settings) |
-| Copilot in VS Code (`vscode`) | `.vscode/mcp.json`, a section in `.github/copilot-instructions.md`, the skill in `.agents/skills/storyshot/` |
-| Windsurf | `.windsurf/rules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in `~/.codeium/windsurf/mcp_config.json` (for your user) |
-| Cline | `.clinerules/storyshot.md`, the skill in `.agents/skills/storyshot/`, and the MCP server in Cline's own settings in each editor it is installed in (for your user) |
-
-Existing files are merged, not replaced: other MCP servers stay, and instruction files get one marked
-Storyshot section that a second `setup` updates instead of duplicating.
-
-**Tested end to end** (setup, then an agent making a real video from a plain request): **Claude Code,
-Cursor and Codex**. Gemini CLI, Copilot in VS Code, Windsurf and Cline get the configuration their docs
-describe, but haven't been tested with a real session yet; reports are welcome.
-
-The agent does the rest:
-- `setup` writes the MCP server config and the Storyshot skill, adds
-  `.storyshot/` to `.gitignore`, and downloads the browser it needs.
-- If ffmpeg is missing, setup prints the exact install command for your OS
-  (`brew install ffmpeg`, `winget install --id Gyan.FFmpeg -e`,
-  `sudo apt-get install -y ffmpeg`). The agent runs it after you approve.
-- The agent reads the skill and starts on your video in the same chat, using
-  the CLI.
-
-Restart or reload your agent when convenient (`setup` says how for each one). From the next chat on,
-the agent uses the Storyshot MCP tools automatically, and you can just ask:
-
-- *"make a 15 s promo video of https://myapp.com"*, or type `/storyshot`
-- *"make a narrated tutorial showing how to export a report"*
-- *"make a lesson video explaining how the AI editor works"*
-- *"make docs GIFs for the onboarding flow"*
-
-`npx storyshot doctor` re-checks everything at any time. Storyshot runs on
-macOS, Linux and Windows.
-
 ## What happens when you ask
 
 1. **The agent looks at your site** (about 5 s). It reads the page, and checks
@@ -142,8 +172,8 @@ After your next release, re-render it and you have an up-to-date video.
 | ask for | type (`purpose`) | you get |
 |---|---|---|
 | a promo / launch / landing-page clip | `pitch` | short and tightly cut: intro card, the app in a browser frame, music, captions |
-| a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters |
-| a lesson | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters. `check` holds the narration to a teaching pace too — one job per step, a budget per line, no bolded payoffs — so a slow film doesn't still read as a pitch |
+| a lesson | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters. `check` holds it to the tutorial's teaching pace, and to a lesson's own shape: a card names one idea, a question waits for an answer and its step marks it |
 | help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
 | an animated explainer of how something works | `explainer` | no web app: every step is a **scene**, an animation the agent writes and times to the narration (a mechanism, a diagram that grows, a number); calm music, subtitles, chapters |
 
@@ -259,9 +289,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
@@ -529,8 +561,24 @@ 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,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.9.0",
+  "version": "0.11.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": {

package/skills/storyshot/SKILL.md

@@ -175,7 +175,9 @@ or scientific tool they have never seen. Storyshot paces `tutorial` and
 `course` slowly by default (`pace: slow`: slower cursor and typing, a beat
 after every click, a hold after every narration line, slower voice, real
 progress shown for waits) and the camera follows the action (`follow`), so
-small controls are readable. Your job is the structure:
+small controls are readable. What the tool cannot set for you is the structure
+and the voice. The structure first; "The teaching voice" below is the half that
+decides whether a slow film still sounds like a sales pitch:
 
 - **Start with the goal**: an `intro` with `bullets` saying what the viewer
   will be able to do ("Run a BLAST search", "Read the hits table", "Judge a
@@ -245,6 +247,86 @@ small controls are readable. Your job is the structure:
   don't pad: if a part is long, split it into more parts rather than
   speeding it up.
 
+#### The teaching voice
+
+`pace: slow` buys time on screen: slower cursor and typing, a beat after every
+click, a hold after every line. It cannot buy time *inside* a sentence. A
+tutorial that still sounds like an ad read slowly is nearly always a writing
+problem, not a timing one — and the usual cause is density, not length.
+`check` holds a `tutorial` or a `course` to the rules below. A promo is held to
+none of them, which is the point: they are different jobs.
+
+1. **One job per step.** A step either names an idea, does an action, or reads
+   a result. Not two of those, and never three. The line that packs all three
+   is the commonest failure, and it reads fine on the page:
+
+   > "The E value is how many hits this good you would expect by pure chance in
+   > a database this size. Smaller is better, and anything below 1e-5 usually
+   > means a real relationship. Here it is 6e-106, essentially zero."
+
+   A definition, a rule of thumb and a reading, in eleven seconds. The viewer
+   is still working out what "expect by chance" means when the number arrives,
+   so they keep none of it. As three steps they keep all three.
+2. **A step's whole `say:` fits in about 35 words (55 Chinese characters).**
+   Past that, split the step.
+3. **A sentence is about 15 words (25 characters).** `check` speaks up past 18
+   (30), so 15 is what to write to, not a line to trip over. Promos are allowed
+   25; a lesson is not.
+4. **At most three figures in one line.** Nobody holds four numbers by ear. Say
+   the one that carries the point, round it out loud ("about eighty percent"),
+   and let the screen carry the exact value — which it can, because you marked
+   the cell.
+5. **Say the number, then what it means, then the rule again.** Teaching
+   repeats. A script that states each fact exactly once reads as a list of
+   facts, however plainly each one is put. The recap at the end repeats them in
+   the same words as the first time.
+6. **Silence is part of the lesson.** After a result appears, the viewer needs a
+   beat to find it on their own screen. Hold the step (`pause: 2000`) and say
+   nothing. Compose's dead-air warning knows the difference: 3 s is too long in
+   a promo, a `tutorial` or `course` is allowed 6 s, and 8 s on a step that
+   asked to hold. Resolve a dead-air warning in a lesson by saying what to look
+   at, not by cutting the beat.
+7. **A new term gets a step of its own**, the first time it appears, before any
+   number is attached to it.
+
+**A tutorial's caption is a label, not a payoff.** A promo bolds the payoff
+because a promo is selling the payoff. Here the caption says where the viewer
+is — "The E value column", "Part 2: read the results" — and the voice does the
+explaining. `Shorter protein, **larger** E value` reaches the conclusion before
+the narration gets there, which is an ad's grammar; `check` warns on `**` in a
+tutorial caption. A `note` works the same way: it labels the control it points
+at in a few words ("FASTA or accession"), it does not recommend it ("Curated,
+fast: good for learning").
+
+#### What a lesson adds
+
+A tutorial teaches the steps; a lesson (`course`) teaches the idea behind them,
+so the clicking is usually done in `hidden` steps and the film is about reading
+what is on the page. It is held to the whole teaching voice above, and to three
+things of its own. `check` warns on each.
+
+1. **A card names one idea.** A concept card's `say:` gets the same budget as a
+   step (about 35 words, 55 Chinese characters), and it is the easiest place to
+   break it, because a card feels like the place for the whole explanation:
+   definition, threshold and example. Put the name and the plain-words meaning
+   on the card. The rule and the number go in the steps after it, where the
+   page can show them and you can `mark` them.
+2. **A question card waits, and its step shows the answer.** A check has three
+   parts: the question, time to answer it (`think: 3`, at least 2), and the
+   answer marked on the page. Without the wait it is a rhetorical question,
+   which a promo asks and a lesson does not. Without the mark, a viewer who
+   guessed wrong is told so and never shown where to look. The step a question
+   card sits on is the reveal: it points at the answer first, and the reason
+   comes in the step after.
+3. **Ask at least once.** A lesson with no question is a lecture: the viewer
+   cannot tell whether they followed it. The best second question is a new case
+   the rule has to be applied to (a different search, another input), not the
+   first one asked again.
+
+The order inside each idea is the one in "Explain in an order the viewer can
+follow" below: a concrete case on screen, then the card that names it, then the
+reading, then the rule, then the question.
+
 ### Writing the narration
 
 Viewers notice three things first: lines that run together, phrasing nobody
@@ -254,7 +336,9 @@ They should sound like one person talking a friend through it.
 
 **Say it like a person.**
 - Short sentences, one idea each: about 15 words at most in English, 25
-  characters in Chinese. If you would run out of breath, split it.
+  characters in Chinese. If you would run out of breath, split it. In a
+  tutorial or lesson `check` enforces this, along with a budget for the whole
+  step — see "The teaching voice".
 - Spoken words: contractions ("you'll", "it's"), "you", present tense, active
   voice. In Chinese, 口语 rather than 书面语: "点一下这里", not "进行点击操作".
 - Use the exact labels on screen, and the same term every time (no synonyms
@@ -314,8 +398,10 @@ Rules of thumb from real renders (promos and tutorials):
     icon and name, not an address bar.
   - Other purposes: leave out `duration`. `auto` times each step to its
     narration and plays motion in real time.
-- **Captions ≤ 7 words.** `**bold**` the payoff ("Every text box is
-  **fully editable**"). Steps with the same caption keep it on screen.
+- **Captions ≤ 7 words.** In a promo, `**bold**` the payoff ("Every text box is
+  **fully editable**"); in a tutorial or lesson a caption is a label for where
+  the viewer is, with no bold payoff (see "The teaching voice"). Steps with the
+  same caption keep it on screen.
 - **Narration (`say:`) is not a caption.** Write full spoken sentences, one
   instruction or idea per step. Use normal spelling, and put pronunciations in
   `voice.pronounce` (e.g. `pxGenius: P X Genius`, `AI: A I`) so subtitles stay
@@ -380,7 +466,9 @@ Notes:
   automatically (never under 2.5 s); leave out `duration` there.
 - Compose warns about **dead air**: 3 s or more where nothing moves and
   nothing is said. Shorten the wait or pause, hide the load in a `hidden`
-  step, or narrate it. Keep `intro` cards to 6–8 s.
+  step, or narrate it. A `tutorial` or `course` is allowed 6 s, and 8 s on a
+  step that asked to hold with `pause`, because a learner needs the beat.
+  Keep `intro` cards to 6–8 s.
 - With `subtitles: burn`, the top caption pills can repeat the subtitles;
   `captions: false` keeps them off the video (chapters and SRT still use them).
 - `.storyshot/` next to the YAML is a cache of recordings, screenshots and
@@ -681,6 +769,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:`.
@@ -688,6 +787,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
@@ -715,6 +818,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/check.mjs

@@ -9,6 +9,9 @@ import { sentences } from './voice.mjs';
 import { sceneInfo, filmGround, contrast } from './scenes.mjs';
 import path from 'node:path';
 
+const cjkLen = (s) => (s.match(/[぀-ヿ㐀-鿿가-힯]/g) ?? []).length;
+const wordLen = (s) => s.replace(/[぀-ヿ㐀-鿿가-힯]/g, ' ').split(/\s+/).filter((w) => /\w/.test(w)).length;
+
 // Phrases that mark narration as machine-written, and sentences too long to say in one breath.
 const TELLS = [
   /\bnot (?:just|only|merely) [^.,;!?]{1,40}?,? but(?: also)?\b/i, // "not just X, but Y"
@@ -28,15 +31,41 @@ export function narrationLint(text) {
   }
   let long = null;
   for (const s of sentences(t)) {
-    const cjk = (s.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length;
-    const words = s.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter((w) => /\w/.test(w)).length;
+    const cjk = cjkLen(s), words = wordLen(s);
     if (cjk > 40 && !long) long = `${cjk}-character`;
     else if (!cjk && words > 25 && !long) long = `${words}-word`;
   }
   return { tells, long };
 }
 
-const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'ground', 'lang', 'colorScheme',
+// How much one step may carry when the viewer is meant to follow along and do it themselves.
+// A promo packs; a tutorial parcels out. The skill has always asked for 15 words a sentence, but the
+// lint above only caught 25, which is a promo's budget — tutorials and lessons are held to the number
+// the skill actually says, and a step gets a budget of its own. Density is the thing nobody notices
+// while writing: three jobs in one breath (name the idea, give the rule, read the number) is what
+// makes a tutorial sound like an ad read at speed, even when every sentence is short.
+// sentenceWords/Chars is the number the skill asks for; the lint only speaks up past the slack, so
+// "about 15 words" stays a target to write to rather than a line to trip over at 16.
+export const TEACH = { words: 35, chars: 55, sentenceWords: 15, sentenceChars: 25, slackWords: 18, slackChars: 30, numbers: 3 };
+const an = (s) => `${/^(?:8|11|18|8\d|11\d|18\d)/.test(s) ? 'an' : 'a'} ${s}`;
+export function teachingLint(text) {
+  const t = String(text).replace(/\*\*/g, '');
+  const c = cjkLen(t), w = wordLen(t);
+  const heavy = c > TEACH.chars ? `${c}-character` : (!c && w > TEACH.words ? `${w}-word` : null);
+  let long = null;
+  for (const s of sentences(t)) {
+    const sc = cjkLen(s), sw = wordLen(s);
+    if (sc > TEACH.slackChars && !long) long = `${sc}-character`;
+    else if (!sc && sw > TEACH.slackWords && !long) long = `${sw}-word`;
+  }
+  // figures the viewer has to hold: a digit that starts a number, so an accession (P68871) or a
+  // version inside a word is not one, and the comma in "1,000" is part of it while the one after
+  // "105," is not. Chinese numerals are spelled out, where the character budget above is what limits them.
+  const numbers = [...new Set(t.match(/(?<![A-Za-z\d])\d(?:,?\d)*(?:\.\d+)?(?:e[-+]?\d+)?%?/gi) ?? [])];
+  return { heavy, long, numbers };
+}
+
+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'];
@@ -91,6 +120,8 @@ export function check(file, { draft = false } = {}) {
     return { ok: false, errors: [`YAML syntax: ${e.message.split('\n')[0]}`], warnings, summary: '' };
   }
   unknown(raw, TOP, 'top level');
+  const sold = []; // tutorial captions written as a promo's payoff, reported together
+  let questions = 0; // question cards (a card that waits with `think`), which a lesson is expected to have
   for (const [i, a] of (raw.setup ?? []).entries()) checkAction(a, `setup action ${i + 1}`);
   for (const [i, s] of (raw.steps ?? []).entries()) {
     const where = `step ${i + 1}`;
@@ -121,8 +152,42 @@ export function check(file, { draft = false } = {}) {
       if (s.say && kinds.some((k) => k === 'scroll' || k === 'scrollTo') && !kinds.some((k) => ['mark', 'note', 'click', 'type', 'select', 'move', 'hover'].includes(k)) && !s.zoom) {
         warnings.push(`${where}: scrolls and talks but points at nothing — on a dense page the viewer can't tell what you mean; \`mark\` or \`note\` the row or value the narration is about (the camera then zooms to it)`);
       }
+      // A promo's caption bolds the payoff, because a promo is selling the payoff. A tutorial's caption
+      // says where the viewer is, and the narration does the explaining: bold it and the caption gets
+      // to the conclusion before the voice does, which is the grammar of an ad, not of a lesson. It is
+      // one decision rather than one mistake per step, so it is reported once.
+      if (typeof s.caption === 'string' && s.caption.includes('**')) sold.push([i + 1, s.caption]);
+      // A callout points at a control and names it. Longer than that and it is arguing for the app.
+      for (const a of (s.actions ?? [])) {
+        const n = a?.note;
+        const t = typeof n === 'string' ? n : n?.text;
+        if (t && (wordLen(t) > 8 || cjkLen(t) > 14)) warnings.push(`${where}: the note reads as a sentence ("${t}") — a callout is a label for the control it points at, a few words at most`);
+      }
+      // A question card is a check, and a check has three parts: the question, time to answer it, and
+      // the answer shown on the page. Without the wait it is a rhetorical question, which a promo asks
+      // and a lesson does not; without something marked, the viewer who guessed wrong is told they
+      // were wrong and never shown where to look.
+      const card = s.card && typeof s.card === 'object' ? s.card : null;
+      const asks = card && /question|quiz|check|问题|提问|思考|想一想|pregunta|frage/i.test(String(card.kicker ?? ''));
+      if (card && (card.think != null || asks)) {
+        questions++;
+        if (card.think == null) warnings.push(`${where} card: asks a question but does not wait for an answer — give it \`think: 3\` (seconds), so the viewer answers before the reveal`);
+        else if (!(card.think >= 2)) warnings.push(`${where} card: think: ${card.think} is too short to answer in — give the viewer at least 2 seconds, 3 to 4 for anything they have to work out`);
+        if (!s.zoom && !kinds.some((k) => ['mark', 'note', 'move', 'hover', 'click', 'slide', 'drag', 'type', 'select'].includes(k))) {
+          warnings.push(`${where}: this step answers the question card before it, but points at nothing — \`mark\` the row, value or line that is the answer, so a viewer who guessed wrong sees why`);
+        }
+      }
     }
   }
+  // A lesson that never asks is a lecture: the viewer cannot tell whether they followed it.
+  if (raw.purpose === 'course' && !questions && (raw.steps ?? []).some((s) => !s.hidden && s.say)) {
+    warnings.push('a lesson with no question card — check understanding at least once: `card: { kicker: Question, title: "…?", think: 3 }` on the step that then marks the answer');
+  }
+  if (sold.length) {
+    const ns = sold.map(([n]) => n);
+    const which = sold.length === 1 ? `step ${ns[0]}` : sold.length > 6 ? `steps ${ns[0]}–${ns.at(-1)} (${sold.length} captions)` : `steps ${ns.join(', ')}`;
+    warnings.push(`${which}: the caption bolds a payoff (${sold.slice(0, 3).map(([, c]) => `"${c}"`).join(', ')}${sold.length > 3 ? ', …' : ''}) — that is a promo's grammar, and it reaches the conclusion before the voice does; in a ${raw.purpose} a caption labels where the viewer is ("The E value column", "Part 2: read the results") and the narration explains`);
+  }
   if (raw.end_card) unknown(raw.end_card, END, 'end_card');
   if (raw.intro) unknown(raw.intro, END, 'intro');
   if (raw.hyperframes && typeof raw.hyperframes === 'object') unknown(raw.hyperframes, HYPERFRAMES, 'hyperframes');
@@ -226,12 +291,29 @@ export function check(file, { draft = false } = {}) {
     }
     // spoken lines that read as machine-written, or run on without a breath (the skill's "Writing the narration")
     if (cfg.voice) {
-      const lines = [...visible.flatMap((s) => [[s.say, `step ${cfg.steps.indexOf(s) + 1}`], [s.card?.say, `step ${cfg.steps.indexOf(s) + 1} card`]]),
-        [cfg.intro?.say, 'intro'], [cfg.endCard?.say, 'end card']].filter(([t]) => t);
-      for (const [text, where] of lines) {
+      const teach = cfg.purpose === 'tutorial' || cfg.purpose === 'course';
+      const lines = [...visible.flatMap((s) => [[s.say, `step ${cfg.steps.indexOf(s) + 1}`, true], [s.card?.say, `step ${cfg.steps.indexOf(s) + 1} card`, 'card']]),
+        [cfg.intro?.say, 'intro', false], [cfg.endCard?.say, 'end card', false]].filter(([t]) => t);
+      for (const [text, where, isStep] of lines) {
         const { tells, long } = narrationLint(text);
         if (tells.length) warnings.push(`${where}: the narration sounds machine-written (${tells.map((x) => `"${x}"`).join(', ')}) — say it plainly, as you would out loud`);
-        if (long) warnings.push(`${where}: a ${long} sentence — split it, so the voice gets a breath between the parts`);
+        // a tutorial's own sentence budget is tighter, and it replaces this one
+        if (long && !teach) warnings.push(`${where}: a ${long} sentence — split it, so the voice gets a breath between the parts`);
+        if (!teach) continue;
+        const t = teachingLint(text);
+        if (isStep === 'card' && t.heavy) {
+          // a concept card names one idea. The rule that goes with it, and the number that shows it,
+          // belong to the steps after the card, where the page can carry them
+          warnings.push(`${where}: ${an(t.heavy)} line on one card — a card names one idea; say the rule and read the number in the steps after it, where the page shows them`);
+        } else if (isStep && t.heavy) {
+          warnings.push(`${where}: ${an(t.heavy)} line for one step — one job per step in a ${cfg.purpose} (name the idea, do the action, or read the result); split it`);
+        }
+        if (t.long) {
+          warnings.push(`${where}: ${an(t.long)} sentence — a ${cfg.purpose} keeps them to about ${TEACH.sentenceWords} words (${TEACH.sentenceChars} Chinese characters), so the viewer holds one idea at a time`);
+        }
+        if (t.numbers.length > TEACH.numbers) {
+          warnings.push(`${where}: ${t.numbers.length} figures in one line (${t.numbers.join(', ')}) — nobody holds that many by ear; say the one that carries the point, round it out loud ("about 80 percent"), and leave the exact values on screen`);
+        }
       }
     }
     // the Chinese Kokoro voice needs a Python for its G2P: say so now, not after the recording

package/src/compose.mjs

@@ -5,11 +5,31 @@ 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>`);
 
+// The camera path as one ffmpeg expression: a value per keyframe interval, smoothstepped between the
+// two ends. Written as a FLAT SUM of gated terms, not a nested if/else chain — ffmpeg's expression
+// parser guards recursion at 100 levels, and each zoom contributes four keyframes, so a tutorial
+// written to "one job per step" (30-odd zooms, 130-odd intervals) silently exceeded it and the whole
+// compose failed with "Missing ')' or too many args". A `+` chain is parsed iteratively, so the depth
+// is constant however long the film is. The gates partition the timeline, so exactly one term is ever
+// non-zero: the first interval also covers everything before it, and the last keyframe holds to the end.
+export function keyframeExpr(kf, get, fps) {
+  const n = kf.length, terms = [];
+  for (let i = 0; i < n - 1; i++) {
+    const t0 = kf[i][0], t1 = kf[i + 1][0], v0 = get(kf[i]), v1 = get(kf[i + 1]);
+    const p = `clip((T-${t0.toFixed(3)})/${Math.max(1e-3, t1 - t0).toFixed(3)},0,1)`;
+    const body = v0 === v1 ? `${v0}` : `(${v0}+(${(v1 - v0).toFixed(4)})*${p}*${p}*(3-2*${p}))`;
+    const gate = i === 0 ? `lt(T,${t1.toFixed(3)})` : `(gte(T,${t0.toFixed(3)})*lt(T,${t1.toFixed(3)}))`;
+    terms.push(`${gate}*${body}`);
+  }
+  terms.push(`gte(T,${kf[n - 1][0].toFixed(3)})*${get(kf[n - 1])}`);
+  return `(${terms.join('+')})`.replaceAll('T', `(on/${fps})`);
+}
+
 export async function compose(cfg, { log = console.log, voiceLens = { steps: {}, endCard: null } } = {}) {
   const warnings = [];
   const warn = (m) => { warnings.push(m); log(`warning: ${m}`); };
@@ -192,11 +212,23 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       ...cards.map((c) => [c.t0, c.t1]),
       ...segs.filter((g) => voiceLens.steps[g.i] != null).map((g) => [g.o0 + g.sayAt, g.o0 + g.sayAt + voiceLens.steps[g.i]]),
     ];
+    // A promo must never stall. A tutorial is the opposite: the viewer is doing this too, and needs a
+    // beat to read the result, find the control on their own screen, and catch up. So a lesson gets a
+    // longer allowance, and a step that asked to hold (`pause`) means it — only a hold long enough to
+    // feel broken is worth a word there.
+    const teach = cfg.purpose === 'tutorial' || cfg.purpose === 'course';
+    const held = (i) => (cfg.steps[i]?.actions ?? []).some((a) => a && (a.pause != null || a.wait != null));
     let from = null;
     const report = (to) => {
-      if (from != null && to - from >= 3) {
+      if (from != null) {
         const ns = segs.filter((x) => x.o1 > from + 1e-6 && x.o0 < to - 1e-6).map((x) => x.i + 1);
-        warn(`${ns.length > 1 ? `steps ${ns[0]}–${ns.at(-1)}` : `step ${ns[0] ?? (segs.at(-1)?.i ?? cfg.steps.length - 1) + 1}`}: ${(to - from).toFixed(1)}s of dead air at ${from.toFixed(1)}–${to.toFixed(1)}s (nothing moves and nothing is said) — shorten the wait or pause, hide the load, or narrate what is happening`);
+        const limit = !teach ? 3 : ns.length && ns.every((k) => held(k - 1)) ? 8 : 6;
+        const fix = teach
+          ? 'say what is happening or what to look at, or let the step hold on purpose with `pause`'
+          : 'shorten the wait or pause, hide the load, or narrate what is happening';
+        if (to - from >= limit) {
+          warn(`${ns.length > 1 ? `steps ${ns[0]}–${ns.at(-1)}` : `step ${ns[0] ?? (segs.at(-1)?.i ?? cfg.steps.length - 1) + 1}`}: ${(to - from).toFixed(1)}s of dead air at ${from.toFixed(1)}–${to.toFixed(1)}s (nothing moves and nothing is said) — ${fix}`);
+        }
       }
       from = null;
     };
@@ -270,16 +302,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   }
   if (kf.at(-1)[0] < TOTAL) kf.push([TOTAL, 1, C0]);
   const S = 2; // supersample to avoid zoompan's integer-pixel jitter
-  const piece = (get) => {
-    let e = String(get(kf.at(-1)));
-    for (let i = kf.length - 2; i >= 0; i--) {
-      const t0 = kf[i][0], t1 = kf[i + 1][0], v0 = get(kf[i]), v1 = get(kf[i + 1]);
-      const p = `clip((T-${t0.toFixed(3)})/${Math.max(1e-3, t1 - t0).toFixed(3)},0,1)`;
-      const body = v0 === v1 ? `${v0}` : `(${v0}+(${(v1 - v0).toFixed(4)})*${p}*${p}*(3-2*${p}))`;
-      e = `if(lt(T,${t1.toFixed(3)}),${body},${e})`;
-    }
-    return e.replaceAll('T', `(on/${FPS})`);
-  };
+  const piece = (get) => keyframeExpr(kf, get, FPS);
   const zExpr = piece((k) => k[1]);
   const cxExpr = piece((k) => +(k[2][0] * S).toFixed(1));
   const cyExpr = piece((k) => +(k[2][1] * S).toFixed(1));
@@ -388,11 +411,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 +587,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 }) : {};

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,6 +238,7 @@ 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 ?? {};
@@ -231,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,7 +16,7 @@ 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));
@@ -152,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);
@@ -301,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;
@@ -346,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}

package/src/init.mjs

@@ -120,7 +120,7 @@ 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: true                                  # an .srt beside the video, which is the right one for an explainer: the
+${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.

package/src/record.mjs

@@ -423,7 +423,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   }
   const { width: VW, height: VH } = cfg.viewport;
 
-  const browser = await chromium.launch();
+  // STORYSHOT_GPU=1 renders WebGL on the GPU (Metal on macOS) instead of SwiftShader;
+  // 3D pages otherwise record at ~10 fps and every step comes out rushed.
+  const gpu = /^(1|true|yes)$/i.test(process.env.STORYSHOT_GPU || '');
+  const browser = await chromium.launch(gpu ? { args: ['--enable-gpu', '--ignore-gpu-blocklist', ...(process.platform === 'darwin' ? ['--use-angle=metal'] : [])] } : {});
   const context = await sessionContext(browser, {
     viewport: cfg.viewport, deviceScaleFactor: cfg.scale, colorScheme: cfg.colorScheme, storageState: cfg.storageState, ignoreHTTPSErrors: cfg.ignoreHTTPSErrors,
     permissions: ['clipboard-read', 'clipboard-write'], // for `paste`

package/src/scenes.mjs

@@ -144,7 +144,12 @@ ${(job.kit?.css ?? []).map((f, k) => `<link rel="stylesheet" href="kit/${k}-${pa
 ${(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>
@@ -195,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];