storyshot 0.7.2 → 0.8.0

package/src/mcp.mjs

@@ -13,7 +13,8 @@ import { build } from './build.mjs';
 import { record } from './record.mjs';
 import { guide } from './guide.mjs';
 import { check, formatCheck } from './check.mjs';
-import { initStoryboard } from './init.mjs';
+import { initStoryboard, initExplainer } from './init.mjs';
+import { sceneCues, previewScene, formatPreview } from './scene-tools.mjs';
 import { openLoginWindow, finishLogin, authFileFor } from './auth.mjs';
 import { ensureBrowser, ffmpegInstallCommand } from './doctor.mjs';
 import { execFileSync } from 'node:child_process';
@@ -29,7 +30,8 @@ const abs = (p) => path.resolve(p);
 
 const server = new McpServer({ name: 'storyshot', version: pkg.version }, {
   instructions: [
-    'Storyshot makes product demo, tutorial, course and docs videos of web apps from a YAML storyboard.',
+    'Storyshot makes product demo, tutorial, course and docs videos of web apps from a YAML storyboard,',
+    'and explainers: a concept told with animated scenes you write (scene steps; also usable inside tutorials and lessons).',
     'Before writing anything, inspect_page the start url (it reports login walls), then confirm the brief with the user in ONE message:',
     'purpose (pitch/tutorial/course/docs), length, flow, voice, music, subtitles, language, and whether a login is needed (then call login).',
     'Workflow: storyboard_guide (once) → init_storyboard (or inspect_page) → edit the YAML → check_storyboard → render_video',
@@ -49,15 +51,22 @@ server.registerTool('init_storyboard', {
   title: 'Create a starter storyboard',
   description: 'Inspect a URL and write a starter storyboard YAML that already uses verified click targets from that page (listed as comments at the bottom). Start here, then edit the file.',
   inputSchema: {
-    url: z.string().describe('Start page of the web app'),
+    url: z.string().optional().describe('Start page of the web app (not needed for purpose explainer)'),
     path: z.string().optional().describe('Absolute path for the YAML (must not exist yet). Default: <cwd>/videos/<site>-<kind>[-<topic>].yaml, kind = promo/tutorial/lesson/docs from purpose'),
-    purpose: z.enum(['pitch', 'tutorial', 'course', 'docs']).optional().describe('pitch = short promo (default); tutorial = narrated how-to, paced to follow along; course = narrated lesson that explains the why; docs = per-step GIFs/PNGs + a Markdown article'),
+    purpose: z.enum(['pitch', 'tutorial', 'course', 'docs', 'explainer']).optional().describe('pitch = short promo (default); tutorial = narrated how-to, paced to follow along; course = narrated lesson that explains the why; docs = per-step GIFs/PNGs + a Markdown article; explainer = a concept told with animated scenes you write (no url: give topic)'),
+    lang: z.string().optional().describe('explainer: language of the narration, e.g. zh (Mandarin, Qwen3-TTS Dylan) or en'),
+    portrait: z.boolean().optional().describe('explainer: a vertical 1080x1920 video'),
     topic: z.string().optional().describe('Short topic for the file name, e.g. "export-pdf" → videos/<site>-tutorial-export-pdf.yaml. Use it for tutorials/lessons, since a site usually gets several'),
     storage_state: z.string().optional().describe('Absolute path to a saved login (from the login tool) for apps behind a login'),
     ignore_https_errors: z.boolean().optional().describe('Accept a self-signed HTTPS certificate (internal sites only); also writes ignoreHTTPSErrors: true into the storyboard'),
   },
-}, async ({ url, path: file, purpose = 'pitch', topic, storage_state, ignore_https_errors = false }) => {
+}, async ({ url, path: file, purpose = 'pitch', topic, storage_state, ignore_https_errors = false, lang, portrait = false }) => {
   try {
+    if (purpose === 'explainer') {
+      const r = initExplainer({ topic, file: file ? abs(file) : undefined, lang, portrait });
+      return { content: [text(`Wrote ${r.file} and the starter scenes\n${r.scenes.join('\n')}\n\n${r.yaml}\nNext: write the say: lines, call scene_cues, write the scenes with S.at(k), then preview_scene each one.`)] };
+    }
+    if (!url) return fail('give the url of the web app (only purpose: explainer starts without one)');
     await ensureBrowser(() => {});
     const r = await initStoryboard(url, { purpose, topic, file: file ? abs(file) : undefined, storageState: storage_state ? abs(storage_state) : undefined, ignoreHTTPSErrors: ignore_https_errors });
     return { content: [text(`${r.login?.hint ? `ℹ Login: ${r.login.hint}. If the flow needs it, call login first.\n\n` : ''}Wrote ${r.file}:\n\n${r.yaml}`), image(r.screenshot)] };
@@ -143,6 +152,35 @@ server.registerTool('check_storyboard', {
   return { isError: !r.ok, content: [text(formatCheck(r))] };
 });
 
+server.registerTool('scene_cues', {
+  title: 'Scene cues',
+  description: 'For storyboards with scene steps: synthesizes the narration and returns, for every scene, its length and when each phrase of its say: line is spoken (scene seconds = what S.at(k) returns inside the scene). Call it after writing the say: lines and before timing the animations; again after changing a line.',
+  inputSchema: { storyboard: z.string().describe('Absolute path to the storyboard YAML'), draft: z.boolean().optional().describe('use the free local voice') },
+}, async ({ storyboard, draft = false }) => {
+  try {
+    const r = await sceneCues(loadConfig(abs(storyboard), { draft }), { log: () => {} });
+    return { content: [text(`${r.text || 'no scene steps in this storyboard'}\n\n(also in ${r.file})`)] };
+  } catch (e) { return fail(`scene_cues failed: ${e.message}`); }
+});
+
+server.registerTool('preview_scene', {
+  title: 'Preview a scene',
+  description: 'Render stills of one scene step as HyperFrames will (default: a beat into each phrase of its narration, and the last frame), plus HyperFrames lint and its layout/contrast check, in about 20–40 s — without rendering the video. Returns the contact sheet: look at every still (does each part appear when the voice names it? overlaps, crops, text under the subtitles?), fix the scene, preview again.',
+  inputSchema: {
+    storyboard: z.string().describe('Absolute path to the storyboard YAML'),
+    step: z.number().int().min(1).describe('The scene\'s step number (from 1)'),
+    at: z.array(z.number().min(0)).optional().describe('Scene seconds to capture instead of the defaults'),
+    check: z.boolean().optional().describe('Run the layout/contrast check too (default true; ~20 s)'),
+    draft: z.boolean().optional(),
+  },
+}, async ({ storyboard, step, at, check: chk = true, draft = false }) => {
+  try {
+    const r = await previewScene(loadConfig(abs(storyboard), { draft }), step, { at, check: chk, log: () => {} });
+    const pics = r.sheets?.length ? r.sheets.map(image) : r.images.slice(0, 6).map(image);
+    return { isError: !!r.lint.errors.length, content: [text(formatPreview(r, step)), ...pics] };
+  } catch (e) { return fail(`preview_scene failed: ${e.message}`); }
+});
+
 // --- background render jobs -------------------------------------------------------------------
 const jobs = new Map();
 let seq = 0;

package/src/outputs.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { chromium } from 'playwright';
 import { hasFilter } from './ffmpeg.mjs';
+import { filmGround, isDark } from './scenes.mjs';
 
 const plain = (s) => String(s).replace(/\*\*/g, '');
 const srtTime = (t) => {
@@ -90,7 +91,11 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
   // Chinese, Japanese, Korean: no spaces between words, so lines are cut by characters (one line of
   // at most ~18), in a lighter weight and a font that has the glyphs
   const cjk = cfg.lang === 'zh' || narration.some((l) => /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(l.text));
-  const size = Math.round(H * (cjk ? 0.042 : 0.048)), edge = Math.max(2, Math.round(size * (cjk ? 0.07 : 0.09)));
+  // portrait (9:16): size by the width, and keep the lines above the bottom fifth, which short-video
+  // apps cover with the title, the account name and their buttons
+  const portrait = H > W;
+  const size = Math.round(portrait ? W * (cjk ? 0.068 : 0.062) : H * (cjk ? 0.042 : 0.048)), edge = Math.max(2, Math.round(size * (cjk ? 0.07 : 0.09)));
+  const lift = Math.round(H * (portrait ? 0.2 : 0.06)), most = portrait ? Math.floor((W * 0.84) / size) : 18;
   const fontName = cjk && cfg.theme.font === 'Inter' ? (process.platform === 'darwin' ? 'PingFang SC' : 'Noto Sans CJK SC') : cfg.theme.font;
   const cues = []; // { words: [{ w, start, d }] }: one on-screen line each
   for (const line of narration) {
@@ -102,7 +107,7 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
     const total = words.reduce((a, w) => a + weight(w), 0), span = line.end - line.start;
     let at = line.start;
     const timed = words.map((w) => { const d = (span * weight(w)) / total; const r = { w, start: at, d }; at += d; return r; });
-    // chunks of up to 7 words, broken after sentence punctuation
+    // chunks of up to 7 words (5 in portrait), broken after sentence punctuation
     let chunk = [];
     const flush = () => {
       if (!chunk.length) return;
@@ -111,16 +116,21 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
     };
     const len = () => chunk.reduce((a, x) => a + x.w.length, 0);
     for (const x of timed) {
-      // a CJK line ends at a sentence break, or at a comma once it is half full, or at 18 characters
-      if (cjk && chunk.length && len() + x.w.length > 18) flush();
+      // a CJK line ends at a sentence break, or at a comma once it is half full, or when full (18 characters; about 12 in portrait)
+      if (cjk && chunk.length && len() + x.w.length > most) flush();
       chunk.push(x);
-      if (cjk ? /[。！？；!?;]$/.test(x.w) || (/[，、：,:]$/.test(x.w) && len() >= 9) : chunk.length >= 7 || /[.!?;:]$/.test(x.w)) flush();
+      if (cjk ? /[。！？；!?;]$/.test(x.w) || (/[，、：,:]$/.test(x.w) && len() >= most / 2) : chunk.length >= (portrait ? 5 : 7) || /[.!?;:]$/.test(x.w)) flush();
     }
     flush();
   }
   const tmp = cfg.out.replace(/(\.[^.]+)$/, '.burn$1');
   const encode = ['-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-pix_fmt', 'yuv420p', '-c:a', 'copy', '-movflags', '+faststart', tmp];
-  const edgeCol = cfg.theme.ink, sweep = cfg.theme.accent;
+  // The words follow the film's ground (`ground:`, else read from the scenes or the frame): white
+  // letters with an ink outline on a dark film, ink letters with a white outline on a light one, where
+  // white letters would need a dark bar under them. The word being spoken is the accent either way.
+  const light = filmGround(cfg) === 'light' && isDark(cfg.theme.ink);
+  const restCol = light ? cfg.theme.ink : '#ffffff', edgeCol = light ? '#ffffff' : cfg.theme.ink, sweep = cfg.theme.accent;
+  const shade = light ? [255, 255, 255] : [0, 0, 0];
   if (renderer === 'png') {
     // no libass in this ffmpeg: draw each state of each line (the words spoken so far in the accent
     // colour) in Chromium, string them into one transparent track and overlay it
@@ -156,10 +166,10 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
       if (cue.words[0].start > at) push('blank.png', cue.words[0].start);
       for (const [j, x] of cue.words.entries()) {
         const file = `s${String(n++).padStart(5, '0')}.png`;
-        const text = cue.words.map((y, k) => `<span style="color:${k <= j ? sweep : '#fff'}">${esc(y.w)}</span>`).join(cjk ? '' : ' ');
-        await shot(`<div style="position:absolute;left:${Math.round(W * 0.08)}px;right:${Math.round(W * 0.08)}px;bottom:${Math.round(H * 0.06)}px;text-align:center;
+        const text = cue.words.map((y, k) => `<span style="color:${k <= j ? sweep : restCol}">${esc(y.w)}</span>`).join(cjk ? '' : ' ');
+        await shot(`<div style="position:absolute;left:${Math.round(W * 0.08)}px;right:${Math.round(W * 0.08)}px;bottom:${lift}px;text-align:center;
           font-family:${font};font-size:${px}px;font-weight:${cjk ? 400 : 700};line-height:1.2;
-          -webkit-text-stroke:${edge * 2}px ${edgeCol};paint-order:stroke fill;text-shadow:${Math.round(edge * 0.8)}px ${Math.round(edge * 0.8)}px 0 rgba(0,0,0,.5)">${text}</div>`, path.join(dir, file));
+          -webkit-text-stroke:${edge * 2}px ${edgeCol};paint-order:stroke fill;text-shadow:${Math.round(edge * 0.8)}px ${Math.round(edge * 0.8)}px 0 rgba(${shade.join(',')},.5)">${text}</div>`, path.join(dir, file));
         push(file, j + 1 < cue.words.length ? cue.words[j + 1].start : end);
       }
     }
@@ -170,7 +180,7 @@ export async function burnSubtitles(cfg, narration, { log = console.log, rendere
     execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', cfg.out, '-f', 'concat', '-safe', '0', '-i', path.join(dir, 'list.txt'),
       '-filter_complex', '[1:v]format=rgba[s];[0:v][s]overlay=0:0:eof_action=pass,format=yuv420p[v]', '-map', '[v]', '-map', '0:a?', ...encode]);
     fs.renameSync(tmp, cfg.out);
-    return log(`subtitles: burned in ${cues.length} lines with word-by-word highlight (drawn by Storyshot: this ffmpeg has no libass)`);
+    return log(`subtitles: burned in ${cues.length} lines with word-by-word highlight${light ? ', in ink (the film is light)' : ''} (drawn by Storyshot: this ffmpeg has no libass)`);
   }
   const events = cues.map(({ words }) => {
     const s0 = words[0].start, e0 = words.at(-1).start + words.at(-1).d;
@@ -184,7 +194,7 @@ WrapStyle: 0
 
 [V4+ Styles]
 Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Sub,${fontName},${size},${bgr(sweep)},&H00FFFFFF,${bgr(edgeCol)},&H80000000,${cjk ? 0 : 1},0,0,0,100,100,0,0,1,${edge},${Math.round(edge * 0.8)},2,${Math.round(W * 0.08)},${Math.round(W * 0.08)},${Math.round(H * 0.06)},1
+Style: Sub,${fontName},${size},${bgr(sweep)},${bgr(restCol)},${bgr(edgeCol)},${bgr(light ? '#ffffff' : '#000000', '80')},${cjk ? 0 : 1},0,0,0,100,100,0,0,1,${edge},${Math.round(edge * 0.8)},2,${Math.round(W * 0.08)},${Math.round(W * 0.08)},${lift},1
 
 [Events]
 Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
@@ -196,5 +206,5 @@ ${events.join('\n')}
   const arg = file.replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, "\\'");
   execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', cfg.out, '-vf', `ass='${arg}'`, ...encode]);
   fs.renameSync(tmp, cfg.out);
-  log(`subtitles: burned in ${events.length} lines with word-by-word highlight`);
+  log(`subtitles: burned in ${events.length} lines with word-by-word highlight${light ? ', in ink (the film is light)' : ''}`);
 }

package/src/record.mjs

@@ -413,6 +413,7 @@ const isPoint = (v) => v && typeof v === 'object' && typeof v.x === 'number' &&
 // inspectAfter: N → don't record; run setup + steps 1..N quickly, then describe the page as
 // it is at that moment (for states only reachable through the flow, e.g. an editor after upload).
 export async function record(cfg, { log = console.log, inspectAfter = null } = {}) {
+  if (!cfg.url) throw new Error('this storyboard has no url: its steps are all scenes, so there is no web app to record or inspect — preview a scene with `storyshot scene <storyboard> --step N` (MCP: preview_scene)');
   const fast = inspectAfter != null;
   const RAW = path.join(cfg.work, 'raw');
   fs.mkdirSync(cfg.work, { recursive: true });

package/src/scene-tools.mjs

@@ -0,0 +1,123 @@
+// The two tools for writing scenes: the cue table (when each phrase of each scene's narration is
+// spoken, so the animation can land on the words) and a preview of one scene (stills at chosen
+// moments, plus HyperFrames' own lint and layout check), without rendering the whole video.
+import fs from 'node:fs';
+import path from 'node:path';
+import { measureVoice, speak, phraseTimes } from './voice.mjs';
+import { sceneTimings, sceneSeconds, writeSceneProject, formatTimings } from './scenes.mjs';
+import { hyperframesRun, sceneFontFaces } from './hyperframes.mjs';
+
+const SR = 48000;
+
+// Every scene step's timing and cues; also written to .storyshot/<name>/cues.json.
+export async function sceneCues(cfg, { log = console.log } = {}) {
+  const lens = await measureVoice(cfg, { log });
+  const list = sceneTimings(cfg, lens);
+  fs.mkdirSync(cfg.work, { recursive: true });
+  const file = path.join(cfg.work, 'cues.json');
+  fs.writeFileSync(file, JSON.stringify(list.map((s) => ({ ...s, file: path.relative(path.dirname(cfg.work), s.file) })), null, 1));
+  return { list, file, text: formatTimings(list) };
+}
+
+// One scene as HyperFrames will render it: stills at `at` (scene seconds; default: as each phrase is
+// spoken, and the last frame), HyperFrames lint, and (check: true) its layout/contrast check.
+export async function previewScene(cfg, stepNo, { at, check = true, log = console.log } = {}) {
+  const i = stepNo - 1, s = cfg.steps[i];
+  if (!s) throw new Error(`the storyboard has ${cfg.steps.length} steps, not ${stepNo}`);
+  if (!s.scene) throw new Error(`step ${stepNo} is not a scene (it records the web app: preview it with render --draft, or inspect after_step)`);
+  let len = null, cues = [];
+  if (s.say && cfg.voice) {
+    const sp = await speak(cfg, s.say, { log, chunk: true });
+    len = sp.pcm.length / 2 / SR;
+    cues = phraseTimes(sp.pcm, sp.parts);
+  }
+  const seconds = sceneSeconds(s, len);
+  const { width: W, height: H, fps: FPS } = cfg.output;
+  const { accent, ink, font } = cfg.theme;
+  const ctx = { W, H, FPS, accent, ink, font, lang: cfg.lang, subs: cfg.subtitles === 'burn', fontFaces: sceneFontFaces(font) };
+  const job = { name: `step${stepNo}`, kind: 'scene', seconds, scene: s.scene, say: s.say, lead: s.scene.lead, cues, step: i, preview: true, kit: cfg.sceneKit };
+  const dir = path.join(cfg.work, 'scene-preview', `step-${stepNo}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+  writeSceneProject(job, ctx, dir);
+  const local = cues.map((c) => ({ text: c.text, t: +(c.t + s.scene.lead).toFixed(2), end: +(c.end + s.scene.lead).toFixed(2) }));
+
+  // lint: the HyperFrames contract (fast, no browser)
+  const lint = { errors: [], warnings: [] };
+  {
+    const r = await hyperframesRun(['lint', dir, '--json'], { log });
+    try {
+      const j = JSON.parse(r.out.slice(r.out.indexOf('{')));
+      for (const f of j.findings ?? []) {
+        // the wrapper is ours: only what is about the scene file counts
+        if (f.file && !/scene\.html$/.test(f.file)) continue;
+        (f.severity === 'error' ? lint.errors : f.severity === 'warning' ? lint.warnings : []).push(`${f.code}: ${f.message}${f.fixHint ? ` — ${f.fixHint}` : ''}`);
+      }
+    } catch { if (r.code !== 0) lint.errors.push((r.err || r.out).trim().split('\n').slice(-3).join(' | ')); }
+  }
+
+  // stills: as each phrase is spoken (a beat into it), and the end
+  let times = at?.length ? at : [...local.map((c) => c.t + Math.min(0.9, (c.end - c.t) * 0.6)), seconds - 0.05];
+  times = [...new Set(times.map((t) => +Math.max(0, Math.min(seconds - 0.02, t)).toFixed(2)))].sort((a, b) => a - b);
+  if (times.length > 12) times = Array.from({ length: 12 }, (_, k) => times[Math.round(k * (times.length - 1) / 11)]);
+  const shots = path.join(dir, 'shots');
+  const r = await hyperframesRun(['snapshot', dir, '--at', times.join(','), '--no-end', '--output', shots], { log });
+  if (r.code !== 0) throw new Error(`the scene did not load in HyperFrames: ${(r.err || r.out).trim().split('\n').filter(Boolean).slice(-4).join(' | ')}`);
+  const files = fs.existsSync(shots) ? fs.readdirSync(shots).sort() : [];
+  const images = files.filter((f) => /^frame-.*\.png$/.test(f)).map((f) => path.join(shots, f));
+  const sheets = files.filter((f) => /^contact-sheet/.test(f)).map((f) => path.join(shots, f)), sheet = sheets[0] ?? null;
+
+  // check: overlaps, text off the frame, contrast, text too small (needs a browser: ~20 s)
+  const found = { errors: [], warnings: [] };
+  if (check) {
+    const c = await hyperframesRun(['check', dir, '--json', '--samples', '6'], { log });
+    try {
+      const j = JSON.parse(c.out.slice(c.out.indexOf('{')));
+      for (const k of ['runtime', 'layout', 'contrast', 'craft']) {
+        for (const f of j[k]?.findings ?? []) {
+          if (f.severity === 'info') continue;
+          // only the video's own first frame is its thumbnail, and only its last line needs the long hold
+          const visible = cfg.steps.map((x, k) => (x.hidden ? -1 : k)).filter((k) => k >= 0);
+          if (f.code === 'first_frame_empty' && visible[0] !== i) continue;
+          if (f.code === 'line_unread' && /last line/i.test(f.message ?? '') && (visible.at(-1) !== i || cfg.endCard)) continue;
+          if (f.selector && /storyshot-subtitle-band/.test(f.selector)) continue;
+          if (f.code === 'film_silent') continue; // the video's sound comes from Storyshot, not the scene
+          const where = [f.selector, f.time != null ? `at ${Number(f.time).toFixed(1)}s` : null].filter(Boolean).join(' ');
+          const hint = HINTS[f.code] ? ` → ${HINTS[f.code]}` : '';
+          (f.severity === 'error' ? found.errors : found.warnings).push(`${f.code}${where ? ` (${where})` : ''}: ${f.message}${hint}`);
+        }
+      }
+    } catch { found.warnings.push(`the layout check could not run: ${(c.err || c.out).trim().split('\n').slice(-2).join(' | ')}`); }
+    // one line for a finding repeated on siblings (a counter's digits, a row of tiles)
+    for (const k of ['errors', 'warnings']) {
+      const groups = new Map();
+      for (const w of found[k]) {
+        const key = w.replace(/:nth-of-type\(\d+\)/g, '').replace(/ at [\d.]+s/, '').replace(/"[^"]*"/g, '"…"').replace(/[\d.]+ s \(±[\d.]+ s\)/, '').slice(0, 120);
+        groups.set(key, [...(groups.get(key) ?? []), w]);
+      }
+      found[k] = [...groups.values()].map((ws) => (ws.length > 1 ? `${ws[0]} (and ${ws.length - 1} more like it)` : ws[0]));
+    }
+  }
+  return { dir, seconds, cues: local, times, images, sheet, sheets, lint, check: check ? found : null, subs: ctx.subs };
+}
+
+// What to do about the findings agents meet most in scenes (HyperFrames' own messages point at its docs).
+const HINTS = {
+  text_below_floor: 'text meant to be read: at least 28 px at 1080p; a source credit or a label that is only texture may stay small with data-layout-ignore on it',
+  escaped_container: 'a glow or a part meant to spill out of its box: add data-layout-allow-overflow to the box',
+  content_overlap: 'parts meant to overlap (a label on its object): add data-layout-allow-overlap to their container',
+  line_unread: 'hold the text longer: reveal it on an earlier phrase (S.at), or give the scene more tail: (seconds after the voice)',
+  text_occluded: 'text under another element: move one of them, or add data-layout-allow-occlusion if that is the point',
+};
+
+export function formatPreview(r, stepNo) {
+  const list = (xs) => xs.map((x) => `    ${x}`).join('\n');
+  return [
+    `step ${stepNo} scene: ${r.seconds.toFixed(2)}s`,
+    ...(r.cues.length ? ['  cues (scene seconds):', ...r.cues.map((c, k) => `    S.at(${k}) = ${c.t.toFixed(2)} → ${c.end.toFixed(2)}  ${c.text}`)] : ['  (no narration: S.at(k) = lead + k seconds)']),
+    `  stills at ${r.times.join(', ')}s:`, ...r.images.map((f) => `    ${f}`), ...(r.sheets ?? []).map((f) => `  contact sheet: ${f}`),
+    ...(r.lint.errors.length ? ['  ✖ lint errors:', list(r.lint.errors)] : []), ...(r.lint.warnings.length ? ['  ⚠ lint warnings:', list(r.lint.warnings)] : []),
+    ...(r.check ? [r.check.errors.length || r.check.warnings.length ? '  layout check:' : '  ✔ layout check: nothing found', ...r.check.errors.map((e) => `    ✖ ${e}`), ...r.check.warnings.map((w) => `    ⚠ ${w}`)] : []),
+    `  look at every still: does each part appear when the voice names it, and does anything overlap, crop or sit under the subtitles${r.subs ? ' (the striped red band)' : ''}?`,
+    ...(r.lint.errors.length || r.lint.warnings.length || r.check?.errors.length || r.check?.warnings.length ? ['  (references/….md in these messages are HyperFrames docs: https://hyperframes.heygen.com)'] : []),
+  ].join('\n');
+}

package/src/scenes.mjs

@@ -0,0 +1,234 @@
+// Scenes: a step whose picture is an animation the agent writes (a HyperFrames composition) instead
+// of a recording of the web app: a concept, a mechanism, a diagram that grows while the voice explains
+// it. `purpose: explainer` storyboards are made of scenes only (no url, nothing recorded); tutorials
+// and lessons can put a scene between recorded steps.
+//
+// A scene file is one HyperFrames sub-composition: a <template> with a root element whose id and
+// data-composition-id are the same, and a script that registers one paused GSAP timeline under that
+// id. Storyshot wraps it in a project of its own, as long as the step's narration needs, and gives it
+// `window.__storyshot`: the duration, the frame size, the theme, and `cues`, when each phrase of the
+// step's `say:` line is spoken, so the animation lands on the words (`S.at(2)` = when the third phrase
+// starts). Media the scene uses sit in an `assets/` folder next to the scene file.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const SCENE_DEFAULTS = { lead: 0.5, tail: 0.8 };
+export const GSAP_URL = 'https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js';
+
+// How long a scene plays: a fixed `duration`, else its narration plus a lead-in and a tail.
+export function sceneSeconds(step, voiceLen) {
+  if (typeof step.duration === 'number') return step.duration;
+  const { lead, tail } = step.scene;
+  return voiceLen == null ? 4 : Math.max(1.5, lead + voiceLen + tail);
+}
+
+// What a scene file declares, and what is wrong with it (errors stop the render, warnings don't).
+export function sceneInfo(file, { width, height } = {}) {
+  const errors = [], warnings = [];
+  if (!fs.existsSync(file)) return { errors: [`the scene ${file} does not exist — write it (\`storyshot init --purpose explainer\` writes a starter)`], warnings };
+  const html = fs.readFileSync(file, 'utf8');
+  const name = path.basename(file);
+  if (!/<template[\s>]/i.test(html)) errors.push(`${name}: a scene puts its styles, markup and script inside one <template> … </template>`);
+  const id = html.match(/data-composition-id\s*=\s*["']([^"']+)["']/)?.[1];
+  if (!id) errors.push(`${name}: the scene's root element needs data-composition-id="<id>" (and the same id)`);
+  else {
+    const tag = html.match(new RegExp(`<[a-z][^>]*data-composition-id\\s*=\\s*["']${id}["'][^>]*>`, 'i'))?.[0] ?? '';
+    const elId = tag.match(/\sid\s*=\s*["']([^"']+)["']/)?.[1];
+    if (elId !== id) errors.push(`${name}: the root element's id must equal its data-composition-id ("${id}"), or HyperFrames shows a still`);
+    const re = new RegExp(`__timelines\\s*\\[\\s*["'\`]${id}["'\`]\\s*\\]\\s*=`);
+    if (!re.test(html)) errors.push(`${name}: register the scene's timeline: window.__timelines['${id}'] = tl;`);
+    const w = Number(tag.match(/data-width\s*=\s*["'](\d+)/)?.[1]), h = Number(tag.match(/data-height\s*=\s*["'](\d+)/)?.[1]);
+    if (width && height && w && h && (w !== width || h !== height)) errors.push(`${name}: the scene is ${w}x${h} but the video is ${width}x${height} — set data-width/data-height to the video's size`);
+  }
+  if (/\bDate\.now\(|\bnew Date\(|setTimeout\(|setInterval\(|requestAnimationFrame\(/.test(html)) errors.push(`${name}: no clocks or timers in a scene (Date, setTimeout, requestAnimationFrame): everything on screen must follow the timeline, which is seeked frame by frame`);
+  if (/Math\.random\(/.test(html)) warnings.push(`${name}: Math.random() gives a different picture on every render — use a seeded generator`);
+  if (/repeat\s*:\s*-1/.test(html)) errors.push(`${name}: repeat: -1 never ends; repeat a fixed number of times`);
+  if (!/__storyshot/.test(html)) warnings.push(`${name}: times nothing from window.__storyshot — read them from its cues (S.at(k)) so the animation stays on the words when the narration changes`);
+  if (/["'(]\/assets\//.test(html)) errors.push(`${name}: asset paths are relative: "assets/…", not "/assets/…"`);
+  return { id, html, errors, warnings };
+}
+
+// Every file in the scene's assets/ folder: { 'sub/x.png': '/abs/…/assets/sub/x.png' }
+export function sceneAssets(file) {
+  const root = path.join(path.dirname(file), 'assets'), out = {};
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const f = path.join(d, e.name);
+      if (e.isDirectory()) walk(f);
+      else out[path.relative(root, f).split(path.sep).join('/')] = f;
+    }
+  };
+  if (fs.existsSync(root)) walk(root);
+  return out;
+}
+
+// The runtime a scene reads: window.__storyshot.
+//   duration, width, height, lang, lead (when the voice starts), say (the line), safeBottom (px the
+//   burned-in subtitles take at the bottom, 0 without them), theme { accent, ink, font }
+//   cues: [{ text, t, end }] in scene seconds
+//   at(k, offset = 0): when phrase k starts (0-based; -1 = the last; or a piece of its text)
+//   end(k, offset = 0): when it ends
+export function sceneRuntime(job, ctx) {
+  const data = {
+    duration: +job.seconds.toFixed(3), width: ctx.W, height: ctx.H, lang: ctx.lang, lead: job.lead, say: job.say ?? '',
+    safeBottom: ctx.subs ? Math.round(ctx.H > ctx.W ? ctx.H * 0.22 : ctx.H * 0.16) : 0,
+    theme: { accent: ctx.accent, ink: ctx.ink, font: ctx.font },
+    cues: (job.cues ?? []).map((c) => ({ text: c.text, t: +(c.t + job.lead).toFixed(3), end: +(c.end + job.lead).toFixed(3) })),
+  };
+  return `window.__storyshot = Object.assign(${JSON.stringify(data)}, {
+  _find(k) {
+    const c = this.cues;
+    if (!c.length) return null;
+    if (typeof k === 'string') { const i = c.findIndex((x) => x.text.includes(k)); if (i < 0) throw new Error('no cue contains "' + k + '"'); return c[i]; }
+    return c[Math.max(0, Math.min(c.length - 1, k < 0 ? c.length + k : k))];
+  },
+  at(k, offset = 0) { const c = this._find(k); return Math.max(0, (c ? c.t : this.lead + (typeof k === 'number' ? k : 0)) + offset); },
+  end(k, offset = 0) { const c = this._find(k); return Math.max(0, (c ? c.end : this.lead + (typeof k === 'number' ? k + 1 : 1)) + offset); },
+});`;
+}
+
+// GSAP renders a fromTo's start state as soon as it is created. When a later fromTo animates the same
+// property of the same element (a label that fades in, then out), that start state would show from the
+// first frame. A fromTo placed after another on the same element and property gets immediateRender: false
+// unless it says otherwise, so each one takes over when it starts.
+export const GSAP_GUARD = `(function () {
+  if (!window.gsap) return;
+  const P = gsap.core.Timeline.prototype, fromTo = P.fromTo;
+  const NOT = { duration: 1, ease: 1, stagger: 1, delay: 1, immediateRender: 1, overwrite: 1, repeat: 1, yoyo: 1, repeatDelay: 1, id: 1, paused: 1, data: 1,
+    callbackScope: 1, onStart: 1, onUpdate: 1, onComplete: 1, transformOrigin: 1, svgOrigin: 1, autoRound: 1, keyframes: 1 };
+  P.fromTo = function (targets, from, to, position) {
+    if (to && typeof to === 'object' && to.immediateRender === undefined && typeof position === 'number') {
+      let els = [];
+      try { els = gsap.utils.toArray(targets); } catch (e) {}
+      const props = Object.keys(to).filter((k) => !NOT[k]);
+      const seen = this.__storyshotSeen || (this.__storyshotSeen = new Map());
+      if (els.some((el) => props.some((p) => (seen.get(el) || {})[p] < position))) to = Object.assign({}, to, { immediateRender: false });
+      for (const el of els) { const m = seen.get(el) || {}; for (const p of props) m[p] = Math.min(m[p] == null ? Infinity : m[p], position); seen.set(el, m); }
+    }
+    return fromTo.call(this, targets, from, to, position);
+  };
+})();`;
+
+// The project HyperFrames renders for one scene: a root as long as the scene, mounting the scene file.
+// preview: also draw the band the burned-in subtitles will cover (never in a render).
+export function sceneDoc(job, ctx, info) {
+  const { W, H } = ctx, D = job.seconds.toFixed(3);
+  return `<!doctype html><html lang="${ctx.lang ?? 'en'}"><head><meta charset="UTF-8"><meta name="viewport" content="width=${W}, height=${H}">
+<script src="${GSAP_URL}"></script>
+<style>
+${ctx.fontFaces}
+:root{--accent:${ctx.accent};--ink:${ctx.ink};--font:'${ctx.font}','StoryshotCJK',sans-serif;--safe-bottom:${ctx.subs ? Math.round(H > W ? H * 0.22 : H * 0.16) : 0}px}
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:${W}px;height:${H}px;overflow:hidden;background:#000}
+#root{position:relative;width:100%;height:100%;font-family:var(--font)}
+</style>
+<script>${sceneRuntime(job, ctx)}
+${GSAP_GUARD}</script>
+${(job.kit?.css ?? []).map((f, k) => `<link rel="stylesheet" href="kit/${k}-${path.basename(f)}">`).join('\n')}
+${(job.kit?.js ?? []).map((f, k) => `<script src="kit/${k}-${path.basename(f)}"></script>`).join('\n')}
+</head><body>
+<div id="root" data-composition-id="main" data-start="0" data-duration="${D}" data-width="${W}" data-height="${H}">
+<div id="${info.id}" class="clip" data-composition-id="${info.id}" data-composition-src="compositions/scene.html" data-start="0" data-duration="${D}" data-track-index="1" data-width="${W}" data-height="${H}"></div>
+${job.preview && ctx.subs ? `<div id="storyshot-subtitle-band" data-layout-ignore style="position:absolute;left:0;right:0;bottom:0;height:${Math.round(H > W ? H * 0.22 : H * 0.16)}px;z-index:9999;background:repeating-linear-gradient(135deg,rgba(255,64,64,.18) 0 14px,rgba(255,64,64,.08) 14px 28px);border-top:3px dashed rgba(255,64,64,.9);pointer-events:none"><span style="position:absolute;right:24px;top:10px;font:600 26px/1 sans-serif;color:#ff4040">burned-in subtitles</span></div>` : ''}
+</div>
+<script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+export const fileHash = (f) => crypto.createHash('sha1').update(fs.readFileSync(f)).digest('hex');
+
+// Write a scene's project into `dir` (index.html, the scene, its assets). Returns the scene info.
+export function writeSceneProject(job, ctx, dir) {
+  const info = sceneInfo(job.scene.file, { width: ctx.W, height: ctx.H });
+  if (info.errors.length) throw new Error(info.errors.join('; '));
+  fs.mkdirSync(path.join(dir, 'compositions'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'index.html'), sceneDoc(job, ctx, info));
+  fs.writeFileSync(path.join(dir, 'compositions', 'scene.html'), info.html);
+  // the storyboard's scene kit, shared by every scene
+  for (const [kind, list] of Object.entries(job.kit ?? {})) for (const [k, f] of list.entries()) {
+    fs.mkdirSync(path.join(dir, 'kit'), { recursive: true });
+    fs.copyFileSync(f, path.join(dir, 'kit', `${k}-${path.basename(f)}`));
+  }
+  for (const [k, f] of Object.entries(sceneAssets(job.scene.file))) {
+    fs.mkdirSync(path.dirname(path.join(dir, 'assets', k)), { recursive: true });
+    fs.copyFileSync(f, path.join(dir, 'assets', k));
+  }
+  fs.writeFileSync(path.join(dir, 'hyperframes.json'), JSON.stringify({ paths: { blocks: 'compositions', components: 'compositions/components', assets: 'assets' } }));
+  fs.writeFileSync(path.join(dir, 'meta.json'), JSON.stringify({ id: job.name, name: job.name }));
+  return info;
+}
+
+// The scene steps of a storyboard with their timing: [{ i, file, seconds, lead, cues }] (cues in scene seconds).
+export function sceneTimings(cfg, voiceLens) {
+  return cfg.steps.flatMap((s, i) => (!s.scene || s.hidden ? [] : [{
+    i, file: s.scene.file, title: s.scene.title ?? null, seconds: +sceneSeconds(s, voiceLens.steps[i]).toFixed(3), lead: s.scene.lead,
+    voice: voiceLens.steps[i] != null ? +voiceLens.steps[i].toFixed(3) : null,
+    cues: (voiceLens.cues?.[i] ?? []).map((c) => ({ text: c.text, t: +(c.t + s.scene.lead).toFixed(2), end: +(c.end + s.scene.lead).toFixed(2) })),
+  }]));
+}
+
+export function formatTimings(list) {
+  return list.map((s) => [
+    `step ${s.i + 1} · ${path.basename(s.file)} · ${s.seconds.toFixed(2)}s${s.voice != null ? ` (voice ${s.voice.toFixed(2)}s from ${s.lead}s)` : ' (no say: line)'}${s.title ? ` · ${s.title}` : ''}`,
+    ...s.cues.map((c, k) => `  S.at(${k}) = ${c.t.toFixed(2)}  → ${c.end.toFixed(2)}  ${c.text}`),
+  ].join('\n')).join('\n\n');
+}
+
+// How light a hex or rgb() colour is, 0 (black) to 1 (white). null for anything else (a variable, an
+// image, a colour function).
+export function luminance(colour) {
+  const hex = String(colour).match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i)?.[1], rgb = String(colour).match(/rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/i);
+  const c = hex ? (hex.length === 3 ? [...hex].map((h) => parseInt(h + h, 16)) : [0, 2, 4].map((k) => parseInt(hex.slice(k, k + 2), 16))) : rgb ? rgb.slice(1, 4).map(Number) : null;
+  if (!c) return null;
+  const lin = c.map((v) => (v / 255 <= 0.03928 ? v / 255 / 12.92 : ((v / 255 + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+
+// How much two colours differ to the eye, 1:1 to 21:1 (WCAG: large text wants 3, normal text 4.5).
+export function contrast(a, b) {
+  const [la, lb] = [luminance(a), luminance(b)];
+  return la == null || lb == null ? null : +((Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)).toFixed(1);
+}
+
+// Darker than mid-grey? null for a colour this can't read (a variable, an image, a colour function).
+export function isDark(colour) {
+  const l = luminance(colour);
+  return l == null ? null : l < 0.18;
+}
+
+// Whether a scene draws on a dark ground: the background of the rule for its root (a colour, or the
+// first colour of a gradient). A scene whose ground comes from the shared kit (`<div id="x"
+// class="world">` + `.world { background: … }` in scenes.css) has none of its own, so the root's
+// classes are looked up in the kit's CSS too. null when it can't tell (a variable, an image).
+export function sceneIsDark(file, kitCss = '') {
+  const info = fs.existsSync(file) ? sceneInfo(file) : null;
+  if (!info?.id) return null;
+  const tag = info.html.match(new RegExp(`<[a-z][^>]*data-composition-id\\s*=\\s*["']${info.id}["'][^>]*>`, 'i'))?.[0] ?? '';
+  const selectors = [`#${info.id}`, ...(tag.match(/\sclass\s*=\s*["']([^"']*)["']/)?.[1] ?? '').split(/\s+/).filter(Boolean).map((c) => `.${c}`)];
+  for (const css of [info.html, kitCss]) {
+    for (const sel of selectors) {
+      const rule = css.match(new RegExp(`(?<![\\w#.-])${sel.replace('.', '\\.')}\\s*\\{([^}]*)\\}`))?.[1] ?? '';
+      const bg = rule.match(/background(?:-color|-image)?\s*:\s*([^;]+)/)?.[1];
+      const dark = bg ? isDark(bg) : null; // a rule with no background of its own says nothing: try the next one
+      if (dark != null) return dark;
+    }
+  }
+  return null;
+}
+
+// Is the film light or dark overall? That decides what reads on top of it: the colour of the burned-in
+// subtitles, and the ground of the intro, section and end cards. `ground: light | dark` in the
+// storyboard says so outright; otherwise a film of scenes is read from the scenes themselves (a
+// majority vote) and a recording from its frame's backdrop. null when nothing is sure — a recording of
+// a page whose colours we have not measured — and then the subtitles stay white, which carries an
+// outline and works over most screens.
+export function filmGround(cfg) {
+  if (cfg.ground === 'light' || cfg.ground === 'dark') return cfg.ground;
+  if (!cfg.frame) {
+    const kitCss = (cfg.sceneKit?.css ?? []).filter((f) => fs.existsSync(f)).map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+    const grounds = cfg.steps.filter((s) => s.scene && !s.hidden).map((s) => sceneIsDark(s.scene.file, kitCss)).filter((d) => d != null);
+    if (grounds.length) return grounds.filter(Boolean).length * 2 > grounds.length ? 'dark' : 'light';
+  }
+  return ['aurora', 'dark', 'blur'].includes(cfg.frame?.style ?? '') ? 'dark' : null;
+}