explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-coursework/tools/publish.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/* =============================================================================
+   publish.mjs — /publish stage (stage 6): chapters and captions.
+
+   The agent writes out/<name>/<NN>/publish.json (chapters[] + blurb + youtubeTitle);
+   this tool resolves each chapter's timecode from the measured windows, generates the
+   SRT from narration/<key>.src, checks YouTube's chapter rules and title limits, and
+   writes the three deliverables into the video's destination folder
+   (`--dest/<NN>-<slug>/`) beside the MP4:
+
+       title.txt        — the upload title, one line, ≤100 chars
+       description.md   — the blurb, then the chapter block, paste-ready plain text
+       captions.srt     — one cue per segment, verbatim spoken text
+
+   Usage:
+     node tools/publish.mjs --work out/<name>/<NN> \
+                            [--script out/<name>/scripts/<NN>-*.json] \
+                            [--dest <destination>]
+   ========================================================================== */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { videoDir } from './naming.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => {
+  const i = argv.indexOf('--' + n);
+  return i === -1 ? d : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true);
+};
+
+const WORK = flag('work');
+const SCRIPT = flag('script', null);
+const DEST = flag('dest', null);
+
+if (!WORK) {
+  console.error('usage: node tools/publish.mjs --work <work-dir> [--script <script.json>] [--dest <dir>]');
+  process.exit(1);
+}
+
+const workDir = resolve(WORK);
+const timelinePath = join(workDir, 'timeline.json');
+const publishPath = join(workDir, 'publish.json');
+if (!existsSync(timelinePath)) { console.error(`no timeline at ${timelinePath} — run build-audio first`); process.exit(1); }
+if (!existsSync(publishPath)) { console.error(`no publish.json at ${publishPath} — write it first (chapters[] + blurb)`); process.exit(1); }
+
+const tl = JSON.parse(readFileSync(timelinePath, 'utf8'));
+const pub = JSON.parse(readFileSync(publishPath, 'utf8'));
+
+/* Read the script once, up front, so the `--dest` copy and the cross-check below
+   share one parse and can derive the per-video folder from `videoIndex` + title. */
+let script = null;
+if (SCRIPT) {
+  const scriptPath = resolve(SCRIPT);
+  if (existsSync(scriptPath)) script = JSON.parse(readFileSync(scriptPath, 'utf8'));
+}
+const windows = tl.windows || {};
+const segments = tl.segments || [];
+const errors = [];
+const warnings = [];
+
+/* ---- formatting ---- */
+const pad2 = n => String(n).padStart(2, '0');
+const pad3 = n => String(n).padStart(3, '0');
+const srtTs = sec => {
+  const ms = Math.round(sec * 1000);
+  const h = Math.floor(ms / 3600000), m = Math.floor((ms % 3600000) / 60000), s = Math.floor((ms % 60000) / 1000), milli = ms % 1000;
+  return `${pad2(h)}:${pad2(m)}:${pad2(s)},${pad3(milli)}`;
+};
+const chapterTs = sec => {
+  const s = Math.round(sec);
+  const h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), ss = s % 60;
+  return h > 0 ? `${h}:${pad2(m)}:${pad2(ss)}` : `${m}:${pad2(ss)}`;
+};
+const normTitle = t => String(t).toLowerCase()
+  .replace(/^(the|a|an)\s+/, '')
+  .replace(/[^a-z0-9]+/g, ' ')
+  .trim().replace(/\s+/g, ' ');
+
+/* ---- chapters: resolve + validate ---- */
+const resolved = [];
+const chapters = pub.chapters;
+if (!Array.isArray(chapters) || chapters.length === 0) {
+  errors.push('publish.json must contain a non-empty "chapters" array');
+} else {
+  if (chapters.length < 3) errors.push(`need at least 3 chapters (got ${chapters.length}) — YouTube ignores fewer`);
+
+  chapters.forEach((ch, i) => {
+    const at = `chapter ${i + 1}`;
+    const keys = ch && ch.segments;
+    const title = ch && ch.title;
+    if (!Array.isArray(keys) || keys.length === 0) { errors.push(`${at}: "segments" must be a non-empty array of segment keys`); return; }
+    keys.forEach(k => { if (!windows[k]) errors.push(`${at}: segment key "${k}" has no timeline window`); });
+    const t = title == null ? '' : String(title).trim();
+    if (!t) errors.push(`${at}: missing title`);
+    else if (t.length > 40) errors.push(`${at}: title is ${t.length} chars (max 40)`);
+    if (keys[0] && windows[keys[0]]) resolved.push({ i, title: t, start: windows[keys[0]].start });
+  });
+
+  if (resolved.length) {
+    if (chapterTs(resolved[0].start) !== '0:00') {
+      errors.push(`first chapter must start at 0:00 (got ${chapterTs(resolved[0].start)}) — anchor it to the first segment`);
+    }
+    for (let i = 1; i < resolved.length; i++) {
+      if (resolved[i].start <= resolved[i - 1].start) errors.push(`chapter ${resolved[i].i + 1} starts at ${chapterTs(resolved[i].start)}, not after chapter ${resolved[i - 1].i + 1}`);
+    }
+    for (let i = 0; i < resolved.length; i++) {
+      const end = i + 1 < resolved.length ? resolved[i + 1].start : tl.total;
+      if (end - resolved[i].start < 10) errors.push(`chapter ${resolved[i].i + 1} ("${resolved[i].title}") is ${(end - resolved[i].start).toFixed(1)}s — each chapter must be ≥10s`);
+    }
+    const seen = new Map();
+    resolved.forEach(r => {
+      const n = normTitle(r.title);
+      if (!n) return;
+      if (seen.has(n)) errors.push(`chapters ${seen.get(n) + 1} and ${r.i + 1}: duplicate/near-duplicate title "${r.title}"`);
+      else seen.set(n, r.i);
+    });
+  }
+}
+
+/* ---- youtubeTitle: the one line a viewer reads before deciding ---- */
+/* `title` is structural: set at stage 2, it names the folder and must never move.
+   `youtubeTitle` is what YouTube actually shows, and it can only be written once the
+   video exists — which is here. title.txt is also the file `upload_yt_video` reads out
+   of the video's folder, so a missing one is an incomplete upload, not a cosmetic gap. */
+const scriptTitle = script && script.title ? String(script.title) : '';
+const rawTitle = pub.youtubeTitle == null ? '' : String(pub.youtubeTitle);
+let ytTitle = rawTitle.replace(/\s+/g, ' ').trim();
+
+if (!ytTitle) {
+  const fallback = scriptTitle.replace(/\s+/g, ' ').trim();
+  if (fallback) {
+    ytTitle = fallback;
+    warnings.push(`no "youtubeTitle" in publish.json — title.txt fell back to the script title "${fallback}". Author one: it is the only line a viewer reads before deciding to click.`);
+  } else {
+    errors.push('no "youtubeTitle" in publish.json, and no script title (pass --script) to fall back to');
+  }
+}
+
+if (ytTitle) {
+  if (/[\r\n]/.test(rawTitle)) errors.push('"youtubeTitle" contains a line break — title.txt must be a single line');
+  if (ytTitle.length > 100) errors.push(`"youtubeTitle" is ${ytTitle.length} chars — YouTube's hard limit is 100`);
+  else if (ytTitle.length > 70) warnings.push(`"youtubeTitle" is ${ytTitle.length} chars — past ~70 it truncates in mobile listings`);
+  const letters = ytTitle.replace(/[^A-Za-z]/g, '');
+  if (letters.length >= 8 && letters === letters.toUpperCase()) warnings.push('"youtubeTitle" is all uppercase — reads as a gimmick and truncates badly');
+  if (/[!?]{2,}/.test(ytTitle)) warnings.push('"youtubeTitle" stacks "!" or "?" — the same shape as the clickbait it competes with');
+
+  /* A series whose parts are titled near-identically buries itself. Siblings are read
+     opportunistically: a half-written neighbour is not this video's problem. */
+  try {
+    const parent = dirname(workDir);
+    const mine = normTitle(ytTitle);
+    for (const e of readdirSync(parent, { withFileTypes: true })) {
+      if (!e.isDirectory() || join(parent, e.name) === workDir) continue;
+      const sib = join(parent, e.name, 'publish.json');
+      if (!existsSync(sib)) continue;
+      let other = '';
+      try { other = String(JSON.parse(readFileSync(sib, 'utf8')).youtubeTitle || ''); } catch { continue; }
+      if (other && normTitle(other) === mine) warnings.push(`"youtubeTitle" matches video ${e.name}'s ("${other}") — each part of a series needs its own reason to be clicked`);
+    }
+  } catch { /* nothing to compare against */ }
+}
+
+/* ---- captions: one cue per segment, verbatim from the audio ---- */
+const cues = [];
+segments.forEach(sg => {
+  const srcPath = join(workDir, 'narration', `${sg.key}.src`);
+  if (!existsSync(srcPath)) { errors.push(`segment "${sg.key}": missing narration/${sg.key}.src — cannot build its caption`); return; }
+  const text = readFileSync(srcPath, 'utf8').replace(/\s+$/, '');
+  cues.push({ key: sg.key, start: sg.start, end: sg.end, text });
+});
+for (let i = 1; i < cues.length; i++) {
+  if (cues[i].start < cues[i - 1].end) errors.push(`captions overlap at "${cues[i].key}"`);
+}
+
+/* ---- optional cross-check against the script ---- */
+if (SCRIPT) {
+  if (!script) warnings.push(`--script not found or unreadable: ${SCRIPT}`);
+  else {
+    const scriptKeys = new Set((script.segments || []).map(s => s.key));
+    segments.forEach(s => { if (!scriptKeys.has(s.key)) warnings.push(`timeline has segment "${s.key}" not present in the script`); });
+    scriptKeys.forEach(k => { if (!windows[k]) warnings.push(`script has segment "${k}" with no timeline window`); });
+  }
+}
+
+/* ---- report ---- */
+const label = String(WORK).split('/').pop() || 'publish';
+console.log(`\n${label}`);
+console.log('─'.repeat(Math.min(60, label.length + 20)));
+warnings.forEach(w => console.log(`  ⚠ ${w}`));
+if (errors.length) {
+  console.log(`\n  ✗ ${errors.length} error(s):`);
+  errors.forEach(e => console.log(`     - ${e}`));
+  process.exit(2);
+}
+
+/* ---- emit ---- */
+const descLines = [];
+if (pub.blurb && String(pub.blurb).trim()) descLines.push(String(pub.blurb).trim(), '');
+resolved.forEach(r => descLines.push(`${chapterTs(r.start)} ${r.title}`));
+const description = descLines.join('\n') + '\n';
+
+const srt = cues.map((c, i) => `${i + 1}\n${srtTs(c.start)} --> ${srtTs(c.end)}\n${c.text}\n`).join('\n');
+
+const titleOut = join(workDir, 'title.txt');
+const descOut = join(workDir, 'description.md');
+const srtOut = join(workDir, 'captions.srt');
+writeFileSync(titleOut, `${ytTitle}\n`);
+writeFileSync(descOut, description);
+writeFileSync(srtOut, srt);
+
+console.log(`  title    : ${ytTitle.length} chars — "${ytTitle}"`);
+console.log(`  chapters : ${resolved.length}  (${chapterTs(resolved[0].start)} → ${chapterTs(resolved[resolved.length - 1].start)})`);
+console.log(`  captions : ${cues.length} cues  (${(tl.total).toFixed(1)}s of narration)`);
+console.log(`\n[out] ${titleOut}`);
+console.log(`[out] ${descOut}`);
+console.log(`[out] ${srtOut}`);
+
+if (DEST) {
+  /* One folder per video: <dest>/<NN>-<slug>/. The folder, not the filename, is the
+     namespace, so the fixed description.md / captions.srt can never collide. */
+  const dir = join(resolve(DEST), videoDir(script, basename(workDir)));
+  mkdirSync(dir, { recursive: true });
+  copyFileSync(titleOut, join(dir, 'title.txt'));
+  copyFileSync(descOut, join(dir, 'description.md'));
+  copyFileSync(srtOut, join(dir, 'captions.srt'));
+  console.log(`[dest] ${dir}`);
+}

