explainer-video 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/* =============================================================================
+   assemble.mjs — render every segment of a script and concatenate them.
+
+   Each segment owns a contiguous WINDOW of the finished video (emitted by the
+   audio stage). So assembly is:
+
+     for each segment:
+        render its window slice through its own host + config   -> SILENT part
+     concatenate the parts                                       -> full video
+     mux the single measured narration track                     -> final
+     verify the mux tracks the narration                         -> guard
+
+   Parts are rendered silent on purpose. Muxing narration onto each part would
+   restart the whole track at every segment boundary — which is exactly the bug
+   this file used to have.
+
+   Usage:
+     node tools/assemble.mjs --script out/<name>/scripts/NN-<slug>.json \
+                             --work out/<name>/<NN> --name <output> \
+                              --dest <destination> [--port 9333]
+
+   `--port` (default 9333) is forwarded to every per-segment render.mjs. Chromium's
+   CDP port is the ONE resource two concurrent assemblies share, and sharing it does
+   not fail cleanly: the second render attaches to the first browser's page and
+   encodes the FIRST video's scene under its own name (measured on two concurrent
+   runs — identical decoded frame hashes, exit 0, a valid MP4 of the wrong video).
+   Because that failure is silent, the port is asserted free before segment one.
+   ========================================================================== */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync, copyFileSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createConnection } from 'node:net';
+import { requireCmd } from './env.mjs';
+import { videoDir } from './naming.mjs';
+import { claimWorkDir } from './workdir.mjs';
+
+requireCmd('ffmpeg');
+requireCmd('ffprobe');
+
+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 SCRIPT = flag('script');
+const WORK = String(flag('work', 'out/video'));
+const NAME = String(flag('name', 'video'));
+const FPS = String(flag('fps', '30'));
+const ONLY = flag('only', null);
+const KEEP = !!flag('keep-parts', false);
+const TOLERANCE = parseFloat(flag('audio-tolerance', '1.5'));   // dB
+const DEST = flag('dest', null);   // where to copy the finished mp4 (never committed)
+const PORT = String(flag('port', '9333'));  // CDP port, forwarded to every segment render.
+                                            // One per concurrent assembly (SERIES.md rule 2).
+
+/* Refuse a port someone else already owns. Without this, render.mjs attaches to the
+   other browser's page and encodes the wrong video with no error (see header). */
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host: '127.0.0.1', port: Number(port) });
+    sock.once('connect', () => { sock.destroy(); resolve(false); });  // someone is listening
+    sock.once('error', () => { sock.destroy(); resolve(true); });     // ECONNREFUSED -> free
+    setTimeout(() => { sock.destroy(); resolve(true); }, 750);
+  });
+}
+
+if (!SCRIPT || !existsSync(SCRIPT)) {
+  console.error('usage: node tools/assemble.mjs --script <script.json> --work <dir> --name <output>');
+  process.exit(1);
+}
+
+const run = (cmd, args) => execFileSync(cmd, args, { stdio: 'inherit' });
+const ffprobeDur = f =>
+  parseFloat(execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', f]).toString());
+
+const script = JSON.parse(readFileSync(SCRIPT, 'utf8'));
+
+/* One work dir per video (see tools/workdir.mjs) — parts/, the silent cut and the
+   final MP4 all have fixed names, so a shared dir would overwrite another video. */
+claimWorkDir(WORK, script, 'assemble');
+/* Per-video manifest: <work>/manifest.json. Falls back to the legacy global path so
+   a work dir that hasn't been migrated yet still assembles. */
+const manifestPath = existsSync(join(WORK, 'manifest.json'))
+  ? join(WORK, 'manifest.json')
+  : join(ROOT, 'scenes', 'manifest.json');
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+const timelinePath = join(WORK, 'timeline.json');
+if (!existsSync(timelinePath)) {
+  console.error(`no timeline at ${timelinePath} — run tools/build-audio.mjs first`);
+  process.exit(1);
+}
+const tl = JSON.parse(readFileSync(timelinePath, 'utf8'));
+const windows = tl.windows || {};
+const narration = join(WORK, 'narration.wav');
+
+/* ---------------- pre-flight: nothing missing, windows must tile ---------------- */
+const errors = [];
+script.segments.forEach(sg => {
+  if (!windows[sg.key]) errors.push(`segment "${sg.key}" has no window in the timeline`);
+  if (!manifest.segments[sg.key]) errors.push(`segment "${sg.key}" has no entry in manifest.json`);
+});
+let cursor = 0;
+for (const sg of script.segments) {
+  const w = windows[sg.key];
+  if (!w) continue;
+  if (Math.abs(w.start - cursor) > 0.01) errors.push(`window gap/overlap at "${sg.key}": expected ${cursor.toFixed(2)}, got ${w.start}`);
+  cursor = w.end;
+}
+if (Math.abs(cursor - tl.total) > 0.05) errors.push(`windows end at ${cursor.toFixed(2)} but the timeline is ${tl.total}s`);
+if (errors.length) {
+  console.error('\n[assemble] cannot proceed:');
+  errors.forEach(e => console.error('  ✗ ' + e));
+  process.exit(1);
+}
+
+const order = script.segments.map(s => s.key).filter(k => !ONLY || k === ONLY);
+const partDir = resolve(WORK, 'parts');
+mkdirSync(partDir, { recursive: true });
+
+console.log(`[assemble] ${order.length} segment(s) · timeline ${tl.total}s · narration ${existsSync(narration) ? 'present' : 'MISSING'} · port ${PORT}\n`);
+
+/* ---------------- render each window, SILENT ---------------- */
+if (!(await isPortFree(PORT))) {
+  console.error(`\n[assemble] port ${PORT} is already in use — another render/assemble owns it.`);
+  console.error(`[assemble] Give this run its own --port (e.g. --port ${Number(PORT) + 1}).`);
+  console.error('[assemble] Sharing a CDP port does NOT fail cleanly: the second run attaches to the');
+  console.error('           first browser and encodes the other video\'s frames under its own name.');
+  process.exit(1);
+}
+for (const key of order) {
+  const w = windows[key];
+  const m = manifest.segments[key];
+  const host = manifest.hosts[m.host];
+  if (!host) { console.error(`unknown host "${m.host}" for ${key}`); process.exit(1); }
+  console.log(`▶ ${key.padEnd(7)} ${String(w.dur).padStart(6)}s  (t ${w.start} → ${w.end})  ${m.host}/${m.scene}`);
+  run('node', [join(ROOT, 'tools', 'render.mjs'),
+    '--scene', `${host}?scene=${m.scene}`,
+    '--work', WORK,
+    '--range', `${w.start},${w.end}`,
+    '--name', `part-${key}`,
+    '--outdir', join(WORK, 'parts'),
+    '--fps', FPS,
+    '--port', PORT,
+  ]);
+}
+
+/* ---------------- concatenate (identical codec/size/fps -> stream copy) ---------------- */
+const parts = order.map(k => join(partDir, `part-${k}.mp4`)).filter(existsSync);
+if (parts.length !== order.length) {
+  console.error(`\n[assemble] expected ${order.length} parts, found ${parts.length}`);
+  process.exit(1);
+}
+const listFile = join(partDir, 'concat.txt');
+writeFileSync(listFile, parts.map(p => `file '${resolve(p)}'`).join('\n') + '\n');
+
+const outDir = resolve(WORK);
+const silent = join(outDir, `${NAME}-silent.mp4`);
+const final = join(outDir, `${NAME}.mp4`);
+
+console.log('\n[assemble] concatenating…');
+run('ffmpeg', ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, '-c', 'copy', silent]);
+
+/* ---------------- mux the narration ONCE ---------------- */
+if (existsSync(narration)) {
+  console.log('[assemble] muxing narration (once)…');
+  run('ffmpeg', ['-y', '-v', 'error', '-i', silent, '-i', narration,
+    '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-af', 'apad', '-shortest',
+    '-movflags', '+faststart', final]);
+  rmSync(silent, { force: true });
+} else {
+  console.log('[assemble] no narration.wav — leaving a silent cut');
+  rmSync(final, { force: true });
+  execFileSync('mv', [silent, final]);
+}
+
+/* ---------------- VERIFY: audio must match the narration sample-for-sample ----------------
+   RMS was too weak a test: speech sits at a roughly constant level, so a part
+   playing the WRONG slice can still look right. verify-audio.mjs compares the
+   residual energy after subtraction, which separates "same audio" (near 0) from
+   "different audio" (~1.4) unambiguously. */
+let verdict = 'skipped (no narration)';
+if (existsSync(narration)) {
+  console.log('\n[verify] finished audio vs narration track…');
+  try {
+    const out = execFileSync('node', [join(ROOT, 'tools', 'verify-audio.mjs'),
+      '--video', final, '--narration', narration], { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    process.stdout.write(out);
+    verdict = 'ok';
+  } catch (e) {
+    process.stdout.write(String(e.stdout || ''));
+    process.stderr.write(String(e.stderr || ''));
+    console.error('  ✗ a part is playing the wrong slice of narration (double mux?)');
+    process.exit(2);
+  }
+}
+
+/* ---------------- report ---------------- */
+const dur = ffprobeDur(final);
+console.log(`\n[done] ${final}`);
+console.log(`       ${parts.length} segments · ${dur.toFixed(2)}s · ${(dur / 60).toFixed(2)} min · audio ${verdict}`);
+
+/* ---------------- deliver: the mp4 is the only thing the user keeps ---------
+   Copy it to a destination they own; the work dir stays scratch and disposable. */
+if (DEST) {
+  /* The finished MP4 goes into the video's own folder — the same <NN>-<slug> that
+     publish.mjs uses for description.md / captions.srt — so a series sorts into
+     consumption order and the three deliverables never collide across videos. */
+  const dir = join(resolve(DEST), videoDir(script, basename(WORK)));
+  mkdirSync(dir, { recursive: true });
+  const destPath = join(dir, NAME + '.mp4');
+  copyFileSync(final, destPath);
+  console.log(`[dest] ${destPath}`);
+}
+
+if (!KEEP) {
+  for (const f of readdirSync(partDir)) rmSync(join(partDir, f), { force: true });
+  console.log('[clean] parts removed (use --keep-parts to retain)');
+}

package/skills/explainer-video-from-coursework/tools/build-audio.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/* =============================================================================
+   build-audio.mjs — the /audio stage: narration script -> measured audio.
+
+   This is the ONLY stage that calls an API (Gemini TTS). Everything else in the
+   pipeline runs offline.
+
+   It does not estimate. It synthesizes, MEASURES the real duration of every
+   segment with ffprobe, and emits a timeline of absolute start/end times. Scene
+   timings are then bound to those measurements rather than to a wpm guess.
+
+   Usage:
+     node tools/build-audio.mjs --script out/<name>/scripts/NN-<slug>.json \
+                                --out out/<name>/<NN> \
+                                [--only <key>] [--voice Aoede] [--model gemini-3.8-flash-lite-tts] [--interactive]
+   ========================================================================== */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { synthesize, synthesizeBatch, DEFAULT_MODEL, FALLBACK_MODEL } from './tts-gemini.mjs';
+import { loadKey, describe, storeHint } from './key-source.mjs';
+import { claimWorkDir } from './workdir.mjs';
+import { requireCmd } from './env.mjs';
+
+requireCmd('ffmpeg');
+requireCmd('ffprobe');
+
+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 SCRIPT = flag('script');
+const OUT_DIR = String(flag('out', 'out'));
+const ONLY = flag('only', null);                  // synthesize just one segment key
+const VOICE = String(flag('voice', 'Aoede'));
+const MODEL = String(flag('model', 'gemini-3.8-flash-lite-tts'));
+const INTERACTIVE = !!flag('interactive', false);  // opt OUT of batch: per-segment, synchronous
+const BATCH = !INTERACTIVE;                        // default: one batch job for all pending segments
+const FALLBACK = MODEL === FALLBACK_MODEL ? DEFAULT_MODEL : FALLBACK_MODEL;  // the other TTS model
+const LEAD = parseFloat(flag('lead', '0.6'));     // silence before the first word
+const GAP = parseFloat(flag('gap', '0.75'));      // silence between segments
+const TAIL = parseFloat(flag('tail', '1.6'));     // silence after the last word
+const SR = 22050;
+
+if (!SCRIPT || !existsSync(SCRIPT)) {
+  console.error('usage: node tools/build-audio.mjs --script <script.json> --out <dir> [--only key]');
+  process.exit(1);
+}
+
+const run = (cmd, args) => execFileSync(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+const durationOf = f => parseFloat(
+  run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', f]).toString().trim()
+);
+
+const script = JSON.parse(readFileSync(SCRIPT, 'utf8'));
+
+/* One work dir per video, or the fixed artefact names collide: a second video's
+   run would overwrite the first's timeline.json and everything downstream would
+   read the wrong video's timings. Checked before any filesystem or API work. */
+claimWorkDir(OUT_DIR, script, 'build-audio');
+
+const narDir = join(OUT_DIR, 'narration');
+mkdirSync(narDir, { recursive: true });
+
+const { key, source: keySrc, store } = loadKey(flag('key'));
+if (!key) { console.error('No API key found. Store it in your OS secret store.\n' + storeHint(store)); process.exit(1); }
+console.log(`[auth]  ${describe(keySrc, key)}`);
+console.log(`[model] ${MODEL}  voice=${VOICE}${BATCH ? `  batch (fallback ${FALLBACK})` : ''}`);
+
+const wanted = script.segments.filter(s => !ONLY || s.key === ONLY);
+if (!wanted.length) { console.error(`no segment matched --only ${ONLY}`); process.exit(1); }
+
+const segments = [];
+let cursor = LEAD;
+let calls = 0;
+let batchJobs = 0;
+
+/* ---- phase 1: ensure every wanted segment has its WAV on disk ---- */
+const missing = [];
+const wasCached = new Map();
+for (const seg of wanted) {
+  const wav = join(narDir, `${seg.key}.wav`);
+  const srcFile = join(narDir, `${seg.key}.src`);
+  const cached = existsSync(wav) && existsSync(srcFile) && readFileSync(srcFile, 'utf8') === seg.text;
+  wasCached.set(seg.key, cached && !flag('force'));
+  if (cached && !flag('force')) {
+    console.log(`  [tts] ${seg.key.padEnd(7)} reused (text unchanged)`);
+  } else {
+    missing.push(seg);
+  }
+}
+
+if (missing.length) {
+  if (BATCH) {
+    const { segments: made, jobs } = await synthesizeBatch({
+      segments: missing.map(s => ({ key: s.key, text: s.text, style: s.style })),
+      voice: VOICE, model: MODEL, fallbackModel: FALLBACK, key,
+    });
+    batchJobs += jobs;
+    for (const { key: k, wav: buf } of made) {
+      const seg = missing.find(s => s.key === k);
+      const raw = join(narDir, `${k}.raw.wav`);
+      const wavPath = join(narDir, `${k}.wav`);
+      writeFileSync(raw, buf);
+      run('ffmpeg', ['-y', '-v', 'error', '-i', raw, '-ar', String(SR), '-ac', '1', wavPath]);
+      rmSync(raw, { force: true });
+      writeFileSync(join(narDir, `${k}.src`), seg.text);
+      calls++;
+      console.log(`  [tts] ${k.padEnd(7)} ${durationOf(wavPath).toFixed(2)}s  (${seg.text.split(/\s+/).filter(Boolean).length} words)`);
+    }
+  } else {
+    for (const seg of missing) {
+      process.stdout.write(`  [tts] ${seg.key.padEnd(7)} … `);
+      try {
+        const { wav: buf } = await synthesize({ text: seg.text, voice: VOICE, style: seg.style, model: MODEL, key });
+        const raw = join(narDir, `${seg.key}.raw.wav`);
+        writeFileSync(raw, buf);
+        run('ffmpeg', ['-y', '-v', 'error', '-i', raw, '-ar', String(SR), '-ac', '1', join(narDir, `${seg.key}.wav`)]);
+        rmSync(raw, { force: true });
+        writeFileSync(join(narDir, `${seg.key}.src`), seg.text);
+        calls++;
+        console.log(`${durationOf(join(narDir, `${seg.key}.wav`)).toFixed(2)}s  (${seg.text.split(/\s+/).filter(Boolean).length} words)`);
+      } catch (e) {
+        console.log('FAILED');
+        console.error('\n[error] ' + e.message.split('\n')[0]);
+        process.exit(1);
+      }
+    }
+  }
+}
+
+/* ---- phase 2: measure every segment and build the timeline ---- */
+for (const seg of wanted) {
+  const dur = durationOf(join(narDir, `${seg.key}.wav`));
+  // A segment may declare a hold: extra silence after the spoken words, giving the
+  // visuals room a beat needs beyond its narration. pacing-check reports the
+  // shortfall; this pad resolves it (and re-running is free — the TTS is cached).
+  const pad = Number(seg.pad) || 0;
+  segments.push({ key: seg.key, start: +cursor.toFixed(3), end: +(cursor + dur).toFixed(3), duration: +dur.toFixed(3), pad: pad, words: seg.text.split(/\s+/).filter(Boolean).length, cached: !!wasCached.get(seg.key) });
+  cursor += dur + pad + GAP;
+}
+
+const total = +(cursor - GAP + TAIL).toFixed(3);
+
+/* ---- partial runs must not touch the global artefacts ----
+   `--only` is a smoke test ("does TTS work for this segment?"). It used to write
+   the concatenated `narration.wav`, `timeline.json` and `timeline.js` from that
+   one segment, silently replacing a finished video's timeline with a one-scene
+   version that no downstream stage could use. A partial run now stops here with a
+   segment-scoped timeline and leaves the global artefacts exactly as they were. */
+const complete = wanted.length === script.segments.length;
+if (!complete) {
+  const suffix = wanted.map(s => s.key).join('+');
+  const partialPath = join(OUT_DIR, `timeline.${suffix}.json`);
+  writeFileSync(partialPath, JSON.stringify({
+    script: SCRIPT, voice: VOICE, model: MODEL, measured: true, partial: true,
+    requested: wanted.length, of: script.segments.length, total, segments,
+  }, null, 2));
+
+  const hadGlobal = existsSync(join(OUT_DIR, 'timeline.json'));
+  console.log(`\n[partial] ${wanted.length} of ${script.segments.length} segment(s) requested — a partial run.`);
+  console.log(`[partial] NOT written: narration.wav, timeline.json, timeline.js${hadGlobal ? ' (an existing timeline.json was left untouched)' : ''}`);
+  console.log(`[partial] measured timeline: ${partialPath}`);
+  console.log(`[partial] re-run without --only to rebuild the full track.`);
+  process.exit(0);
+}
+
+/* ---- build the full narration track (silence + segments + silence) ---- */
+const sil = (name, secs) => {
+  const p = join(narDir, `silence-${name}.wav`);
+  run('ffmpeg', ['-y', '-v', 'error', '-f', 'lavfi', '-i', `anullsrc=r=${SR}:cl=mono`, '-t', String(secs), p]);
+  return p;
+};
+
+const parts = [];
+if (LEAD > 0) parts.push(sil('lead', LEAD));
+wanted.forEach((seg, i) => {
+  parts.push(join(narDir, `${seg.key}.wav`));
+  const pad = Number(seg.pad) || 0;
+  if (pad > 0) parts.push(sil(`${seg.key}-hold`, pad));
+  const isLast = i === wanted.length - 1;
+  const gap = isLast ? TAIL : GAP;
+  if (gap > 0) parts.push(sil(isLast ? 'tail' : 'gap', gap));
+});
+// ffmpeg resolves entries in a concat list RELATIVE TO THE LIST FILE, so every
+// entry must be absolute or paths silently double up.
+const listFile = join(narDir, 'concat.txt');
+writeFileSync(listFile, parts.map(p => `file '${resolve(p)}'`).join('\n') + '\n');
+run('ffmpeg', ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, '-ar', String(SR), '-ac', '1', join(OUT_DIR, 'narration.wav')]);
+const trackDur = durationOf(join(OUT_DIR, 'narration.wav'));
+
+// Each segment OWNS a contiguous slice of the finished video: from its lead-in
+// to the next segment's lead-in. These tile the whole timeline with no gaps, so
+// per-segment renders can simply be concatenated.
+const windows = {};
+const grandTotal = Math.max(total, trackDur);
+segments.forEach((sg, i) => {
+  const wStart = i === 0 ? 0 : sg.start - LEAD;
+  const wEnd = i === segments.length - 1 ? grandTotal : segments[i + 1].start - LEAD;
+  windows[sg.key] = { start: +wStart.toFixed(3), end: +wEnd.toFixed(3), dur: +(wEnd - wStart).toFixed(3) };
+});
+
+const timeline = {
+  script: SCRIPT,
+  voice: VOICE,
+  model: MODEL,
+  measured: true,
+  total: grandTotal,
+  segments,
+  windows,
+  calls,
+};
+writeFileSync(join(OUT_DIR, 'timeline.json'), JSON.stringify(timeline, null, 2));
+
+// scenes: a browser host loads this with <script> — file:// cannot fetch JSON
+// Per-video: the browser-loadable timeline lives beside timeline.json, so a second
+// video no longer overwrites a global src/timeline.js (ROADMAP §1, "Work-dir layout").
+const scenes = {};
+segments.forEach(sg => { scenes[sg.key] = { start: sg.start, end: sg.end, dur: sg.duration }; });
+writeFileSync(join(OUT_DIR, 'timeline.js'),
+  'window.TIMELINE = ' + JSON.stringify({
+    fps: 30, width: 1920, height: 1080,
+    total: grandTotal, scenes, windows, segments,
+  }, null, 2) + ';\n');
+
+console.log(`\n[audio] ${calls} segment(s) synthesized${BATCH ? ` via ${batchJobs} batch job(s)` : ''} · narration track ${trackDur.toFixed(2)}s`);
+console.log(`[windows] ${Object.entries(windows).map(([k, w]) => k + ' ' + w.dur + 's').join(' · ')}`);
+segments.forEach(s => console.log(`   ${s.key.padEnd(7)} ${String(s.start).padStart(7)}s -> ${String(s.end).padStart(7)}s  (${s.duration}s)`));
+console.log(`[out] ${join(OUT_DIR, 'narration.wav')}`);
+console.log(`[out] ${join(OUT_DIR, 'timeline.json')}`);
+console.log(`[out] ${join(OUT_DIR, 'timeline.js')}  (browser-loadable, ${segments.length} scene(s))`);

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

@@ -0,0 +1,73 @@
+// chromium.mjs — locate the Playwright headless-Chromium binary.
+//
+// The single source of truth for "where is the browser". Both the renderer
+// (render.mjs) and the scene-boot debugger (debug-page.mjs) import this, so the
+// platform/architecture logic lives in exactly one place (ROADMAP §2.1).
+//
+// Resolution order:
+//   1. CHROME_BIN                 — explicit binary path
+//   2. PLAYWRIGHT_BROWSERS_PATH   — explicit cache root
+//   3. the platform default cache root
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+
+const REVISION_PREFIX = 'chromium_headless_shell-';
+const BUILD_PREFIX = 'chrome-headless-shell-';
+
+function defaultCacheRoot() {
+  switch (process.platform) {
+    case 'darwin':
+      return join(os.homedir(), 'Library/Caches/ms-playwright');
+    case 'win32':
+      return join(process.env.LOCALAPPDATA || join(os.homedir(), 'AppData', 'Local'), 'ms-playwright');
+    default:
+      return join(process.env.XDG_CACHE_HOME || join(os.homedir(), '.cache'), 'ms-playwright');
+  }
+}
+
+export function findChromium() {
+  if (process.env.CHROME_BIN) {
+    if (!existsSync(process.env.CHROME_BIN)) {
+      throw new Error(`CHROME_BIN is set but not found: ${process.env.CHROME_BIN}`);
+    }
+    return process.env.CHROME_BIN;
+  }
+
+  const base = process.env.PLAYWRIGHT_BROWSERS_PATH || defaultCacheRoot();
+  if (!existsSync(base)) {
+    throw new Error(`Playwright cache not found at ${base} (set PLAYWRIGHT_BROWSERS_PATH or CHROME_BIN)`);
+  }
+
+  const revision = readdirSync(base)
+    .filter(d => d.startsWith(REVISION_PREFIX))
+    .sort()
+    .pop();
+  if (!revision) throw new Error(`No ${REVISION_PREFIX}* build found in ${base}`);
+
+  const revisionDir = join(base, revision);
+  // The binary sits one directory down, and that directory is named per
+  // platform+architecture (chrome-headless-shell-mac-arm64, ...-linux64, etc.).
+  // Globbing the prefix — rather than hardcoding the name — is what makes this
+  // portable instead of Apple-Silicon-only.
+  const build = readdirSync(revisionDir).find(d => d.startsWith(BUILD_PREFIX));
+  if (!build) throw new Error(`No ${BUILD_PREFIX}* directory found in ${revisionDir}`);
+
+  const binName = process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+  const bin = join(revisionDir, build, binName);
+  if (!existsSync(bin)) throw new Error(`Chromium binary not found at ${bin}`);
+  return bin;
+}
+
+/** findChromium, or print the one-time setup and exit — for the CLI entry points. */
+export function chromiumBinOrExit(tool) {
+  try {
+    return findChromium();
+  } catch (err) {
+    console.error(`[${tool}] headless Chromium not found:\n  ${err.message}`);
+    console.error('  One-time install: npx playwright install --with-deps --only-shell');
+    console.error('  Full setup: see SETUP.md (Node ≥ 22, ffmpeg, Chromium, Gemini key).');
+    process.exit(1);
+  }
+}

package/skills/explainer-video-from-coursework/tools/debug-page.mjs

@@ -0,0 +1,75 @@
+// Load a scene page in headless chromium and print any console output or
+// uncaught exceptions. A page that fails to boot reports as
+// "never exposed window.VIDEO_META", which tells you nothing about WHY.
+//
+//   node tools/debug-page.mjs src/scene-diagram.html
+
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { chromiumBinOrExit } from './chromium.mjs';
+import { requireNode } from './env.mjs';
+
+requireNode();
+
+const page = process.argv[2] || 'src/scene-diagram.html';
+const BIN = chromiumBinOrExit('debug-page');
+const PORT = 9444;
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+const proc = spawn(BIN, ['--headless', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+  '--allow-file-access-from-files', `--remote-debugging-port=${PORT}`, '--window-size=1920,1080',
+  'file://' + resolve(page)], { stdio: 'ignore' });
+
+try {
+  let target = null;
+  for (let i = 0; i < 40; 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('no page target');
+
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  let id = 0; const pending = new Map();
+  const logs = [];
+  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); return; }
+    if (m.method === 'Runtime.consoleAPICalled') {
+      logs.push(`console.${m.params.type}: ` + m.params.args.map(a => a.value ?? a.description ?? a.type).join(' '));
+    }
+    if (m.method === 'Runtime.exceptionThrown') {
+      const d = m.params.exceptionDetails;
+      logs.push(`EXCEPTION: ${d.exception?.description || d.text}`);
+    }
+    if (m.method === 'Log.entryAdded') logs.push(`log.${m.params.entry.level}: ${m.params.entry.text}`);
+  });
+  await new Promise((res, rej) => { ws.addEventListener('open', res, { once: true }); ws.addEventListener('error', rej, { once: true }); });
+  const send = (method, params = {}) => new Promise((res, rej) => {
+    const myId = ++id;
+    pending.set(myId, m => m.error ? rej(new Error(JSON.stringify(m.error))) : res(m.result));
+    ws.send(JSON.stringify({ id: myId, method, params }));
+  });
+
+  await send('Runtime.enable');
+  await send('Log.enable');
+  await send('Page.enable');
+  await send('Page.reload');           // reload so we capture boot-time errors
+  await sleep(2500);
+
+  const state = await send('Runtime.evaluate', {
+    expression: 'JSON.stringify({meta: !!window.VIDEO_META, scenes: typeof window.SceneCore, cfg: typeof window.SCENE_CONFIG, tl: typeof window.TIMELINE})',
+    returnByValue: true,
+  });
+  console.log('page state:', state.result.value);
+  console.log('\n--- console / errors ---');
+  console.log(logs.length ? logs.join('\n') : '(nothing captured)');
+  ws.close();
+} catch (e) {
+  console.error('[debug error]', e.message);
+} finally {
+  proc.kill();
+}

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

