storyshot 0.7.2 → 0.8.0

package/src/check.mjs

@@ -6,6 +6,8 @@ import { gitIgnored } from './auth.mjs';
 import { isZhVoice, zhVoiceStatus } from './kokoro-zh.mjs';
 import { qwenStatus } from './qwen-tts.mjs';
 import { sentences } from './voice.mjs';
+import { sceneInfo, filmGround, contrast } from './scenes.mjs';
+import path from 'node:path';
 
 // Phrases that mark narration as machine-written, and sentences too long to say in one breath.
 const TELLS = [
@@ -34,9 +36,10 @@ 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', 'lang', 'colorScheme',
-  'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card', 'hyperframes'];
-const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc'];
+const TOP = ['name', 'url', 'out', 'purpose', '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'];
 const ZOOM = ['target', 'scale', 'start', 'end', 'ramp', 'offset'];
 const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'bullets', 'image', 'think', 'emblem'];
 const HYPERFRAMES = ['template', 'band', 'bandColors', 'emblem', 'hand', 'backdrop'];
@@ -103,9 +106,14 @@ export function check(file, { draft = false } = {}) {
     if (!Array.isArray(s.actions ?? [])) errors.push(`${where}: actions must be a list`);
     for (const [j, a] of (s.actions ?? []).entries()) checkAction(a, `${where} action ${j + 1}`);
     if (s.card) unknown(s.card, END, `${where} card`);
+    if (s.scene) {
+      if (typeof s.scene === 'object') unknown(s.scene, SCENE, `${where} scene`);
+      for (const k of ['caption', 'zoom', 'sayAt', 'follow', 'highlight']) if (s[k] != null) warnings.push(`${where}: ${k} does nothing on a scene (a scene draws its own picture and text)`);
+      for (const k of ['lead', 'tail']) if (s.scene?.[k] != null && !(typeof s.scene[k] === 'number' && s.scene[k] >= 0)) errors.push(`${where} scene: ${k} is seconds (≥ 0)`);
+    }
     // tutorials: one thing per step, so the viewer can follow (and the narration can explain it)
     const purpose = raw.purpose ?? 'pitch';
-    if ((purpose === 'tutorial' || purpose === 'course') && !s.hidden) {
+    if ((purpose === 'tutorial' || purpose === 'course') && !s.hidden && !s.scene) {
       const doing = (s.actions ?? []).filter((a) => a && ['click', 'dblclick', 'type', 'drag', 'press', 'goto', 'select', 'slide', 'paste'].includes(Object.keys(a)[0]) && !(Object.keys(a)[0] === 'press' && /^(Enter|Tab)$/.test(String(Object.values(a)[0]))));
       if (doing.length > 2) warnings.push(`${where}: does ${doing.length} things (${doing.map((a) => Object.keys(a)[0]).join(', ')}) in one step — in a ${purpose}, split it so each action gets its own explanation and the viewer can keep up`);
       if (doing.length && !s.say) warnings.push(`${where}: does something but has no say: line — in a ${purpose}, tell the viewer what and why`);
@@ -168,6 +176,34 @@ export function check(file, { draft = false } = {}) {
   }
   let summary = '';
   if (cfg) {
+    // scenes: the file is there and keeps the HyperFrames contract (the full lint runs in `storyshot scene`)
+    for (const [i, s] of cfg.steps.entries()) {
+      if (!s.scene || s.hidden) continue;
+      const r = sceneInfo(s.scene.file, cfg.output);
+      errors.push(...r.errors.map((e) => `step ${i + 1}: ${e}`));
+      warnings.push(...r.warnings.map((w) => `step ${i + 1}: ${w}`));
+      if (!cfg.voice && !(typeof s.duration === 'number')) errors.push(`step ${i + 1}: a scene is as long as its narration, and there is no voice: — add a voice: block, or give the scene a duration`);
+    }
+    if (raw.scenes) unknown(raw.scenes, ['css', 'js'], 'scenes');
+    for (const f of [...cfg.sceneKit.css, ...cfg.sceneKit.js]) if (!fs.existsSync(f)) errors.push(`scenes: ${f} does not exist`);
+    for (const f of cfg.sceneKit.css) if (!/\.css$/i.test(f)) errors.push(`scenes.css: ${path.basename(f)} is not a .css file`);
+    for (const f of cfg.sceneKit.js) if (!/\.m?js$/i.test(f)) errors.push(`scenes.js: ${path.basename(f)} is not a .js file`);
+    const ids = cfg.steps.filter((s) => s.scene && !s.hidden).map((s) => sceneInfo(s.scene.file).id).filter(Boolean);
+    for (const id of new Set(ids.filter((x, k) => ids.indexOf(x) !== k))) errors.push(`two scenes share the composition id "${id}" — give each scene its own id (and prefix its element ids with it)`);
+    if (cfg.purpose === 'explainer' && !cfg.steps.some((s) => s.scene)) warnings.push('an explainer is made of scenes: give its steps a scene: file');
+    // burned-in subtitles follow the film's ground: ink letters on a light film, white on a dark one,
+    // with the word being spoken in the accent either way, so the accent has to carry a large text's
+    // 3:1 against that ground
+    if (cfg.subtitles === 'burn') {
+      const ground = filmGround(cfg), against = ground === 'light' ? '#ffffff' : '#000000';
+      const ratio = contrast(cfg.theme.accent, against);
+      if (ground && ratio != null && ratio < 3) {
+        warnings.push(`theme.accent (${cfg.theme.accent}) is only ${ratio}:1 against ${ground === 'light' ? 'white' : 'black'}, and the burned-in subtitles paint the word being spoken in the accent: on this ${ground} film it would barely read — ${ground === 'light' ? 'darken' : 'lighten'} the accent (large text needs 3:1)`);
+      }
+      if (ground == null && cfg.steps.some((s) => s.scene && !s.hidden)) {
+        warnings.push("the scenes' ground could not be read (a variable, an image, or a rule this check cannot follow), so the burned-in subtitles stay white, which needs something dark under it — say which the film is with `ground: light` or `ground: dark`");
+      }
+    }
     const visible = cfg.steps.filter((s) => !s.hidden);
     const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0) + (cfg.intro?.say ? 1 : 0);
     if (cfg.voice && !says) warnings.push('voice is set but no step has a `say:` line');
@@ -230,7 +266,8 @@ export function check(file, { draft = false } = {}) {
     const ec = cfg.endCard ? (cfg.endCard.duration === 'auto' ? null : cfg.endCard.duration) : 0;
     const length = auto ? `${fixed ? `${fixed.toFixed(1)}s fixed + ` : ''}${auto} steps timed to narration${cfg.endCard ? ' + end card' : ''}${cfg.intro ? ' + intro' : ''}`
       : `${fixed.toFixed(1)}s of steps${cfg.endCard ? ` + ${ec ?? 'auto'}s end card` : ''}${ec != null ? ` = ${(fixed + ec).toFixed(1)}s total` : ''}`;
-    summary = `${cfg.name}: purpose ${cfg.purpose}, ${visible.length} visible steps, ${length}` +
+    const nScenes = visible.filter((s) => s.scene).length;
+    summary = `${cfg.name}: purpose ${cfg.purpose}, ${visible.length} visible steps${nScenes ? ` (${nScenes} scene${nScenes > 1 ? 's' : ''})` : ''}, ${length}` +
       (cfg.voice ? `, voice ${cfg.voice.provider}` : '') + ` → ${cfg.out}`;
   }
   return { ok: !errors.length, errors, warnings, summary };

package/src/compose.mjs

@@ -5,6 +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';
 
 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>`);
@@ -89,6 +90,16 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       cards.push({ i, t0: acc, t1: acc + C, card: s.card, thinkAt: C - (s.card.think ?? 0) - 0.3 });
       acc += C;
     }
+    if (s.scene) {
+      // a scene is its own picture (the last frame shown holds under it) for as long as its narration needs
+      const C = sceneSeconds(s, voiceLens.steps[i]);
+      const prev = pieces.at(-1)?.raw[1] ?? r.start;
+      pieces.push({ raw: [prev, prev], o0: acc, o1: acc + C });
+      cards.push({ i, t0: acc, t1: acc + C, card: { title: s.scene.title ?? '' }, scene: s.scene, say: s.say, lead: s.scene.lead, cues: voiceLens.cues?.[i] ?? [] });
+      acc += C;
+      afterHidden = false;
+      continue;
+    }
     const g = { i, step: s, o0: acc, o1: acc + D, sayAt, zoomBox: r.zoomBox, afterHidden, hold,
       motionSpeed: M && motionBudget ? M / motionBudget : 1, waitSpeed: Wt && waitBudget ? Wt / waitBudget : 1 };
     for (const [a, b, w] of parts) {
@@ -185,7 +196,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const report = (to) => {
       if (from != null && to - from >= 3) {
         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 + 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`);
+        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`);
       }
       from = null;
     };
@@ -373,9 +384,10 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // Intro and end cards are short animations (logo pops, title rises, the highlight sweeps, a command
   // CTA types itself out), rendered frame by frame by seeking the page's CSS animations.
   const u = H / 1080;
-  // cards follow the frame: dark backdrops (aurora, dark, blur) get dark cards, so a dark app doesn't
-  // cut to a white card; `cards: light | dark` overrides
-  const darkCards = cfg.cards === 'dark' || (cfg.cards !== 'light' && ['aurora', 'dark', 'blur'].includes(cfg.frame?.style));
+  // cards follow the film's ground (see filmGround): dark backdrops (aurora, dark, blur) and scenes that
+  // 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)' }
@@ -485,7 +497,10 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // what each HyperFrames card is about: its text, when its narration plays (card seconds), and
   // pictures from the recording (the page it leads into, blurred, as a backdrop; for a launch intro, the
   // first page sharp, and where the app shows the intro's logo, so the logo can land there)
+  // scenes: rendered with HyperFrames whatever `hyperframes:` says (they are HyperFrames compositions);
+  // the cards only when it is on
   function hfJobs() {
+    if (!cfg.hyperframes) return cards.flatMap((c, k) => (c.scene ? [sceneJob(c, k)] : []));
     const launch = cfg.hyperframes.template === 'launch';
     const seqAt = (t) => path.join(SEQ, `${String(Math.min(nFrames - 1, Math.max(0, Math.round(t * FPS)))).padStart(5, '0')}.jpg`);
     const blurred = (t, name) => {
@@ -522,6 +537,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
         page: launch && nFrames ? seqAt(INTRO) : null, backdrop: launch ? null : blurred(INTRO + 0.05, 'intro') });
     }
     for (const [k, c] of cards.entries()) {
+      if (c.scene) { jobs.push(sceneJob(c, k)); continue; }
       jobs.push({ name: `card${k}`, kind: 'section', seconds: c.t1 - c.t0, card: c.card, voice: voice(c.card.say, 0.15, voiceLens.cards?.[c.i]),
         index: k, of: cards.length, thinkAt: c.thinkAt, image: c.card.imageFile, backdrop: blurred(c.t1 + 0.05, `card${k}`) });
     }
@@ -534,11 +550,14 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     return jobs;
   }
 
+  function sceneJob(c, k) {
+    return { name: `card${k}`, kind: 'scene', seconds: c.t1 - c.t0, scene: c.scene, say: c.say, lead: c.lead, cues: c.cues, step: c.i, kit: cfg.sceneKit };
+  }
   // the cards: HyperFrames compositions when asked for (`hyperframes:`), else (or for any card that
   // 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 ? await renderHyperframesCards(hfJobs(), {
-    W, H, FPS, dark: darkCards, accent, ink, font, lang: cfg.lang, labels: cfg.labels, opts: cfg.hyperframes, work: cfg.work,
+  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',
     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 }) : {};
@@ -555,6 +574,10 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   }
   for (const [k, c] of cards.entries()) {
     if (hf[`card${k}`]) place(`card${k}`, c.t1 - c.t0);
+    else if (c.scene) {
+      await browser.close();
+      throw new Error(`step ${c.i + 1}: the scene ${path.relative(process.cwd(), c.scene.file)} did not render${hf._errors?.[`card${k}`] ? `: ${hf._errors[`card${k}`]}` : ''} — preview it with \`storyshot scene <storyboard> --step ${c.i + 1}\` (MCP: preview_scene), fix it, and render again`);
+    }
     else await animate(card(c.card, c.card.logoFile ?? '', { thinkAt: c.thinkAt }), c.t1 - c.t0, path.join(cfg.work, `card${k}`));
   }
   if (in0) {
@@ -607,7 +630,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const lead = in0 && Math.abs(c.t0 - INTRO) < 0.02 ? Math.min(0.2, INTRO) : 0, s0 = c.t0 - lead;
     inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, `card${k}`, '%04d.jpg'));
     graph += `[${idx}:v]format=rgba,${lead ? `tpad=start_duration=${lead.toFixed(3)}:start_mode=clone,` : ''}setpts=PTS-STARTPTS+${s0.toFixed(3)}/TB,` +