package/skills/explainer-video-from-coursework/tools/render.mjs

@@ -0,0 +1,205 @@
+// Headless frame renderer + encoder. No npm dependencies.
+//
+//   node tools/render.mjs --shots 5,12,22,30,45,60,72,82,90   # quick visual QA
+//   node tools/render.mjs                                     # full render + encode + mux
+//   node tools/render.mjs --fps 24 --keep-frames             # options
+//
+// Pipeline: Chromium (CDP) -> PNG sequence -> ffmpeg H.264 -> mux narration.
+
+import { spawn, execFileSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, rmSync, existsSync, renameSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { chromiumBinOrExit } from './chromium.mjs';
+import { runFrames } from './frame-dedup.mjs';
+import { requireNode, requireCmd } from './env.mjs';
+
+requireNode();
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/* ---------- args ---------- */
+const argv = process.argv.slice(2);
+const flag = (name, def = null) => {
+  const i = argv.indexOf('--' + name);
+  return i === -1 ? def : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true);
+};
+const SHOTS = flag('shots');
+const FPS = parseInt(flag('fps', '30'), 10);
+const KEEP_FRAMES = !!flag('keep-frames', false);
+const PORT = parseInt(flag('port', '9333'), 10);
+const QUALITY = flag('crf', '18');
+// Which scene file to render, and where stills go. Lets us render the hand-written
+// scene and the DSL-driven scene through an identical pipeline for comparison.
+const SCENE = String(flag("scene", "src/scene-diagram.html?scene=srp-split"));
+const SHOT_DIR = flag('shot-dir');
+const OUT_NAME = String(flag('name', 'video'));
+const NARR = String(flag('narration', 'out/narration.wav'));
+// "t0,t1" — render only this slice of the timeline, for per-segment assembly
+const RANGE = flag('range');
+const OUTDIR = String(flag('outdir', 'out'));
+// the per-video work dir (timeline.js + scenes/ + manifest.json live here)
+const WORK = String(flag('work', ''));
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/* ---------- CDP client over Node's built-in WebSocket ---------- */
+async function connect(port) {
+  let target = null;
+  for (let i = 0; i < 60; i++) {
+    await sleep(250);
+    try {
+      const list = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+      target = list.find(t => t.type === 'page' && t.webSocketDebuggerUrl);
+      if (target) break;
+    } catch {}
+  }
+  if (!target) throw new Error('Chromium did not expose a page target');
+
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  let id = 0;
+  const pending = new Map();
+  ws.addEventListener('message', e => {
+    const m = JSON.parse(e.data);
+    if (m.id && pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id); }
+  });
+  await new Promise((res, rej) => {
+    ws.addEventListener('open', res, { once: true });
+    ws.addEventListener('error', rej, { once: true });
+  });
+  const send = (method, params = {}) => new Promise((resolve, reject) => {
+    const myId = ++id;
+    pending.set(myId, m => m.error ? reject(new Error(method + ': ' + JSON.stringify(m.error))) : resolve(m.result));
+    ws.send(JSON.stringify({ id: myId, method, params }));
+  });
+  return { send, close: () => { try { ws.close(); } catch {} } };
+}
+
+/* ---------- main ---------- */
+const BIN = chromiumBinOrExit('render');
+const [sceneFile, sceneQuery] = SCENE.split('?');
+let urlQuery = sceneQuery || '';
+if (WORK) { const workUrl = pathToFileURL(resolve(WORK)).href; urlQuery = urlQuery ? urlQuery + '&work=' + encodeURIComponent(workUrl) : 'work=' + encodeURIComponent(workUrl); }
+const sceneUrl = 'file://' + join(ROOT, sceneFile) + (urlQuery ? '?' + urlQuery : '');
+console.log('[chromium]', BIN);
+
+const proc = spawn(BIN, [
+  '--headless', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+  '--force-device-scale-factor=1', '--allow-file-access-from-files',
+  '--disable-lcd-text', '--font-render-hinting=none',
+  `--remote-debugging-port=${PORT}`,
+  '--window-size=1920,1080',
+  sceneUrl,
+], { stdio: 'ignore' });
+
+let exitCode = 0;
+try {
+  const cdp = await connect(PORT);
+  await cdp.send('Page.enable');
+  await cdp.send('Runtime.enable');
+  await cdp.send('Emulation.setDeviceMetricsOverride',
+    { width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false });
+
+  // wait for the scene to finish building
+  const meta = await (async () => {
+    for (let i = 0; i < 80; i++) {
+      const r = await cdp.send('Runtime.evaluate', {
+        expression: 'JSON.stringify(window.VIDEO_META || null)', returnByValue: true,
+      });
+      const v = r.result.value;
+      if (v && v !== 'null') return JSON.parse(v);
+      await sleep(150);
+    }
+    throw new Error('scene.html never exposed window.VIDEO_META');
+  })();
+  console.log(`[scene] ${meta.width}x${meta.height} @ ${meta.fps}fps, ${meta.total}s`);
+
+  const screenshot = async () => Buffer.from(
+    (await cdp.send('Page.captureScreenshot',
+      { format: 'png', fromSurface: true, captureBeyondViewport: false })).data, 'base64');
+  const shoot = async (t) => {
+    await cdp.send('Runtime.evaluate', { expression: `window.renderAt(${t})`, returnByValue: true });
+    return screenshot();
+  };
+  const evaluate = async (expr) =>
+    (await cdp.send('Runtime.evaluate', { expression: expr, returnByValue: true })).result.value;
+
+  /* ---- QA mode: a handful of stills ---- */
+  if (SHOTS) {
+    const dir = resolve(SHOT_DIR || (WORK ? join(WORK, 'preview') : 'preview'));
+    mkdirSync(dir, { recursive: true });
+    const times = String(SHOTS).split(',').map(s => parseFloat(s.trim())).filter(n => !isNaN(n));
+    for (const t of times) {
+      const buf = await shoot(t);
+      const p = join(dir, `t${String(t).padStart(6, '0')}.png`);
+      writeFileSync(p, buf);
+      console.log(`[shot] t=${t}s -> ${(buf.length/1024).toFixed(0)}KB`);
+    }
+    cdp.close();
+  } else {
+    /* ---- full render ---- */
+    const dir = resolve(WORK ? join(WORK, 'frames') : 'frames');
+    /* Wipe, never inherit. frame_%05d.png is numbered from 1 on every run, so leftover
+       frames from an earlier render in this dir would otherwise be encoded into this
+       one — the frames dir is derived, so nothing here is worth keeping. */
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const slice = RANGE ? String(RANGE).split(',').map(Number) : [0, meta.total];
+    const tStart = slice[0], tEnd = slice[1] == null ? meta.total : slice[1];
+    const total = Math.max(1, Math.round((tEnd - tStart) * FPS));
+    console.log(`[render] ${total} frames @ ${FPS}fps  (t ${tStart}s -> ${tEnd}s)`);
+    /* Capture only the frames that actually change; repeat frames are hardlinked from
+       their predecessor. See tools/frame-dedup.mjs for the probe, the animation gate,
+       and the sampled audit that makes a wrong answer impossible to ship silently. */
+    const stats = await runFrames({ dir, fps: FPS, tStart, tEnd, evaluate, screenshot });
+    console.log(`[dedup] ${stats.screenshots}/${stats.total} screenshots · ` +
+      `${(100 * stats.reused / stats.total).toFixed(1)}% reused · ${stats.distinct} distinct states · ` +
+      `audits ${stats.audits} (${stats.mismatches} mismatched) · capture ${stats.captureSec.toFixed(1)}s`);
+    cdp.close();
+
+    /* ---- encode ---- */
+    requireCmd('ffmpeg');
+    const outDir = resolve(OUTDIR);   // cwd-relative, so an absolute --outdir is honoured
+    mkdirSync(outDir, { recursive: true });
+    const silent = join(outDir, 'video-silent.mp4');
+    console.log('[ffmpeg] encoding H.264…');
+    execFileSync('ffmpeg', ['-y', '-v', 'error', '-framerate', String(FPS),
+      '-i', join(dir, 'frame_%05d.png'),
+      '-c:v', 'libx264', '-preset', 'medium', '-crf', String(QUALITY),
+      '-pix_fmt', 'yuv420p', '-movflags', '+faststart', silent], { stdio: 'inherit' });
+
+    /* ---- mux narration ---- */
+    const narr = resolve(NARR);
+    const final = join(outDir, OUT_NAME + '.mp4');
+    if (existsSync(narr)) {
+      console.log('[ffmpeg] muxing narration…');
+      // apad + -shortest: silence extends the audio, then -shortest cuts at the
+      // VIDEO. Plain -shortest would instead truncate a 52s scene to 45s of audio.
+      execFileSync('ffmpeg', ['-y', '-v', 'error', '-i', silent, '-i', narr,
+        '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-af', 'apad', '-shortest',
+        '-movflags', '+faststart', final], { stdio: 'inherit' });
+      rmSync(silent, { force: true });
+      console.log('[done]', final);
+    } else {
+      // silent cut (e.g. a review pass before audio exists) — still ship the named output
+      rmSync(final, { force: true });
+      renameSync(silent, final);
+      console.log('[done]', final, '(silent — no narration.wav found)');
+    }
+
+    // Frames are worthless once the MP4 is muxed: fully deterministic, free to
+    // regenerate (~6 min CPU, no API calls), and invalidated by any change to the
+    // narration timing anyway. The scarce artefact is narration/, not frames.
+    if (!KEEP_FRAMES) {
+      rmSync(dir, { recursive: true, force: true });
+      console.log('[clean] frames removed (use --keep-frames to retain)');
+    }
+  }
+} catch (err) {
+  console.error('\n[error]', err.message);
+  exitCode = 1;
+} finally {
+  proc.kill();
+}
+
+process.exit(exitCode);

