storyshot 0.7.3 → 0.9.0

package/src/audio.mjs

@@ -42,6 +42,49 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
       '-f', 'f32le', '-ac', '2', '-ar', `${SR}`, 'pipe:1'], { maxBuffer: 1 << 30 });
     const f = new Float32Array(pcm.buffer, pcm.byteOffset, pcm.length / 4);
     for (let i = 0; i < Math.min(N, f.length / 2); i++) { music[0][i] = f[2 * i] * 0.5; music[1][i] = f[2 * i + 1] * 0.5; }
+  } else if (cfg.music?.style === 'calm') {
+    // calm (explainers): slow pad chords vi–IV–I–V in C, two bars each, a soft bass under them and a
+    // sparse bell; no drums, nothing on the beat that would pull at the voice.
+    // The film has to *end*, not stop. Truncating the loop wherever the video happens to finish leaves
+    // the last chord hanging (and faded down, which a listener hears as "turned off", not "over"), so
+    // the loop is phased to reach IV one chord before the end, the tonic lands there — under the last
+    // spoken line — and rings out through the tail: a plagal cadence, the gentlest full stop there is.
+    const BEAT = 60 / cfg.music.bpm, LEN = BEAT * 8;
+    const chords = [[57, 60, 64], [53, 57, 60], [48, 52, 55], [55, 59, 62]];
+    const CAD = Math.max(0, events.total - LEN);   // where the tonic lands (a clip shorter than one
+                                                   // chord is all cadence, which is the right answer)
+    const before = Math.ceil(CAD / LEN);           // chords before it...
+    const phase = ((2 - before) % 4 + 4) % 4;      // ...phased so the last of them is IV
+    const pad = (ch, t0, len, gain = 1) => {
+      for (const [k, note] of [...ch, ch[0] + 12].entries()) {
+        for (const det of [-0.06, 0.06]) {
+          const f = hz(note + det), filt = svf();
+          add(music, t0, len, (t) => {
+            const env = Math.min(1, t / 1.4) * Math.min(1, Math.max(0, len - t) / 1.6);
+            return filt(saw(f * t) * 0.6 + Math.sin(2 * Math.PI * f * t) * 0.4, 650 + 250 * Math.sin(t * 0.4 + k)).lp * env;
+          }, 0.024 * gain, (k - 1.5) * 0.35 + det * 2);
+        }
+      }
+      const fb = hz(ch[0] - 12);
+      add(music, t0, len, (t) => Math.sin(2 * Math.PI * fb * t) * Math.min(1, t / 0.6) * Math.min(1, Math.max(0, len - t) / 1.2), 0.09 * gain);
+    };
+    for (let b = 0, t0 = 0; t0 < CAD; b++, t0 = b * LEN) {
+      const ch = chords[(b + phase) % chords.length], len = Math.min(LEN, CAD - t0) + 1.2; // rings into the next chord
+      pad(ch, t0, len);
+      if (b % 2 === 0) for (const [j, note] of [ch[2] + 12, ch[1] + 24].entries()) {
+        const f = hz(note);
+        add(music, t0 + j * BEAT * 2, 2.5, (t) => (Math.sin(2 * Math.PI * f * t) + 0.15 * Math.sin(4 * Math.PI * f * t)) * Math.exp(-t * 1.8) * Math.min(1, t / 0.01), 0.03, j ? 0.3 : -0.3);
+      }
+    }
+    // the cadence: the tonic swells a little louder than the loop ever did, with two bells over it
+    const RING = events.total - CAD, TONIC = [48, 52, 55];
+    pad(TONIC, CAD, RING, 1.15);
+    for (const [j, note] of [TONIC[2] + 12, TONIC[0] + 24].entries()) {
+      const f = hz(note);
+      add(music, CAD + j * BEAT, RING, (t) => (Math.sin(2 * Math.PI * f * t) + 0.2 * Math.sin(4 * Math.PI * f * t)) * Math.exp(-t * 0.9) * Math.min(1, t / 0.01), 0.035, j ? 0.3 : -0.3);
+    }
+    // fade in over 2 s; the cadence is what ends the music, so the fade out only guards the cut
+    for (const c of music) for (let i = 0; i < N; i++) c[i] *= Math.min(1, i / SR / 2) * Math.min(1, (N - i) / SR / 1.2);
   } else if (cfg.music) {
     // I–V–vi–IV in C at `bpm`, resolving on the end card (or fading at the end)
     const BEAT = 60 / cfg.music.bpm, BAR = BEAT * 4;
@@ -134,7 +177,7 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   if (cfg.voice && events.voice?.length) {
     let prevEnd = 0;
     for (const line of events.voice) {
-      let { pcm, parts } = await speak(cfg, line.text, { log });
+      let { pcm, parts } = await speak(cfg, line.text, { log, chunk: !!line.chunk });
       let dur = pcm.length / 2 / SR;
       const start = Math.max(line.start, prevEnd + 0.12), room = line.until - start - 0.1;
       let sped = 1;
@@ -198,7 +241,7 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   // so re-encoding by video sites doesn't clip
   execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', silentVideo, '-i', wavFile,
     '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-af', `loudnorm=I=-14:TP=-1.5:LRA=11,aresample=${SR},alimiter=limit=0.7:level=false:attack=1:release=50`, '-ar', `${SR}`, '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', cfg.out]);
-  log(`soundtrack: ${cfg.music ? (cfg.music.file ? 'music file' : `synth ${cfg.music.bpm} bpm`) : 'no music'}, ${events.clicks.length} clicks, ${cfg.sfx?.transitions ? events.whooshes.length : 0} whooshes` +
+  log(`soundtrack: ${cfg.music ? (cfg.music.file ? 'music file' : `synth${cfg.music.style ? ` ${cfg.music.style}` : ''} ${cfg.music.bpm} bpm`) : 'no music'}, ${events.clicks.length} clicks, ${cfg.sfx?.transitions ? events.whooshes.length : 0} whooshes` +
     (cfg.voice ? `, ${events.voice.length} narration lines (${cfg.voice.provider}/${cfg.voice.voice})` : ''));
   return { out: cfg.out, warnings, narration };
 }

package/src/build.mjs

@@ -1,4 +1,7 @@
 // record → compose → soundtrack, shared by the CLI and the MCP server.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { record } from './record.mjs';
 import { compose } from './compose.mjs';
 import { soundtrack } from './audio.mjs';
@@ -7,7 +10,9 @@ import { writeOutputs, burnSubtitles } from './outputs.mjs';
 
 export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const t0 = Date.now();
-  if (mode !== 'compose') await record(cfg, { log });
+  // a storyboard of scenes only (an explainer) has no web app to record: an empty recording stands in
+  if (!cfg.url) noRecording(cfg);
+  else if (mode !== 'compose') await record(cfg, { log });
   if (mode === 'record') return { warnings: [] };
   const voiceLens = await measureVoice(cfg, { log });
   const { silent, clean, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
@@ -16,3 +21,12 @@ export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const extras = await writeOutputs(cfg, { captions, cards, segs, clean, narration: audio.narration, total: events.total }, { log });
   return { out: audio.out, extras, preview, warnings: [...warnings, ...audio.warnings], duration: events.total, seconds: Math.round((Date.now() - t0) / 1000) };
 }
+
+// The recording of a storyboard with nothing to record: one black frame, every step empty.
+export function noRecording(cfg) {
+  fs.mkdirSync(path.join(cfg.work, 'raw'), { recursive: true });
+  const frame = path.join(cfg.work, 'raw', 'blank.jpg');
+  if (!fs.existsSync(frame)) execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-f', 'lavfi', '-i', `color=c=black:s=${cfg.output.width}x${cfg.output.height}`, '-frames:v', '1', frame]);
+  const steps = cfg.steps.map((s) => ({ start: 0, end: 0, hidden: !!s.hidden, zoomBox: null, zoomTarget: null, waits: [], holds: 0, marks: [] }));
+  fs.writeFileSync(path.join(cfg.work, 'timeline.json'), JSON.stringify({ frames: [{ t: 0, file: 'blank.jpg' }], steps, clicks: [], navs: [], gotos: [], urls: [], app: null, introLogo: null, scale: cfg.scale }, null, 1));
+}

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, three: !!cfg.sceneKit?.three });
+      errors.push(...r.errors.map((e) => `step ${i + 1}: ${e}`));
+      warnings.push(...r.warnings.map((w) => `step ${i + 1}: ${w}`));
+      if (!cfg.voice && !(typeof s.duration === 'number')) errors.push(`step ${i + 1}: a scene is as long as its narration, and there is no voice: — add a voice: block, or give the scene a duration`);
+    }
+    if (raw.scenes) unknown(raw.scenes, ['css', 'js', 'three'], 'scenes');
+    for (const f of [...cfg.sceneKit.css, ...cfg.sceneKit.js]) if (!fs.existsSync(f)) errors.push(`scenes: ${f} does not exist`);
+    for (const f of cfg.sceneKit.css) if (!/\.css$/i.test(f)) errors.push(`scenes.css: ${path.basename(f)} is not a .css file`);
+    for (const f of cfg.sceneKit.js) if (!/\.m?js$/i.test(f)) errors.push(`scenes.js: ${path.basename(f)} is not a .js file`);
+    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,10 +550,13 @@ 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(), {
+  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])) },
@@ -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}`;
   }
@@ -636,7 +659,12 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       `[${last}][in]overlay=0:0:eof_action=pass[v${++idx}];\n`;
     last = `v${idx}`;
   }
-  graph += `[${last}]trim=duration=${TOTAL},format=yuv420p[out]`;
+  // The picture needs a full stop too. Without one the file simply ceases on whatever was on screen —
+  // which in an explainer is the recap, the busiest frame of the film, held still and then cut. An end
+  // card is already an ending; otherwise settle to the film's own ground over the last of the tail.
+  const OUTRO = ec ? 0 : Math.min(0.9, TOTAL * 0.02);
+  const outro = OUTRO > 0.05 ? `,fade=out:st=${(TOTAL - OUTRO).toFixed(3)}:d=${OUTRO.toFixed(3)}:color=${filmGround(cfg) === 'light' ? 'white' : 'black'}` : '';
+  graph += `[${last}]trim=duration=${TOTAL},format=yuv420p${outro}[out]`;
   if (clean) graph += `;\n[vclean0]trim=duration=${TOTAL},format=yuv420p[clean]`;
   const graphFile = path.join(cfg.work, 'graph.txt');
   fs.writeFileSync(graphFile, graph);
@@ -652,7 +680,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 +713,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 +722,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 +745,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,22 @@ 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 ?? {};
+  // `three: true` adds storyshot's own drawn-3D helpers (three.js + Kit3) before the storyboard's
+  // own kit files, for scenes whose subject is an object rather than a quantity (guide: "3D scenes").
+  if (sk.three != null && typeof sk.three !== 'boolean') throw new Error('scenes.three is true or false (it loads three.js and storyshot\'s Kit3 helpers into every scene)');
+  const sceneKit = {
+    css: [].concat(sk.css ?? []).map((f) => path.resolve(dir, f)),
+    js: [].concat(sk.js ?? []).map((f) => path.resolve(dir, f)),
+    three: sk.three === true,
+  };
   return {
     name,
     purpose,
+    sceneKit,
     highlight: pick('highlight'),
     stepNumbers: pick('stepNumbers'),
     subtitles: pick('subtitles'),
@@ -189,7 +221,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 +241,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,9 +16,11 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { writeSceneProject, sceneAssets, fileHash } from './scenes.mjs';
 
 export const HF_VERSION = '0.8.217';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
+const KIT3D = path.join(HERE, 'scene-kit', 'kit3d.js');
 // families HyperFrames resolves by name; any other needs an @font-face
 const BUNDLED = ['Inter', 'Montserrat', 'Outfit', 'Nunito', 'Oswald', 'League Gothic', 'Archivo Black', 'Space Mono', 'IBM Plex Mono', 'JetBrains Mono',
   'EB Garamond', 'Playfair Display', 'Source Code Pro', 'Noto Sans JP', 'Roboto', 'Open Sans', 'Lato', 'Poppins'];
@@ -66,6 +68,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
@@ -574,7 +592,10 @@ blurIn('#try', ${n(ctaAt + 0.85)}, { d: 0.25 });` : ''}
 // --- rendering ---------------------------------------------------------------------------------------
 const hashOf = (...parts) => {
   const h = crypto.createHash('sha1');
-  for (const p of parts) h.update(typeof p === 'string' ? p : JSON.stringify(p));
+  // JSON.stringify(undefined) is undefined, not a string, and Hash.update throws on it. A scene step
+  // with a `duration:` and no `say:` line is legal and hashes `job.say` as undefined, so keep a name
+  // for the empty ones rather than crashing the whole render on them.
+  for (const p of parts) h.update(typeof p === 'string' ? p : JSON.stringify(p) ?? String(p));
   return h.digest('hex').slice(0, 16);
 };
 
@@ -582,16 +603,40 @@ const hashOf = (...parts) => {
 //          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, 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)]),
+        // the shipped 3D helpers are part of the picture too: upgrading storyshot has to invalidate
+        // the cached frames of every 3D scene, or a fixed engine renders the old frames back
+        job.kit?.three ? ['kit3d', fileHash(KIT3D)] : 'no-three',
+        ...[...(job.kit?.css ?? []), ...(job.kit?.js ?? [])].map((f) => [f, fs.existsSync(f) ? fileHash(f) : 'missing']));
+      const dir = path.join(root, `${job.name}-${key}`), frames = path.join(dir, 'frames');
+      if (fs.existsSync(path.join(dir, 'done'))) { out[job.name] = { dir: frames, ext: 'jpg', alpha: false }; continue; }
+      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 {}; }
@@ -627,10 +672,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 {
@@ -649,9 +696,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)