-      `${lead ? '' : `fade=in:st=${c.t0.toFixed(3)}:d=0.15:alpha=1,`}fade=out:st=${Math.max(c.t0, c.t1 - 0.15).toFixed(3)}:d=0.15:alpha=1[sc${k}];\n` +
+      `${lead || c.scene ? '' : `fade=in:st=${c.t0.toFixed(3)}:d=0.15:alpha=1,`}${c.scene ? 'null' : `fade=out:st=${Math.max(c.t0, c.t1 - 0.15).toFixed(3)}:d=0.15:alpha=1`}[sc${k}];\n` +
       `[${last}][sc${k}]overlay=0:0:eof_action=pass:enable='between(t,${s0.toFixed(3)},${c.t1.toFixed(3)})'[v${++idx}];\n`;
     last = `v${idx}`;
   }
@@ -652,7 +675,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // --- 6. preview contact sheet: one frame per step (at its zoom peak) + end card ------------
   // zoomed steps: at the zoom peak; others: late in the step, where its actions' result is visible
   const shots = segs.map((g) => ({ t: Math.min(g.o1 - 0.05, g.zoomPeak ?? g.o0 + (g.o1 - g.o0) * 0.8), label: `step ${g.i + 1} · ${g.o0.toFixed(1)}–${g.o1.toFixed(1)}s${g.step.zoom ? ' · zoom' : ''}`, caption: g.step.caption ?? '' }));