package/skills/explainer-video-from-coursework/tools/resolve-beats.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/* =============================================================================
+   resolve-beats.mjs — the gate between "a beat says which line it belongs to"
+   and "a beat has a number of seconds".
+
+   The bug this closes
+   -------------------
+   A scene used to declare `at: 6.6` — a hand-guessed second. Nothing measured it,
+   so a beat could fire six seconds early and every check still passed. On the
+   module-07 pilot the April reveal fired at 6.60s while the words "In April"
+   start at 12.60s.
+
+   The contract now
+   ----------------
+   A scene declares WHICH LINE of the narration a beat belongs to:
+
+       window.SCENE_BEATS = {
+         beats: [
+           { id: 'march', line: 1, min: 5 },
+           { id: 'april', line: 2, min: 5 },
+         ]
+       }
+
+   and `tools/align.mjs` has measured every line's span. This tool resolves each
+   `line` to seconds, writes `beats.json`, and REFUSES to pass when:
+
+     • a beat carries a raw `at` and no `line`      (a hand-guessed time)
+     • a `line` index does not exist in lines.json  (a stale or invented line)
+     • lines are referenced out of order            (a beat before its own line)
+     • two beats share an id                        (ambiguous resolution)
+     • lines.json is missing or older than the WAV  (stale alignment)
+     • a narration line has no beat at all          (narration with no visual)
+
+   Beat times are written in SCENE time — relative to the segment's render window,
+   so `at = line.start + lead` (lead is measured, not assumed).
+
+   Usage
+     node tools/resolve-beats.mjs --work out/<name>/<NN> [--allow-uncovered]
+     node tools/resolve-beats.mjs --work out/<name>/<NN> --print
+   ========================================================================== */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+
+const flag = (n, d) => {
+  const i = process.argv.indexOf('--' + n);
+  if (i === -1) return d;
+  const v = process.argv[i + 1];
+  return v && !v.startsWith('--') ? v : true;
+};
+
+const WORK = flag('work');
+const SCRIPT = flag('script', null);   // optional: verify lines.json still matches the narration
+const ALLOW_UNCOVERED = !!flag('allow-uncovered', false);
+const PRINT = !!flag('print', false);
+
+if (!WORK) {
+  console.error('usage: node tools/resolve-beats.mjs --work <work-dir> [--allow-uncovered] [--print]');
+  process.exit(1);
+}
+const workDir = resolve(WORK);
+const linesPath = join(workDir, 'lines.json');
+const scenesDir = join(workDir, 'scenes');
+
+const rel = p => p.replace(process.cwd() + '/', '');
+const errors = [];
+const warnings = [];
+
+if (!existsSync(linesPath)) {
+  console.error(`no lines.json at ${rel(linesPath)} — run tools/align.mjs first`);
+  process.exit(1);
+}
+if (!existsSync(scenesDir)) {
+  console.error(`no scenes/ at ${rel(scenesDir)} — author the scenes first (stage 5)`);
+  process.exit(1);
+}
+const linesDoc = JSON.parse(readFileSync(linesPath, 'utf8'));
+const segLines = linesDoc.segments || {};
+
+/* THE LOOP GUARD. The audio stage can be re-invoked from the scene stage to resolve a
+   shortfall. A `pad` only widens the window (line times stay valid), but "extend the
+   narration" changes the WAV — and then every line time in lines.json describes audio
+   that no longer exists. Nothing else would notice, so compare the text hash align.mjs
+   recorded against the script as it stands now. */
+const scriptByKey = (() => {
+  if (!SCRIPT) return null;
+  if (!existsSync(String(SCRIPT))) { errors.push(`--script not found: ${SCRIPT}`); return null; }
+  const doc = JSON.parse(readFileSync(String(SCRIPT), 'utf8'));
+  const sha1 = t => createHash('sha1').update(t).digest('hex');
+  return new Map((doc.segments || []).map(sg => [sg.key, sha1(sg.text)]));
+})();
+if (scriptByKey) {
+  for (const [segKey, seg] of Object.entries(segLines)) {
+    const want = scriptByKey.get(segKey);
+    if (want && seg.textHash && want !== seg.textHash) {
+      errors.push(`${segKey}: narration text changed since align ran — re-run tools/align.mjs (its word cache makes this free unless the audio changed)`);
+    }
+  }
+}
+
+/* Read a scene's declared beats by EXECUTING it with a stubbed `window`, exactly
+   as pacing-check and the scene host do. Regex-parsing the literal would reject
+   hand-written JS object syntax (unquoted keys), which is a legitimate way to
+   author a scene. */
+async function readBeats(path) {
+  const prev = global.window;
+  global.window = {};
+  try {
+    await import(pathToFileURL(path).href + '?v=' + Date.now());
+    const declared = global.window.SCENE_BEATS;
+    if (!declared) return { beats: null };
+    const beats = Array.isArray(declared) ? declared : declared.beats;
+    return { beats: Array.isArray(beats) ? beats : null, legacyArray: Array.isArray(declared) };
+  } catch (e) {
+    return { beats: null, threw: e.message };
+  } finally {
+    global.window = prev;
+  }
+}
+
+const sceneFiles = readdirSync(scenesDir).filter(f => f.endsWith('.js')).sort();
+if (!sceneFiles.length) errors.push(`no scene files in ${rel(scenesDir)}`);
+
+const resolved = {};
+const coveredLines = {};   // segKey -> Set of covered line indices
+
+for (const file of sceneFiles) {
+  const segKey = basename(file, '.js');
+  const { beats, legacyArray, threw } = await readBeats(join(scenesDir, file));
+  const seg = segLines[segKey];
+
+  if (!seg) { errors.push(`${segKey}: scene exists but lines.json has no entry — re-run align.mjs`); continue; }
+  if (!beats) {
+    errors.push(`${segKey}: declares no window.SCENE_BEATS${threw ? ` (scene threw: ${threw})` : ''}`);
+    continue;
+  }
+  if (legacyArray) {
+    warnings.push(`${segKey}: SCENE_BEATS is a bare array — prefer { beats: [...] } so `+
+      `non-beat metadata can live alongside it`);
+  }
+  if (!beats.length) { errors.push(`${segKey}: SCENE_BEATS is empty`); continue; }
+
+  const lead = seg.lead ?? 0;
+  const seenIds = new Set();
+  const out = [];
+  let lastLine = -1;
+  coveredLines[segKey] = new Set();
+
+  for (const b of beats) {
+    const id = b && b.id;
+    if (!id) { errors.push(`${segKey}: a beat has no id`); continue; }
+    if (seenIds.has(id)) { errors.push(`${segKey}: duplicate beat id "${id}"`); continue; }
+    seenIds.add(id);
+
+    if (b.at != null && b.line == null) {
+      errors.push(`${segKey} / ${id}: declares a raw \`at: ${b.at}\` and no \`line\` — a guessed second is exactly the defect this stage removes. Bind the beat to a narration line instead.`);
+      continue;
+    }
+    /* a beat names ONE line, or a RANGE it narrates over — a closing caption
+       legitimately holds while the last two or three sentences play, so the range
+       form lets coverage be satisfied without inventing a visual per sentence. */
+    const range = Array.isArray(b.lines) ? b.lines : (b.line != null ? [b.line, b.line] : null);
+    if (!range) { errors.push(`${segKey} / ${id}: no \`line\` (or \`lines: [from,to]\`) — every beat must name the narration it illustrates`); continue; }
+    if (range.length !== 2 || !range.every(Number.isInteger)) {
+      errors.push(`${segKey} / ${id}: \`lines\` must be [from, to] integers, got ${JSON.stringify(b.lines)}`); continue;
+    }
+    const [lFrom, lTo] = range;
+    if (lFrom < 0 || lTo >= seg.lines.length || lTo < lFrom) {
+      errors.push(`${segKey} / ${id}: lines ${lFrom}…${lTo} do not exist (segment has ${seg.lines.length} lines: 0…${seg.lines.length - 1})`);
+      continue;
+    }
+    if (lFrom < lastLine) warnings.push(`${segKey} / ${id}: line ${lFrom} is before the previous beat's line ${lastLine} — visual order disagrees with narration order`);
+    lastLine = Math.max(lastLine, lTo);
+
+    const L = seg.lines[lFrom];
+    /* A resolved number baked into the scene must still agree with lines.json —
+       otherwise the audio moved and the scene kept the old time. */
+    const want = +(L.start + lead).toFixed(3);
+    if (b.at != null && Math.abs(b.at - want) > 0.06) {
+      errors.push(`${segKey} / ${id}: baked \`at: ${b.at}\` disagrees with line ${b.line}'s measured onset ${want}s — stale resolve, regenerate the scene`);
+      continue;
+    }
+    for (let li = lFrom; li <= lTo; li++) coveredLines[segKey].add(li);
+    out.push({
+      id,
+      line: lFrom,
+      lines: [lFrom, lTo],
+      at: +(L.start + lead).toFixed(3),   // scene time
+      lineStart: L.start,
+      lineEnd: L.end,
+      min: b.min ?? 0,
+      hold: !!b.hold,
+      text: L.text,
+    });
+  }
+  resolved[segKey] = { lead, total: seg.total, window: seg.window, beats: out };
+}
+
+/* coverage: every narration line should have a visual */
+if (!ALLOW_UNCOVERED) {
+  for (const [segKey, seg] of Object.entries(segLines)) {
+    if (!resolved[segKey]) continue;   // no scene yet: reported elsewhere
+    const covered = coveredLines[segKey] || new Set();
+    seg.lines.forEach(L => {
+      if (!covered.has(L.line)) {
+        warnings.push(`${segKey}: line ${L.line} has no beat — "${L.text.slice(0, 58)}…" is narrated with nothing changing on screen`);
+      }
+    });
+  }
+}
+
+const outPath = join(workDir, 'beats.json');
+const doc = {
+  generatedFrom: { lines: 'lines.json', at: linesDoc.generatedFrom?.at || null, resolver: 'tools/resolve-beats.mjs' },
+  note: 'Beat `at` is in SCENE time (relative to the render window): line.start + lead.',
+  segments: resolved,
+};
+writeFileSync(outPath, JSON.stringify(doc, null, 1) + '\n');
+
+/* report */
+const nBeats = Object.values(resolved).reduce((a, s) => a + s.beats.length, 0);
+if (PRINT) {
+  for (const [segKey, s] of Object.entries(resolved)) {
+    console.log(`\n${segKey}  (lead ${s.lead}s)`);
+    s.beats.forEach(b => console.log(`   ${b.id.padEnd(14)} line ${String(b.line).padStart(2)}  at ${b.at.toFixed(2).padStart(7)}s  "${b.text.slice(0, 46)}…"`));
+  }
+}
+console.log(`\n[resolve] ${Object.keys(resolved).length} scene(s) · ${nBeats} beat(s)`);
+if (warnings.length) { console.log(`\n  ⚠ ${warnings.length} warning(s):`); warnings.forEach(w => console.log(`     - ${w}`)); }
+if (errors.length) {
+  console.log(`\n  ✗ ${errors.length} error(s):`);
+  errors.forEach(e => console.log(`     - ${e}`));
+  process.exitCode = 2;
+} else if (!PRINT) {
+  console.log(`  ✓ written: ${rel(outPath)}`);
+  process.exitCode = 0;
+}