explainer-video 0.0.0-stage → 0.4.1

package/skills/explainer-video-from-coursework/tools/script-check.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/* =============================================================================
+   script-check.mjs — validate a narration script before it costs anything.
+
+   The script writer is the AGENT (judgment). This tool is CODE (exactness), and
+   it enforces the same discipline the planner does for coverage:
+
+     1. STRUCTURE   unique scene keys, non-empty narration, a style per segment
+     2. SPEAKABILITY no markdown, no URLs, no code syntax — this is read aloud
+     3. BUDGET      estimated narration + video duration vs the plan's target
+     4. COVERAGE    every source section the plan assigned must be narrated
+     5. PAUSES      code videos only, inert unless a segment carries `pause`:
+                    a pause prompt is spoken ("pause" in its text), dwells
+                    0 < dwell <= 2 s realised as an equal `pad`, and a video has
+                    at most 3; a fourth is an error that forces a split
+
+   Duration is ESTIMATED here, never trusted: the real number comes from measuring
+   the generated audio downstream.
+
+   Usage:
+     node tools/script-check.mjs --script out/<name>/scripts/NN-<slug>.json \
+                                 [--plan out/<name>/plan.enriched.json] [--max-min 25]
+   ========================================================================== */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { WPM as DEFAULT_WPM, EXPANSION as DEFAULT_EXPANSION, MAX_PAUSES } from './model.mjs';
+
+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);
+};
+
+/* same cost model as the planner, so the two are comparable */
+const WPM = parseFloat(flag('wpm', DEFAULT_WPM));
+const EXPANSION = parseFloat(flag('expansion', DEFAULT_EXPANSION));
+const MAX_MIN = parseFloat(flag('max-min', '25'));
+const MIN_FILL = parseFloat(flag('min-fill', '0.55'));   // script must reach 55% of target
+
+const scriptPath = flag('script');
+const planPath = flag('plan');
+if (!scriptPath) {
+  console.error('usage: node tools/script-check.mjs --script <script.json> [--plan plan.enriched.json]');
+  process.exit(1);
+}
+if (!existsSync(scriptPath)) { console.error('not found: ' + scriptPath); process.exit(1); }
+
+const script = JSON.parse(readFileSync(scriptPath, 'utf8'));
+const errors = [];
+const warnings = [];
+
+/* ---------------- helpers ---------------- */
+const words = s => String(s || '').split(/\s+/).filter(Boolean).length;
+const narrationMin = w => (w / WPM);
+const videoMin = w => (w / WPM) * EXPANSION;
+
+/* ---------------- 1. structure ---------------- */
+if (!script.videoIndex && script.videoIndex !== 0) errors.push('missing videoIndex');
+if (!script.title) errors.push('missing title');
+if (!Array.isArray(script.segments) || !script.segments.length) errors.push('no segments');
+
+const seen = new Set();
+(script.segments || []).forEach((s, i) => {
+  const at = `segment ${i + 1}${s.key ? ` (${s.key})` : ''}`;
+  if (!s.key) errors.push(`${at}: missing key`);
+  else if (seen.has(s.key)) errors.push(`${at}: duplicate key "${s.key}"`);
+  else seen.add(s.key);
+
+  if (!s.text || !String(s.text).trim()) errors.push(`${at}: empty narration`);
+  if (!s.style) warnings.push(`${at}: no style — TTS will fall back to a generic delivery`);
+  if (!s.visual) warnings.push(`${at}: no visual hint — the scene stage will have to guess`);
+  if (!Array.isArray(s.covers) || !s.covers.length) warnings.push(`${at}: does not declare what it covers`);
+});
+
+/* ---------------- 2. speakability ---------------- */
+(script.segments || []).forEach((s, i) => {
+  const t = String(s.text || '');
+  const at = `segment ${i + 1} (${s.key})`;
+  if (/https?:\/\//.test(t)) errors.push(`${at}: contains a URL — not speakable`);
+  if (/[*_`#>]|\|\s*-{2,}/.test(t)) errors.push(`${at}: contains markdown syntax`);
+  if (/[{}();=]|=>|\bdef \b|\bclass \w+\(/.test(t)) warnings.push(`${at}: looks like code in the narration`);
+  if (/\b[A-Z]{3,}\b/.test(t)) {
+    const acronyms = t.match(/\b[A-Z]{3,}\b/g);
+    if (acronyms) warnings.push(`${at}: acronym(s) ${[...new Set(acronyms)].join(', ')} — TTS may spell them out`);
+  }
+  if (words(t) > 130) warnings.push(`${at}: ${words(t)} words in one breath — consider splitting`);
+});
+
+/* ---------------- 5. pause prompts (active only when a segment carries `pause`) ----------------
+   Narration is the reading time: a code panel shows only the lines being narrated. A
+   pause prompt is the rare exception, for a block that must be read whole: the
+   narration says so out loud, a badge shows it, and the segment dwells at most 2 s
+   longer (realised as its `pad`). More than MAX_PAUSES means the video asks the
+   viewer to read silently too often: split it. */
+const pauses = (script.segments || []).filter(s => s.pause != null);
+let pauseDwell = 0;
+if (pauses.length) {
+  pauses.forEach(s => {
+    const at = `segment ${script.segments.indexOf(s) + 1} (${s.key})`;
+    const dwell = s.pause && typeof s.pause === 'object' ? s.pause.dwell : undefined;
+    if (!/\bpause\b/i.test(String(s.text || ''))) errors.push(`${at}: a pause segment's narration must say "pause" — the spoken prompt is what tells the viewer to stop and read`);
+    if (typeof dwell !== 'number' || !(dwell > 0 && dwell <= 2)) errors.push(`${at}: pause.dwell must be a number of seconds, 0 < dwell <= 2 (got ${JSON.stringify(dwell)})`);
+    else {
+      pauseDwell += dwell;
+      if (Number(s.pad) !== dwell) errors.push(`${at}: pause.dwell ${dwell}s is realised as the segment's pad, which is ${JSON.stringify(s.pad)} — set "pad": ${dwell}`);
+    }
+  });
+  if (pauses.length > MAX_PAUSES) errors.push(`${pauses.length} pause prompts (max ${MAX_PAUSES}) — a video that asks for that much silent reading must be split`);
+}
+
+/* ---------------- 3. budget ---------------- */
+const totalWords = (script.segments || []).reduce((a, s) => a + words(s.text), 0);
+const estNarr = narrationMin(totalWords);
+const estVideo = videoMin(totalWords) + pauseDwell / 60;
+const target = script.planTargetMinutes;
+
+if (estVideo > MAX_MIN) errors.push(`estimated ${estVideo.toFixed(1)} min exceeds the ${MAX_MIN} min cap`);
+if (target && estVideo < target * MIN_FILL) {
+  errors.push(`estimated ${estVideo.toFixed(1)} min is under ${(MIN_FILL * 100) | 0}% of the ${target} min target — content likely missing`);
+}
+if (target && estVideo > target * 1.25) {
+  warnings.push(`estimated ${estVideo.toFixed(1)} min is over 125% of the ${target} min target`);
+}
+
+/* ---------------- 4. coverage vs the plan ---------------- */
+let coverageLine = null;
+if (planPath && existsSync(planPath)) {
+  const plan = JSON.parse(readFileSync(planPath, 'utf8'));
+  /* The plan was split at its own recorded cap. If this run's cap disagrees, the plan
+     is from a different model generation — say so rather than silently allowing a
+     script far longer than the plan ever expected. */
+  const planCap = plan.model && plan.model.maxVideoMin;
+  if (planCap != null && Math.abs(planCap - MAX_MIN) > 1e-9) {
+    warnings.push(`plan was built with maxVideoMin=${planCap} but this check uses ${MAX_MIN} — the plan predates the current default (re-plan to change the split, which also reshuffles video indices)`);
+  }
+  const video = plan.videos.find(v => v.index === script.videoIndex);
+  if (!video) {
+    warnings.push(`video ${script.videoIndex} not found in the plan — skipping coverage check`);
+  } else {
+    const assigned = new Set(video.sections);
+    const covered = new Set((script.segments || []).flatMap(s => s.covers || []));
+    const missing = [...assigned].filter(x => !covered.has(x));
+    const extra = [...covered].filter(x => !assigned.has(x));
+    missing.forEach(m => errors.push(`UNCOVERED source section: ${m}`));
+    extra.forEach(x => warnings.push(`covers a section not assigned to this video: ${x}`));
+    coverageLine = `${covered.size}/${assigned.size} assigned sections covered`;
+  }
+}
+
+/* ---------------- report ---------------- */
+const name = basename(scriptPath);
+console.log(`\n${name}`);
+console.log('─'.repeat(Math.min(72, name.length + 20)));
+console.log(`  title        : ${script.title || '(none)'}`);
+console.log(`  form         : ${script.form || '(unset)'}`);
+console.log(`  segments     : ${(script.segments || []).length}`);
+console.log(`  words        : ${totalWords}`);
+console.log(`  narration    : ${estNarr.toFixed(1)} min  (at ${WPM} wpm)`);
+console.log(`  est. video   : ${estVideo.toFixed(1)} min  (×${EXPANSION} visual overhead)`);
+if (pauses.length) console.log(`  pauses       : ${pauses.length} prompt(s), ${pauseDwell.toFixed(1)}s of dwell (in est. video)`);
+if (target) console.log(`  plan target  : ${target} min  →  ${((estVideo / target) * 100).toFixed(0)}% of target`);
+if (coverageLine) console.log(`  coverage     : ${coverageLine}`);
+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}`));
+} else {
+  console.log('\n  ✓ script is valid');
+}
+process.exitCode = errors.length ? 2 : 0;

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

@@ -0,0 +1,71 @@
+/* =============================================================================
+   stamp.mjs — append one per-video stage timing row to out/<name>/timing.jsonl.
+
+   Usage:
+     node tools/stamp.mjs begin --out out/<name> --video <NN> --stage <n> [--note s]
+     node tools/stamp.mjs end   --out out/<name> --video <NN> --stage <n> [--note s]
+
+   A stage spans many turns and several processes, so its duration cannot be read
+   directly: `begin` writes a throwaway start marker, `end` reads it, subtracts,
+   appends one row, and deletes the marker. The marker never enters the ledger.
+
+   One row per attempt, in long format — the stage dimension lives in the `stage`
+   value, never in a column name — so stages can be added, renamed, or merged
+   without ever changing the file's shape.
+
+     { video, stage, attempt, seconds, ended_at, note }
+
+   `attempt` is 1-based and auto-increments: it counts the rows already recorded for
+   this (video, stage) and adds one, so a retry becomes attempt 2 with no bookkeeping.
+   ========================================================================== */
+
+import { mkdirSync, readFileSync, writeFileSync, appendFileSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (n, d) => { const i = argv.indexOf('--' + n); return i === -1 ? d : argv[i + 1]; };
+
+const STAGES = new Set(['3', '4', '4b', '5', '6', '6b', '7', '8']);
+const outDir = flag('out');
+const video = flag('video');
+const stage = flag('stage');
+const note = flag('note', null);
+
+const die = (msg) => { console.error('[stamp] ' + msg); process.exit(1); };
+
+if (!cmd || !['begin', 'end'].includes(cmd))
+  die('usage: stamp.mjs <begin|end> --out <seriesDir> --video <NN> --stage <n> [--note s]');
+if (!outDir) die('missing --out <seriesDir>');
+if (!video) die('missing --video <NN> (the bare plan index)');
+if (!stage || !STAGES.has(stage)) die(`--stage must be one of ${[...STAGES].join(', ')}`);
+
+mkdirSync(outDir, { recursive: true });
+const stampsDir = join(outDir, '.stamps');
+const marker = join(stampsDir, `${video}.${stage}.start`);
+const ledger = join(outDir, 'timing.jsonl');
+
+if (cmd === 'begin') {
+  mkdirSync(stampsDir, { recursive: true });
+  if (existsSync(marker))
+    console.error(`[stamp] overwriting an existing start marker for video ${video} stage ${stage} — did a previous \`end\` never run?`);
+  writeFileSync(marker, String(Date.now()));
+  console.log(`[stamp] begin video ${video} stage ${stage}`);
+} else {
+  if (!existsSync(marker))
+    die(`no start marker for video ${video} stage ${stage} — run \`begin\` first`);
+  const startMs = Number(readFileSync(marker, 'utf8').trim());
+  const seconds = Math.round((Date.now() - startMs) / 100) / 10; // one decimal
+  let attempt = 1;
+  if (existsSync(ledger)) {
+    const prior = readFileSync(ledger, 'utf8').split('\n').filter(Boolean);
+    attempt = prior.reduce((n, line) => {
+      try { const r = JSON.parse(line); return (r.video === video && r.stage === stage) ? n + 1 : n; }
+      catch { return n; }
+    }, 0) + 1;
+  }
+  const row = { video, stage, attempt, seconds, ended_at: new Date().toISOString(), note };
+  appendFileSync(ledger, JSON.stringify(row) + '\n');
+  unlinkSync(marker);
+  console.log(`[stamp] video ${video} stage ${stage} attempt ${attempt} = ${seconds}s`);
+}

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/* =============================================================================
+   thumbnail.mjs — /thumbnail stage (stage 6b): the upload thumbnail.
+
+   The agent writes out/<name>/<NN>/thumbnail.json (the hook, a still from its own
+   stage-5 scenes, an optional crop, accent and badge); this tool adds the series label,
+   photographs src/thumbnail.html at 1280x720 with the headless Chromium, checks the PNG,
+   and copies it into the video's destination folder beside title.txt:
+
+       --dest/<NN>-<slug>/thumbnail.png   — what upload_yt_video picks up
+
+   The series label reads "<playlist>-Part <X>, <upload title>". The playlist name only
+   ever comes from the user (--playlist); a plan of more than one video with neither
+   --playlist nor --standalone is refused with exit 3, so the agent asks instead of
+   inventing one. Part X is the video's 1-based position in plan.enriched.json's
+   `videos` list (after curation's skips and merges), not its raw videoIndex.
+
+   Usage:
+     node tools/thumbnail.mjs --work out/<name>/<NN> --script out/<name>/scripts/<NN>-*.json \
+                              --plan out/<name>/plan.enriched.json --dest <destination> \
+                              [--playlist "<name>" | --standalone]
+
+   Exit: 0 written · 1 a missing input or prerequisite · 2 the config
+   or the PNG fails a check · 3 a series with no playlist decision (ask the user).
+   ========================================================================== */
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { chromiumBinOrExit } from './chromium.mjs';
+import { videoDir } from './naming.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const WIDTH = 1280;
+export const HEIGHT = 720;
+// upload_yt_video refuses a thumbnail over 2 MB; the decimal reading is the stricter one
+export const MAX_BYTES = 2_000_000;
+
+/* ---------------- the PNG ---------------- */
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// width and height from the IHDR chunk, or null for anything that is not a PNG
+export function pngInfo(buf) {
+  if (buf.length < 24 || !buf.subarray(0, 8).equals(PNG_SIG) || buf.toString('latin1', 12, 16) !== 'IHDR') return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+// every way the file fails what the upload tool and YouTube accept
+export function checkThumbnail(buf) {
+  const problems = [];
+  const info = pngInfo(buf);
+  if (!info) problems.push(/^\xff\xd8\xff/.test(buf.toString('latin1', 0, 3))
+    ? 'it is a JPEG named as a PNG: write a real PNG'
+    : 'not a PNG (no PNG signature and IHDR chunk)');
+  else if (info.width !== WIDTH || info.height !== HEIGHT) problems.push(`it is ${info.width}x${info.height}; a thumbnail is ${WIDTH}x${HEIGHT}`);
+  if (buf.length > MAX_BYTES) problems.push(`it is ${buf.length.toLocaleString('en-US')} bytes; the upload refuses more than ${MAX_BYTES.toLocaleString('en-US')}`);
+  return problems;
+}
+
+/* ---------------- the series label ---------------- */
+// the video's place in the series as produced: its 1-based position among the plan's surviving videos
+export function partOf(plan, videoIndex) {
+  const videos = (plan && plan.videos) || [];
+  const at = videos.findIndex((v) => Number(v.index) === Number(videoIndex));
+  return at === -1 ? null : { part: at + 1, of: videos.length };
+}
+
+export const seriesLabel = (playlist, part, title) => `${playlist}-Part ${part}, ${title}`;
+
+/* ---------------- the config ---------------- */
+const norm = (s) => String(s).toLowerCase().replace(/[^a-z0-9' ]+/g, ' ').replace(/\s+/g, ' ').trim();
+const words = (s) => norm(s).split(' ').filter(Boolean);
+const STOP = new Set(['a', 'an', 'the', 'of', 'to', 'in', 'on', 'and', 'or', 'is', 'it', 'for', 'how', 'why', 'what', 'your', 'you']);
+
+// one hook word as the template compares it: case and punctuation dropped, so "Zero-copy" and "zero-copy!" are one word
+const wordKey = (w) => String(w).toLowerCase().replace(/[^\p{L}\p{N}']/gu, '');
+
+// the positions of the hook's whitespace-separated words that a highlight names; the template colours exactly these
+export function markedWords(hook, highlight) {
+  const keys = new Set([].concat(highlight || []).map(wordKey).filter(Boolean));
+  return hook.split(' ').flatMap((w, i) => (keys.has(wordKey(w)) ? [i] : []));
+}
+
+// a hook word that is code, not the viewer's terms: a path, an identifier, a module path or a call
+const CODE = [
+  (w) => /^\.{1,2}\//.test(w),
+  (w) => w.includes('/') && w.split('/').some((s) => /^[\w-]+\.[A-Za-z][A-Za-z0-9]{0,4}$/.test(s)),
+  (w) => /[A-Za-z_][\w-]*(\/[A-Za-z_][\w-]*){2,}/.test(w),
+  (w) => /^[a-z][a-z0-9]+[A-Z][a-z]/.test(w),
+  (w) => /[A-Za-z0-9]_[A-Za-z0-9]/.test(w),
+  (w) => /^[a-z_]\w*(\.[A-Za-z_]\w*){2,}/.test(w),
+  (w) => /\w::\w/.test(w),
+  (w) => /\w\(\)/.test(w),
+];
+export const codeWords = (hook) => hook.split(' ')
+  .filter((w) => { const bare = w.replace(/^[^\w./]+/, '').replace(/[^\w)]+$/, ''); return CODE.some((is) => is(bare)); });
+
+// { errors, warnings } for thumbnail.json against the upload title; `codebase` adds the code-flow rule
+export function checkConfig(cfg, { title = '', codebase = false } = {}) {
+  const errors = [];
+  const warnings = [];
+  const hook = typeof cfg.hook === 'string' ? cfg.hook.replace(/\s+/g, ' ').trim() : '';
+  if (!hook) errors.push('"hook" is missing: a few big words that make a viewer want the answer');
+  else {
+    const n = hook.split(' ').length;
+    if (n > 5) errors.push(`"hook" is ${n} words; at most 5 read at phone size`);
+    if (hook.length > 32) errors.push(`"hook" is ${hook.length} characters; at most 32 read at phone size`);
+    const h = norm(hook), t = norm(title);
+    if (t && (h === t || ` ${t} `.includes(` ${h} `))) errors.push(`"hook" repeats the upload title ("${title}"); it must add to it, not echo it`);
+    else if (t) {
+      const own = words(hook).filter((w) => !STOP.has(w));
+      const shared = own.filter((w) => words(title).includes(w));
+      if (own.length && shared.length / own.length > 0.5) warnings.push(`"hook" shares most of its words with the upload title (${shared.join(', ')}); a hook that complements the title earns the click`);
+    }
+    if (codebase) {
+      const code = codeWords(hook);
+      if (code.length) errors.push(`"hook" names code (${code.join(', ')}); a code-flow hook names the flow in the viewer's terms, never a module path or an identifier`);
+    }
+    for (const w of [].concat(cfg.highlight || [])) {
+      if (!markedWords(hook, w).length) errors.push(`"highlight" word "${w}" is not in the hook`);
+    }
+  }
+  if (cfg.highlight != null && !Array.isArray(cfg.highlight) && typeof cfg.highlight !== 'string') errors.push('"highlight" is a word of the hook or a list of them');
+  if (typeof cfg.still !== 'string' || !cfg.still.trim()) errors.push('"still" is missing: a PNG rendered from one of this video\'s own stage-5 scenes');
+  if (cfg.focus != null) {
+    const { x = 0.5, y = 0.5, zoom = 1 } = cfg.focus;
+    if (![x, y].every((v) => typeof v === 'number' && v >= 0 && v <= 1)) errors.push('"focus" x and y are fractions of the still, 0 to 1');
+    if (typeof zoom !== 'number' || zoom < 1 || zoom > 4) errors.push('"focus" zoom is 1 to 4');
+  }
+  if (cfg.accent != null && !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(String(cfg.accent))) errors.push('"accent" is a hex colour such as "#FFD400"');
+  if (cfg.badge != null && (typeof cfg.badge !== 'string' || !cfg.badge.trim() || cfg.badge.length > 16)) errors.push('"badge" is a short sticker, 1 to 16 characters');
+  return { errors, warnings };
+}
+
+/* ---------------- CLI ---------------- */
+function main(argv) {
+  const has = (n) => argv.includes('--' + n);
+  const flag = (n) => { const i = argv.indexOf('--' + n); return i === -1 ? undefined : argv[i + 1]; };
+  const die = (code, msg) => { console.error(`[thumbnail] ${msg}`); process.exit(code); };
+  const readJson = (p, what) => {
+    if (!existsSync(p)) die(1, `no ${what} at ${p}`);
+    try { return JSON.parse(readFileSync(p, 'utf8')); } catch (e) { die(1, `${what} at ${p} is not JSON: ${e.message}`); }
+  };
+  const report = (file, problems) => {
+    if (problems.length) {
+      console.error(`[thumbnail] ✗ ${file}`);
+      for (const p of problems) console.error(`     - ${p}`);
+      process.exit(2);
+    }
+  };
+
+  const WORK = flag('work'), SCRIPT = flag('script'), PLAN = flag('plan'), DEST = flag('dest');
+  if (!WORK || !SCRIPT || !PLAN || !DEST)
+    die(1, 'usage: thumbnail.mjs --work <work-dir> --script <script.json> --plan <plan.enriched.json> --dest <dir> [--playlist "<name>" | --standalone]');
+  const workDir = resolve(WORK);
+  const script = readJson(resolve(SCRIPT), 'script');
+  const plan = readJson(resolve(PLAN), 'enriched plan');
+  const cfg = readJson(join(workDir, 'thumbnail.json'), 'thumbnail.json (write it first: hook + still)');
+
+  const where = partOf(plan, script.videoIndex);
+  if (!where) die(1, `video ${script.videoIndex} is not in ${PLAN}: pass the enriched plan, which lists the videos curation kept`);
+
+  const destDir = join(resolve(DEST), videoDir(script, basename(workDir)));
+  const titleFile = join(destDir, 'title.txt');
+  if (!existsSync(titleFile)) die(1, `no title.txt at ${titleFile}: run /publish (stage 6) first, the thumbnail needs the final upload title`);
+  const title = readFileSync(titleFile, 'utf8').trim();
+
+  /* The playlist name is the user's, never ours: no default, no guess. */
+  const playlist = flag('playlist');
+  if (playlist !== undefined && has('standalone')) die(1, 'pass --playlist or --standalone, not both');
+  if (playlist !== undefined && !String(playlist).trim()) die(1, '--playlist is empty: pass the user\'s playlist name, --standalone if they said there is none, or neither flag to be asked');
+  if (playlist === undefined && !has('standalone') && where.of > 1)
+    die(3, `this plan has ${where.of} videos, so video ${script.videoIndex} looks like part of a series, and no playlist name was given. ` +
+      'Ask the user for the playlist name (or whether it is standalone), then re-run with --playlist "<name>" or --standalone. Never invent one.');
+  const label = playlist === undefined ? null : seriesLabel(String(playlist).trim(), where.part, title);
+
+  const { errors, warnings } = checkConfig(cfg, { title, codebase: plan.kind === 'codebase' });
+  const stillPath = typeof cfg.still === 'string' ? (isAbsolute(cfg.still) ? cfg.still : join(workDir, cfg.still)) : null;
+  if (stillPath && !existsSync(stillPath)) errors.push(`"still" ${cfg.still} does not exist (paths are relative to ${workDir})`);
+  for (const w of warnings) console.log(`  ⚠ ${w}`);
+  report(join(workDir, 'thumbnail.json'), errors);
+
+  /* Photograph the host: everything is laid out before the load event, so --screenshot never races it. */
+  const bin = chromiumBinOrExit('thumbnail');
+  const hook = cfg.hook.replace(/\s+/g, ' ').trim();
+  const config = {
+    hook,
+    marked: markedWords(hook, cfg.highlight),
+    label,
+    still: pathToFileURL(stillPath).href,
+    focus: cfg.focus || null,
+    accent: cfg.accent || null,
+    badge: cfg.badge ? cfg.badge.trim() : null,
+  };
+  const url = pathToFileURL(join(ROOT, 'src', 'thumbnail.html')).href + '?c=' + encodeURIComponent(JSON.stringify(config));
+  const out = join(workDir, 'thumbnail.png');
+  rmSync(out, { force: true });
+  const shot = spawnSync(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',
+    `--window-size=${WIDTH},${HEIGHT}`, `--screenshot=${out}`, url], { encoding: 'utf8', timeout: 60_000 });
+  if (!existsSync(out)) die(1, `Chromium wrote no screenshot (exit ${shot.status}${shot.error ? `, ${shot.error.message}` : ''})\n${(shot.stderr || '').trim().split('\n').slice(-5).join('\n')}`);
+  report(out, checkThumbnail(readFileSync(out)));
+
+  /* The phone-size look: YouTube's mobile lists show a thumbnail a few hundred pixels wide. */
+  const small = join(workDir, 'thumbnail.small.png');
+  const scaled = spawnSync('ffmpeg', ['-y', '-v', 'error', '-i', out, '-vf', 'scale=320:180', small], { encoding: 'utf8' });
+  if (scaled.error || scaled.status !== 0) console.log(`  ⚠ no phone-size preview (ffmpeg ${scaled.error ? 'not found' : 'failed'}); look at the full PNG at a small zoom instead`);
+
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(out, join(destDir, 'thumbnail.png'));
+  for (const other of ['thumbnail.jpg', 'thumbnail.jpeg']) {
+    if (existsSync(join(destDir, other))) console.log(`  ⚠ ${join(destDir, other)} is also there; the upload may pick it instead of thumbnail.png, so remove it`);
+  }
+  console.log(`  hook     : "${config.hook}"`);
+  console.log(`  label    : ${label ? `"${label}"` : '— (standalone video)'}`);
+  console.log(`  still    : ${stillPath}`);
+  console.log(`\n[out] ${out}`);
+  if (existsSync(small)) console.log(`[out] ${small}`);
+  console.log(`[dest] ${join(destDir, 'thumbnail.png')}`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));