-  for (const c of cards) shots.push({ t: c.t0 + (c.t1 - c.t0) * 0.85, label: `card · ${c.t0.toFixed(1)}–${c.t1.toFixed(1)}s`, caption: c.card.title ?? '' });
+  for (const c of cards) shots.push({ t: c.t0 + (c.t1 - c.t0) * 0.85, label: `${c.scene ? `step ${c.i + 1} scene` : 'card'} · ${c.t0.toFixed(1)}–${c.t1.toFixed(1)}s`, caption: c.card.title || (c.scene ? path.basename(c.scene.file) : '') });
   shots.sort((a, b) => a.t - b.t);
   if (in0) shots.unshift({ t: INTRO * 0.8, label: `intro · 0.0–${INTRO.toFixed(1)}s`, caption: '' });
   if (ec) shots.push({ t: VIDEO + END / 2, label: `end card · ${VIDEO.toFixed(1)}–${TOTAL.toFixed(1)}s`, caption: '' });
@@ -685,7 +708,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
         .map(toOut).filter((t) => t != null && t > 0.2),
       ...segs.filter((g) => g.afterHidden).map((g) => g.o0),
       ...(in0 ? [INTRO - 0.2] : []),
-      ...cards.flatMap((c) => [c.t0, c.t1 - 0.15]),
+      ...cards.filter((c) => !c.scene).flatMap((c) => [c.t0, c.t1 - 0.15]),
       ...(ec ? [VIDEO - 0.25] : []),
     ]),
     risers: segs.filter((g) => g.step.sfx === 'riser').map((g) => [g.o0, g.o1]),
@@ -694,6 +717,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     voice: [
       ...(in0?.say ? [{ text: in0.say, start: 0.15, where: 'intro' }] : []),
       ...cards.filter((c) => c.card.say).map((c) => ({ text: c.card.say, start: c.t0 + 0.15, where: `step ${c.i + 1} card` })),
+      ...cards.filter((c) => c.scene && c.say).map((c) => ({ text: c.say, start: c.t0 + c.lead, where: `step ${c.i + 1} scene`, chunk: true })),
       ...segs.filter((g) => g.step.say).map((g) => ({ text: g.step.say, start: g.o0 + g.sayAt, where: `step ${g.i + 1}` })),
       ...(ec?.say ? [{ text: ec.say, start: VIDEO + 0.05, where: 'end card' }] : []),
     ],
@@ -716,5 +740,5 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     let cx = (x0 + x1) / 2, cy = (y0 + y1) / 2;
     g.crop = { x: even(Math.max(0, Math.min(W - w, cx - w / 2))), y: even(Math.max(0, Math.min(H - h, cy - h / 2))), w: even(w), h: even(h) };
   }