@@ -0,0 +1,30 @@
+// env.mjs — fail loud on missing prerequisites, instead of a raw ENOENT or a
+// cryptic WebSocket error. Each prerequisite maps to a SETUP.md section.
+//
+//   requireNode()   — the tools need Node ≥ 22 (global WebSocket / fetch)
+//   requireCmd(x)   — x must be on PATH (ffmpeg / ffprobe)
+
+import { spawnSync } from 'node:child_process';
+
+const NODE_MAJOR = 22;
+
+export function requireNode() {
+  const major = parseInt(process.versions.node.split('.')[0], 10);
+  if (major < NODE_MAJOR) {
+    console.error(`[node] Node ${process.versions.node} is too old — ${NODE_MAJOR}+ required (global WebSocket).`);
+    console.error('  See SETUP.md (Node ≥ 22).');
+    process.exit(1);
+  }
+}
+
+export function requireCmd(cmd) {
+  // spawnSync reports `error` only when the binary could not be launched (ENOENT
+  // = not on PATH). A non-zero exit still means it exists, so that is not an error
+  // here — `-version` exists precisely because some builds reject `--version`.
+  const r = spawnSync(cmd, ['-version'], { stdio: 'ignore' });
+  if (r.error) {
+    console.error(`[setup] ${cmd} not found on PATH.`);
+    console.error('  See SETUP.md (ffmpeg + ffprobe).');
+    process.exit(1);
+  }
+}