storyshot 0.9.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
@@ -529,8 +531,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.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": {

package/skills/storyshot/SKILL.md

@@ -681,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:`.
@@ -688,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
@@ -715,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/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'];

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 }) : {};

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/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];