-  return { silent, clean, events, preview, warnings, captions, cards: cards.map((c) => ({ t: c.t0, title: [c.card.kicker, c.card.title].filter(Boolean).join(' · ') })), segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption, doc: g.step.doc ?? g.step.say, crop: g.crop })) };
+  return { silent, clean, events, preview, warnings, captions, cards: cards.filter((c) => !c.scene || c.card.title).map((c) => ({ t: c.t0, title: [c.card.kicker, c.card.title].filter(Boolean).join(' · ') })), segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption, doc: g.step.doc ?? g.step.say, crop: g.crop })) };
 }

package/src/config.mjs

@@ -4,6 +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';
 
 // Built-in labels drawn into the video, by `lang` (e.g. es, es-MX); other languages get English
 export const LABELS = {
@@ -35,6 +36,8 @@ export const PURPOSES = {
   tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
   course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
   docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false, hyperframes: false },
+  // a concept explained with animated scenes the agent writes (no web app to record)
+  explainer: { duration: 'auto', music: { style: 'calm', bpm: 64, volume: 0.3 }, sfx: false, highlight: false, stepNumbers: false, subtitles: true, chapters: true, clips: null, frame: false, pace: 'normal', follow: false, hyperframes: true },
 };
 
 // Where storyboards and their videos go, and how they're named: <site>-<kind>[-<topic>].yaml →
@@ -52,7 +55,7 @@ export const PACES = {
 export const FRAME_STYLES = ['aurora', 'studio', 'dark', 'pastel', 'blur'];
 
 export const VIDEO_DIR = 'videos';
-export const KINDS = { pitch: 'promo', tutorial: 'tutorial', course: 'lesson', docs: 'docs' };
+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
 // (http://10.1.2.3:8080 → 10-1-2-3-8080, http://localhost:3000 → localhost-3000)
 export const siteOf = (url) => {
@@ -70,7 +73,8 @@ export const certError = (e, url) => (/ERR_CERT|ERR_SSL/.test(e?.message ?? '')
 const slug = (s) => String(s).toLowerCase().normalize('NFKD').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 40);
 
 export function defaultStoryboard(url, purpose = 'pitch', topic) {
-  const base = [siteOf(url), KINDS[purpose] ?? purpose, topic && slug(topic)].filter(Boolean).join('-');
+  // an explainer has no site: it is named by its topic
+  const base = (url ? [siteOf(url), KINDS[purpose] ?? purpose, topic && slug(topic)] : [topic && slug(topic), KINDS[purpose] ?? purpose]).filter(Boolean).join('-');
   for (let i = 1; ; i++) {
     const file = path.join(VIDEO_DIR, `${base}${i > 1 ? `-${i}` : ''}.yaml`);
     if (!fs.existsSync(file)) return file;
@@ -86,8 +90,9 @@ export function loadConfig(file, { draft = false } = {}) {
   const raw = YAML.parse(fs.readFileSync(abs, 'utf8'));
   const dir = path.dirname(abs);
   const name = raw.name ?? path.basename(abs).replace(/\.ya?ml$/, '');
-  if (!raw.url) throw new Error('demo.yaml: `url` is required');
   if (!Array.isArray(raw.steps) || !raw.steps.length) throw new Error('demo.yaml: `steps` must be a non-empty list');
+  // 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 };
@@ -103,6 +108,17 @@ export function loadConfig(file, { draft = false } = {}) {
   if (!PACES[pick('pace')]) throw new Error(`pace must be one of ${Object.keys(PACES).join(', ')}`);
 
   const steps = raw.steps.map((s, i) => {
+    // scene: an animation the agent wrote (see scenes.mjs), timed to the step's narration
+    let scene;
+    if (s.scene) {
+      const sc = typeof s.scene === 'string' ? { file: s.scene } : s.scene;
+      if (!sc.file) throw new Error(`step ${i + 1}: scene needs a file: \`scene: scenes/<name>.html\``);
+      if (s.actions?.length) throw new Error(`step ${i + 1}: a scene plays its own animation instead of the web app, so it has no actions — move them into a step of their own`);
+      if (!s.say && typeof s.duration !== 'number') throw new Error(`step ${i + 1}: a scene without a say: line needs a duration in seconds`);
+      scene = { ...SCENE_DEFAULTS, ...sc, file: path.resolve(dir, sc.file) };
+      const card = s.card ? { ...s.card, ...(s.card.image ? { imageFile: path.resolve(dir, s.card.image) } : {}) } : undefined;
+      return { ...s, actions: [], duration: typeof s.duration === 'number' ? s.duration : 'auto', card, scene };
+    }
     const duration = s.duration ?? P.duration;
     if (!s.hidden && duration !== 'auto' && !(duration > 0)) {
       throw new Error(`step ${i + 1}: visible steps need a positive \`duration\` in seconds, or \`duration: auto\``);
@@ -136,6 +152,7 @@ export function loadConfig(file, { draft = false } = {}) {
   const frame = frame0 ? { background: null, window: 'browser', ...(typeof frame0 === 'object' ? frame0 : {}), style: styleOf(frame0) } : null;
   if (frame && !FRAME_STYLES.includes(frame.style)) throw new Error(`frame style must be one of ${FRAME_STYLES.join(', ')}`);
   if (frame && !['browser', 'app'].includes(frame.window)) throw new Error('frame.window must be browser or app');
+  if (!['auto', 'light', 'dark'].includes(raw.ground ?? 'auto')) throw new Error('ground must be light or dark (leave it out and auto reads it from the scenes, or from the frame)');
   if (frame?.icon) frame.iconFile = path.resolve(dir, frame.icon);
 
   // hyperframes: true | { template: lesson | launch, band, bandColors, emblem, hand, backdrop } — cards
@@ -156,6 +173,9 @@ export function loadConfig(file, { draft = false } = {}) {
     const byLang = { kokoro: kokoroVoice, qwen: qwenVoiceFor(raw) }[provider];
     voice = { speed: pace0.voiceSpeed, volume: 1, pause: pace0.sentencePause, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...(raw.lang ? { lang: raw.lang } : {}), ...raw.voice, provider };
     if (!(typeof voice.pause === 'number' && voice.pause >= 0 && voice.pause <= 3)) throw new Error('voice.pause is the shortest pause between the sentences of a line, in seconds, 0–3 (0 leaves the voice as it is)');
+    // explainers: a scene's narration keeps moving (no pause in a line longer than this)
+    if (voice.maxPause === undefined && purpose === 'explainer') voice.maxPause = 0.55;
+    if (voice.maxPause != null && !(typeof voice.maxPause === 'number' && voice.maxPause >= voice.pause)) throw new Error(`voice.maxPause is the longest pause inside a line, in seconds, at least voice.pause (${voice.pause})`);
     if (provider === 'qwen') {
       const v = qwenVoice(voice.voice);
       if (!v) throw new Error(`voice: qwen has no voice "${voice.voice}" (one of ${QWEN_VOICES.join(', ')})`);
@@ -178,10 +198,15 @@ export function loadConfig(file, { draft = false } = {}) {
   const clips = [].concat(pick('clips') ?? []).filter(Boolean);
   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)');
 
+  // scenes: { css: [files], js: [files] } shared by every scene (a palette, drawing helpers), loaded before each one
+  const sk = raw.scenes ?? {};
+  const sceneKit = { css: [].concat(sk.css ?? []).map((f) => path.resolve(dir, f)), js: [].concat(sk.js ?? []).map((f) => path.resolve(dir, f)) };
   return {
     name,
     purpose,
+    sceneKit,
     highlight: pick('highlight'),
     stepNumbers: pick('stepNumbers'),
     subtitles: pick('subtitles'),
@@ -189,7 +214,7 @@ export function loadConfig(file, { draft = false } = {}) {
     clips,
     pace: { name: pick('pace'), ...PACES[pick('pace')] },
     maxWait: raw.maxWait ?? PACES[pick('pace')].maxWait,
-    url: raw.url,
+    url: raw.url ?? null,
     viewport,
     output,
     scale,
@@ -209,6 +234,11 @@ export function loadConfig(file, { draft = false } = {}) {
     // e.g. when burned-in subtitles already carry the words
     captions: raw.captions !== false,
     cards: raw.cards ?? 'auto',
+    // ground: light | dark — is the film light or dark overall? It decides the colour of the burned-in
+    // subtitles (ink letters on a light film, white on a dark one) and the cards' ground. `auto` reads
+    // it from the scenes, or from the frame's backdrop; say it outright when the scenes take their
+    // ground from the shared scene kit, which `auto` cannot always see through.
+    ground: raw.ground ?? 'auto',
     // language of the built-in labels ("Pause and think", "Introduction"): `lang`, else guessed from the captions
     lang: raw.lang ?? (/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(JSON.stringify(raw.steps ?? [])) ? 'zh' : 'en'),
     labels: LABELS[String(raw.lang ?? '').toLowerCase().split(/[-_]/)[0]] ?? (/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(JSON.stringify(raw.steps ?? [])) ? LABELS.zh : LABELS.en),

package/src/hyperframes.mjs

@@ -16,6 +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';
 
 export const HF_VERSION = '0.8.217';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -66,6 +67,22 @@ const run = (cli, args) => new Promise((resolve, reject) => {
   p.on('close', (code) => (code === 0 ? resolve(out) : reject(new Error(out.trim().split('\n').filter(Boolean).slice(-3).join(' | ') || `exit ${code}`))));
 });
 
+// Run the HyperFrames CLI (installing the pinned version on first use); resolves with its exit code and output.
+export async function hyperframesRun(args, { log = console.log } = {}) {
+  const c = hyperframesCli();
+  if (c.error) throw new Error(`HyperFrames: ${c.error}`);
+  const cli = await ensureCli(log);
+  return new Promise((resolve, reject) => {
+    const p = spawn(cli.cmd, [...cli.args, ...args], { env: { ...process.env, HYPERFRAMES_NO_TELEMETRY: '1', DO_NOT_TRACK: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => { err += d; });
+    p.on('error', reject);
+    p.on('close', (code) => resolve({ code, out, err }));
+  });
+}
+export const sceneFontFaces = (font) => fontFaces(font);
+
 // --- narration cues --------------------------------------------------------------------------------
 // When the narration names each item (a bullet, the call to action): the item's earliest content word
 // found in the line after the previous item's, placed by its character position (speech runs at a
@@ -233,7 +250,7 @@ function pageTimeline(D) {
   return { fromTo: (sel, from, to, at = 0) => add(sel, from, to, at), to: (sel, to, at = 0) => add(sel, null, to, at), build };
 }
 
-const doc = ({ W, H, D, css, body, js, bg = 'transparent' }) => `<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=${W}, height=${H}">
+const doc = ({ W, H, D, css, body, js, bg = 'transparent', floor = H * 0.97 }) => `<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=${W}, height=${H}">
 <style>
 *{margin:0;padding:0;box-sizing:border-box}
 html,body{width:${W}px;height:${H}px;overflow:hidden;background:${bg}}
@@ -267,7 +284,7 @@ const refit = () => {
   const box = document.querySelector('[data-fit-box]');
   for (let k = 0; box && fits.length && k < 30; k++) {
     const kids = [...box.querySelectorAll(':scope > *, :scope > .right > *')].filter((c) => c.offsetHeight && !c.classList.contains('right'));
-    if (!kids.length || (Math.min(...kids.map((c) => c.offsetTop)) >= ${H * 0.03} && Math.max(...kids.map((c) => c.offsetTop + c.offsetHeight)) <= ${H * 0.97})) break;
+    if (!kids.length || (Math.min(...kids.map((c) => c.offsetTop)) >= ${H * 0.03} && Math.max(...kids.map((c) => c.offsetTop + c.offsetHeight)) <= ${floor})) break;
     fits.forEach(shrink);
   }
 };
@@ -279,7 +296,10 @@ tl.build();
 
 // --- lesson: tutorials, courses, docs ---------------------------------------------------------------
 function lesson(job, ctx) {
-  const { W, H, dark, font, opts } = ctx, u = H / 1080, D = job.seconds, c = job.card, accent = ctx.accent, ink = ctx.ink;
+  // sizes are designed for 1920x1080; a portrait frame (1080x1920) sizes them by its width instead
+  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)' };
@@ -293,9 +313,11 @@ function lesson(job, ctx) {
   const em = job.kind === 'end' ? null : c.emblem === false ? null : [].concat(c.emblem ?? opts.emblem ?? []).filter(Boolean).slice(0, 3).map(String);
   const emblem = !em?.length ? '' : (() => {
     const a = em[0], z = em.at(-1);
-    const diff = (i) => em.length > 1 && a[i] !== z[i];
-    const row = (s, k) => `<div class="row r${k === 0 ? 'q' : k === em.length - 1 ? 's' : 'm'}">${[...s].map((ch, i) =>
-      `<i class="${(k === 1 && em.length === 3 ? ch !== '|' && ch !== ' ' : diff(i)) ? 'df' : ''}">${ch === ' ' ? '&nbsp;' : esc(ch)}</i>`).join('')}</div>`;
+    // (only lines of the same length line up like an alignment; lines of code differ everywhere)
+    const aligned = em.length > 1 && em.every((x) => x.length === a.length);
+    const diff = (i) => aligned && a[i] !== z[i];
+    const row = (s, k) => `<div class="row r${k === 0 || !aligned ? 'q' : k === em.length - 1 ? 's' : 'm'}">${[...s].map((ch, i) =>
+      `<i class="${aligned && (k === 1 && em.length === 3 ? ch !== '|' && ch !== ' ' : diff(i)) ? 'df' : ''}">${ch === ' ' ? '&nbsp;' : esc(ch)}</i>`).join('')}</div>`;
     return `<div id="aln" class="aln" data-layout-ignore>${em.map(row).join('')}</div>`;
   })();
   const kicker = c.kicker ?? (job.kind === 'end' && c.subtitle && c.bullets?.length && String(c.subtitle).length <= 14 ? c.subtitle : null);
@@ -328,7 +350,7 @@ function lesson(job, ctx) {
 .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}
 .band i,.aln i{font-style:normal}
-.col{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:0 ${W * 0.06}px}
+.col{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:0 ${W * 0.06}px ${lift}px}
 .aln{font:500 ${30 * u}px 'IBM Plex Mono',monospace;letter-spacing:.34em;line-height:1.12;margin-bottom:${44 * u}px;color:${P.muted}}
 .aln .row{white-space:nowrap}.aln i{display:inline-block}
 .aln .rm{color:${strong};opacity:.8}.aln i.df{color:${dark ? accent : P.text};background:${dark ? 'transparent' : accent};font-weight:700}
@@ -364,7 +386,7 @@ h1{font-weight:600;letter-spacing:-.03em;line-height:1.08;max-width:${W * 0.82}p
 .cta.cmd{font:500 ${36 * u}px 'IBM Plex Mono',monospace;background:${dark ? '#1a2238' : ink};color:#e2e8f0;text-align:left}
 .cta.cmd b{color:${accent}}
 #type{display:inline-block;white-space:nowrap}
-.think{position:absolute;left:50%;bottom:${H * 0.1}px;width:${W * 0.3}px;margin-left:${-W * 0.15}px;text-align:center;font-size:${26 * u}px;color:${P.muted}}
+.think{position:absolute;left:50%;bottom:${lift ? H * 0.2 : H * 0.1}px;width:${W * 0.3}px;margin-left:${-W * 0.15}px;text-align:center;font-size:${26 * u}px;color:${P.muted}}
 .tlabel{margin-bottom:${12 * u}px}
 .track{height:${8 * u}px;border-radius:99px;background:${P.line};overflow:hidden}
 .drain{height:100%;background:${accent};transform-origin:0 50%}`;
@@ -427,7 +449,7 @@ ${isCmd(c.cta) ? `tl.fromTo('#type', { clipPath: 'inset(0 100% 0 0)' }, { clipPa
 ${think ? `blurIn('#think', ${n(job.thinkAt)});
 tl.fromTo('#drain', { scaleX: 1 }, { scaleX: 0, duration: ${c.think}, ease: 'none' }, ${n(job.thinkAt)});` : ''}
 `;
-  return doc({ W, H, D, css, body, js, bg: P.ground });
+  return doc({ W, H, D, css, body, js, bg: P.ground, floor: H * 0.97 - lift });
 }
 
 // --- launch: promos ----------------------------------------------------------------------------------
@@ -575,18 +597,39 @@ const hashOf = (...parts) => {
 
 // jobs: [{ name, kind: intro|section|end, seconds, card, voice: {text, start, len}?, index, of, thinkAt,
 //          backdrop?, page?, logo?, logoSize?, logoTarget?, image?, alpha? }]
-// ctx: { W, H, FPS, dark, accent, ink, font, lang, labels, opts, frame: {FX,FY,FW,FH,frameBg,chrome,url}, work }
+// ctx: { W, H, FPS, dark, accent, ink, font, lang, labels, opts, frame: {FX,FY,FW,FH,frameBg,chrome,url}, work, subs (burned-in subtitles) }
 // Returns { [name]: { dir, ext, alpha } } for the cards that rendered; the rest fall back.
+// Scene jobs ({ kind: 'scene', scene, say, lead, cues }) have no fallback: why one failed is in out._errors.
 export async function renderHyperframesCards(jobs, ctx, { log = console.log, warn = log } = {}) {
-  if (!jobs.length) return {};
+  const errors = {};
+  const out = {};
+  Object.defineProperty(out, '_errors', { value: errors, enumerable: false });
+  if (!jobs.length) return out;
   let cli = hyperframesCli();
-  if (cli.error) { warn(`hyperframes: ${cli.error} — using the built-in cards`); return {}; }
-  const template = ctx.opts.template;
+  if (cli.error) {
+    for (const j of jobs) if (j.kind === 'scene') errors[j.name] = cli.error;
+    warn(`hyperframes: ${cli.error} — using the built-in cards`);
+    return out;
+  }
+  const template = ctx.opts?.template;
   const root = path.join(ctx.work, 'hf');
   fs.mkdirSync(root, { recursive: true });
-  const out = {};
   const todo = [];
   for (const job of jobs) {
+    if (job.kind === 'scene') {
+      // the agent's composition, wrapped in a project as long as the scene (see scenes.mjs)
+      const sctx = { ...ctx, fontFaces: fontFaces(ctx.font) };
+      const files = sceneAssets(job.scene.file);
+      const key = hashOf(HF_VERSION, ctx.FPS, job.seconds.toFixed(3), job.lead, job.cues, job.say, ctx.W, ctx.H, ctx.accent, ctx.ink, ctx.font, ctx.lang, ctx.subs,
+        fs.existsSync(job.scene.file) ? fileHash(job.scene.file) : 'missing', ...Object.entries(files).map(([k, f]) => [k, fileHash(f)]),
+        ...[...(job.kit?.css ?? []), ...(job.kit?.js ?? [])].map((f) => [f, fs.existsSync(f) ? fileHash(f) : 'missing']));
+      const dir = path.join(root, `${job.name}-${key}`), frames = path.join(dir, 'frames');
+      if (fs.existsSync(path.join(dir, 'done'))) { out[job.name] = { dir: frames, ext: 'jpg', alpha: false }; continue; }
+      fs.rmSync(dir, { recursive: true, force: true });
+      try { writeSceneProject(job, sctx, dir); } catch (e) { errors[job.name] = e.message; continue; }
+      todo.push({ job, dir, frames, ext: 'jpg', alpha: false });
+      continue;
+    }
     const launchCard = template === 'launch' && job.kind !== 'section';
     if (launchCard) {
       try { await import('roughjs'); } catch { warn('hyperframes: the launch template needs the roughjs package (npm i roughjs) — using the built-in cards'); return {}; }
@@ -622,10 +665,12 @@ export async function renderHyperframesCards(jobs, ctx, { log = console.log, war
   if (!todo.length) return out;
 
   try { cli = await ensureCli(log); } catch (e) {
+    for (const t of todo) if (t.job.kind === 'scene') errors[t.job.name] = `could not install the HyperFrames CLI: ${String(e.message).slice(0, 200)}`;
     warn(`hyperframes: could not install the CLI (${String(e.message).slice(0, 200)}) — using the built-in cards`);
     return out;
   }
-  log(`hyperframes: rendering ${todo.length} card${todo.length > 1 ? 's' : ''} (${cli.how})`);
+  const nScenes = todo.filter((t) => t.job.kind === 'scene').length, nCards = todo.length - nScenes;
+  log(`hyperframes: rendering ${[nScenes && `${nScenes} scene${nScenes > 1 ? 's' : ''}`, nCards && `${nCards} card${nCards > 1 ? 's' : ''}`].filter(Boolean).join(' and ')} (${cli.how})`);
   const one = async (t) => {
     const t0 = Date.now();
     try {
@@ -644,9 +689,10 @@ export async function renderHyperframesCards(jobs, ctx, { log = console.log, war
       }
       fs.writeFileSync(path.join(t.dir, 'done'), '');
       out[t.job.name] = { dir: t.frames, ext: t.ext, alpha: t.alpha };
-      log(`  ${t.job.name}: ${t.job.seconds.toFixed(1)}s card in ${((Date.now() - t0) / 1000).toFixed(0)}s`);
+      log(`  ${t.job.kind === 'scene' ? `step ${t.job.step + 1} scene` : t.job.name}: ${t.job.seconds.toFixed(1)}s ${t.job.kind === 'scene' ? path.basename(t.job.scene.file) : 'card'} in ${((Date.now() - t0) / 1000).toFixed(0)}s`);
     } catch (e) {
-      warn(`hyperframes: the ${t.job.name} card did not render (${String(e.message).slice(0, 300)}) — using the built-in one`);
+      if (t.job.kind === 'scene') errors[t.job.name] = String(e.message).slice(0, 600);
+      else warn(`hyperframes: the ${t.job.name} card did not render (${String(e.message).slice(0, 300)}) — using the built-in one`);
     }
   };
   // two renders at a time (each one drives its own browser)

package/src/init.mjs

@@ -86,3 +86,73 @@ ${page.elements.slice(0, 40).map((e) => `#   y=${String(e.y).padEnd(5)} ${tgt(e.
   fs.writeFileSync(file, yaml);
   return { file: path.resolve(file), yaml, screenshot: page.screenshot, inspect: page.text, login: page.login };
 }
+
+// `storyshot init --purpose explainer --topic <topic>`: no web app, so nothing to inspect — a storyboard
+// of three scene steps and a starter scene file for each, timed to its narration with window.__storyshot.
+export function initExplainer({ topic, file, lang = 'en', portrait = false } = {}) {
+  if (!topic) throw new Error('an explainer is named by its topic: --topic "how a TaqMan probe works" (MCP: topic)');
+  file ??= defaultStoryboard(null, 'explainer', topic);
+  if (fs.existsSync(file)) throw new Error(`${file} already exists — edit it, or choose another path`);
+  const name = path.basename(file).replace(/\.ya?ml$/, '');
+  const dir = path.dirname(path.resolve(file));
+  const zh = /^zh/i.test(lang);
+  const [W, H] = portrait ? [1080, 1920] : [1920, 1080];
+  const scenes = [1, 2, 3].map((k) => ({ id: `${name}-s${k}`.replace(/[^a-z0-9-]/gi, '-'), rel: `scenes/${name}-${k}.html` }));
+  const say = zh
+    ? ['TODO 一个观众会问的问题，一两句话。', 'TODO 用一个具体例子回答，每个短句对应画面上的一个变化。', 'TODO 一句话总结。']
+    : ['TODO the question a viewer would ask, in one or two sentences.', 'TODO answer it with one concrete example, one change on screen per phrase.', 'TODO the idea in one line.'];
+  const yaml = `# Storyshot storyboard (explainer) — every step is a scene: an animation you write as a HyperFrames
+# composition (scenes/*.html), timed to the step's narration. Reference: \`storyshot guide\` ("Scenes and explainers").
+# Loop: write the say: lines → storyshot cues (when each phrase is spoken) → write the scenes with S.at(k)
+#       → storyshot scene ${path.basename(file)} --step N (stills + checks) → storyshot render → look → fix.
+name: ${name}
+purpose: explainer
+out: ${name}.mp4
+${zh ? 'lang: zh\nvoice: { provider: qwen, voice: dylan }      # free, local (Apple Silicon); elsewhere kokoro zf_001' : 'voice: { provider: kokoro }                  # free, local'}
+${portrait ? `output: { width: ${W}, height: ${H} }\nviewport: { width: 900, height: 1600 }\n` : ''}subtitles: burn                                  # or true for an .srt beside the video
+ground: light                                    # light | dark: the film's ground, chosen for the subject and its audience
+                                                 # (\`storyshot guide\`: "The look follows the subject"). Paper for a subject that
+                                                 # is taught, printed or voted on; dark for a mechanism, an instrument or anything
+                                                 # that glows. Subtitles and cards follow it; paint every scene to match.
+theme: { accent: "#b45309", ink: "#17181b" }     # accent: the one colour that points. It also paints the word being
+                                                 # spoken in the subtitles, so it has to read on the ground above
+
+steps:
+${scenes.map((sc, k) => `  - scene: ${sc.rel}${k === 0 ? '\n    # scene: { file: …, title: Chapter title, lead: 0.5, tail: 0.8 }   (lead: seconds before the voice starts)' : ''}
+    say: ${say[k]}`).join('\n\n')}
+`;
+  fs.mkdirSync(path.join(dir, 'scenes', 'assets'), { recursive: true });
+  for (const sc of scenes) fs.writeFileSync(path.join(dir, sc.rel), starterScene(sc.id, W, H));
+  fs.writeFileSync(file, yaml);
+  return { file: path.resolve(file), yaml, scenes: scenes.map((sc) => path.join(dir, sc.rel)) };
+}
+
+// A scene that already works: a ground, a line that lands on the first phrase and a mark that grows on
+// the second. Replace its picture; keep the contract (template, matching ids, timeline registered).
+// Every scene of a film shares one ground (here the light one the storyboard declares): for a dark film,
+// repaint all of them together and set `ground: dark`.
+function starterScene(id, W, H) {
+  return `<template>
+  <style>
+    #${id} { position: absolute; inset: 0; overflow: hidden; background: #f6f2e9; color: var(--ink); font-family: var(--font); }
+    #${id}-line { position: absolute; left: ${Math.round(W * 0.083)}px; right: ${Math.round(W * 0.083)}px; top: ${Math.round(H * 0.33)}px; font-size: ${Math.round(Math.min(W, H * 1.15) * 0.074)}px; font-weight: 600; line-height: 1.25; }
+    #${id}-bar { position: absolute; left: ${Math.round(W * 0.083)}px; top: ${Math.round(H * 0.68)}px; width: ${Math.round(W * 0.5)}px; height: 14px; border-radius: 7px; background: var(--accent); transform-origin: 0 50%; }
+  </style>
+  <div id="${id}" data-composition-id="${id}" data-width="${W}" data-height="${H}">
+    <div id="${id}-line">TODO the picture of this step: the object, diagram or number the voice explains</div>
+    <div id="${id}-bar"></div>
+  </div>
+  <script>
+    (function () {
+      // S.at(k): when phrase k of this step's say: line starts (S.end(k): ends); S.duration, S.width, S.height,
+      // S.safeBottom (px the burned-in subtitles take), S.cues ([{ text, t, end }]). Run \`storyshot cues\` to see them.
+      const S = window.__storyshot;
+      const tl = gsap.timeline({ paused: true });
+      tl.fromTo('#${id}-line', { opacity: 0, filter: 'blur(8px)' }, { opacity: 1, filter: 'blur(0px)', duration: 0.4, ease: 'power3.out' }, S.at(0));
+      tl.fromTo('#${id}-bar', { scaleX: 0 }, { scaleX: 1, duration: 0.8, ease: 'expo.out' }, S.at(1));
+      window.__timelines['${id}'] = tl;
+    })();
+  </script>
+</template>
+`;
+}