explainer-video 0.0.0-stage → 0.4.0

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', '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/timing-report.mjs

@@ -0,0 +1,299 @@
+/* =============================================================================
+   timing-report.mjs — render out/<name>/timing.jsonl into four human-readable views.
+
+   Usage:
+     node tools/timing-report.mjs --out out/<name> [--flat]
+
+   Reads the append-only ledger (one row per attempt) plus the enriched plan for
+   titles, then writes:
+
+     out/<name>/timing.csv   — long format, one row per attempt:
+        video_title, stage, attempt, seconds, ended_at, note
+     out/<name>/timing.md    — one heading per video title, a stage -> seconds table
+                               (attempts summed) with a total.
+     out/<name>/timing.svg   — static stacked bars (no-JS fallback; opens anywhere).
+     out/<name>/timing.html  — interactive Plotly chart, self-contained and offline:
+                               the vendored bundle and src/timing-chart.js are inlined.
+
+   Grouping — the plan already groups videos by module (the first path segment of a
+   video's first source), so a series of 85 videos is really ~17 modules. When the
+   ledger spans more than one module the HTML and SVG show one aggregate bar per
+   module and (HTML only) drill into a module's videos on click; with a single module
+   grouping would be a pointless extra click, so both render every video instead.
+   `--flat` forces the per-video chart regardless.
+
+   All four outputs are derived and regenerable; the ledger is the only source of
+   truth. The stage dimension is a *value*, never a column or a hardcoded colour, so
+   adding/removing/merging stages changes the legend — not the drawing code.
+   ========================================================================== */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => { const i = argv.indexOf('--' + n); return i === -1 ? d : argv[i + 1]; };
+const outDir = flag('out');
+if (!outDir) { console.error('usage: node tools/timing-report.mjs --out <seriesDir> [--flat]'); process.exit(1); }
+const forceFlat = argv.includes('--flat');
+
+const ledgerPath = join(outDir, 'timing.jsonl');
+const planPath = join(outDir, 'plan.enriched.json');
+const here = dirname(fileURLToPath(import.meta.url));
+
+const rows = existsSync(ledgerPath)
+  ? readFileSync(ledgerPath, 'utf8').split('\n').filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean)
+  : [];
+
+const titles = {};
+const planModule = {};
+if (existsSync(planPath)) {
+  try {
+    const plan = JSON.parse(readFileSync(planPath, 'utf8'));
+    for (const v of (plan.videos || [])) {
+      if (v.index == null) continue;
+      titles[String(v.index)] = v.title;
+      planModule[String(v.index)] = v.group || ((v.sources && v.sources[0]) || '').split('/')[0];   // a code-flow plan groups by flow
+    }
+  } catch { /* plan unreadable — fall back to the raw key and a single module */ }
+}
+const titleOf = (video) => titles[video] || video;
+const round1 = (n) => String(Math.round(n * 10) / 10);
+const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;')
+  .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const fmtDur = (n) => n < 60 ? `${round1(n)}s` : `${Math.floor(n / 60)}m${Math.round(n % 60)}s`;
+
+const STAGE_NAMES = { '3': 'script', '4': 'audio', '4b': 'align', '5': 'scene', '6': 'publish', '7': 'render', '8': 'assemble' };
+const PALETTE = ['#4f46e5', '#0ea5e9', '#14b8a6', '#f59e0b', '#ef4444', '#8b5cf6',
+                 '#ec4899', '#10b981', '#f97316', '#6366f1', '#a855f7', '#22c55e'];
+
+/* Module display names: "09-tool-platforms-mcp" → "Tool Platforms MCP". */
+const ACRONYM = { mcp: 'MCP', llm: 'LLM', llms: 'LLMs', llmops: 'LLMOps', adk: 'ADK', api: 'API', rag: 'RAG', gcp: 'GCP', ui: 'UI' };
+const displayName = (mod) => {
+  const s = String(mod || '').replace(/^\d+[-_]/, '');
+  if (!s) return '(ungrouped)';
+  return s.split(/[-_]/).filter(Boolean)
+    .map((w) => ACRONYM[w.toLowerCase()] || (w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(' ');
+};
+
+const order = [...new Set(rows.map((r) => r.video))];
+order.sort((a, b) => {
+  const na = parseInt(a, 10), nb = parseInt(b, 10);
+  if (!Number.isNaN(na) && !Number.isNaN(nb)) return na - nb;
+  return a < b ? -1 : a > b ? 1 : 0;
+});
+
+/* Per video: its stages (attempts summed), total, and plan index. */
+const vids = order.map((video) => {
+  const byStage = new Map();
+  for (const r of rows) {
+    if (r.video !== video) continue;
+    const e = byStage.get(r.stage) || { s: 0, n: 0 };
+    e.s += r.seconds; e.n += 1; byStage.set(r.stage, e);
+  }
+  const stages = [...byStage.entries()].map(([st, e]) => [st, e.s, e.n]);
+  return {
+    video, index: parseInt(video, 10),
+    title: titleOf(video),
+    stages,
+    total: stages.reduce((a, [, s]) => a + s, 0),
+  };
+});
+
+/* Stage order across the whole ledger (first-seen = pipeline order). */
+const stageOrder = [];
+for (const v of vids) for (const [st] of v.stages) if (!stageOrder.includes(st)) stageOrder.push(st);
+const colorOf = new Map(stageOrder.map((st, i) => [st, PALETTE[i % PALETTE.length]]));
+const stageLabel = (st) => STAGE_NAMES[st] ? `${st} · ${STAGE_NAMES[st]}` : st;
+
+/* Group by module. A video with no plan entry lands in '(ungrouped)'. */
+const byModule = new Map();
+for (const v of vids) {
+  const mod = planModule[v.video] || '';
+  if (!byModule.has(mod)) byModule.set(mod, []);
+  byModule.get(mod).push(v);
+}
+const modules = [...byModule.entries()]
+  .sort((a, b) => a[0].localeCompare(b[0], undefined, { numeric: true }))
+  .map(([name, videos]) => ({ name, display: displayName(name), videos }));
+
+const mode = (forceFlat || modules.length <= 1) ? 'flat' : 'grouped';
+const maxTotal = Math.max(1, ...vids.map((v) => v.total));
+
+/* ---- CSV (long format) ---- */
+const csvField = (s) => {
+  s = s == null ? '' : String(s);
+  return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+};
+let csv = 'video_title,stage,attempt,seconds,ended_at,note\n';
+for (const r of rows) {
+  csv += [titleOf(r.video), r.stage, r.attempt, r.seconds, r.ended_at, r.note ?? '']
+    .map(csvField).join(',') + '\n';
+}
+writeFileSync(join(outDir, 'timing.csv'), csv);
+
+/* ---- MD (grouped by video) ---- */
+let md = '# Timing audit\n\n';
+if (!rows.length) md += '_No timing rows yet — run stages 3–8 and stamp them._\n';
+for (const v of vids) {
+  md += `## ${v.title}\n\n| stage | seconds | attempts |\n| --- | --- | --- |\n`;
+  let total = 0;
+  for (const [s, e, n] of v.stages) { md += `| ${s} | ${round1(e)} | ${n} |\n`; total += e; }
+  md += `| **total** | **${round1(total)}** | |\n\n`;
+}
+writeFileSync(join(outDir, 'timing.md'), md);
+
+/* ---- SVG (static stacked bars, no-JS fallback) ---- */
+function stageTotals(videos) {
+  const byStage = new Map();
+  for (const v of videos) {
+    for (const [st, sec, n] of v.stages) {
+      const e = byStage.get(st) || { s: 0, n: 0 };
+      e.s += sec; e.n += n; byStage.set(st, e);
+    }
+  }
+  const stages = [...byStage.entries()].map(([st, e]) => [st, e.s, e.n]);
+  return { stages, total: stages.reduce((a, [, s]) => a + s, 0) };
+}
+
+function buildSvg(list, title) {
+  const L = 20, LABEL = 360, GAP = 12, CHART = 560, RAXIS = 64, R = 16;
+  const WIDTH = L + LABEL + GAP + CHART + RAXIS + R;
+  const ROW = 26, ROWGAP = 10;
+  const TITLE_H = 30, LEGEND_H = 22, AXIS_H = 26;
+  const max = Math.max(1, ...list.map((x) => x.total));
+
+  let legendLines = 1, lx = 0;
+  for (const st of stageOrder) {
+    const w = 16 + 6 + stageLabel(st).length * 7.2;
+    if (lx + w > WIDTH - L - R && lx > 0) { legendLines++; lx = 0; }
+    lx += w + 16;
+  }
+
+  const top = 20;
+  const legendTop = top + TITLE_H + 6;
+  const chartTop = legendTop + legendLines * LEGEND_H + 14;
+  const rowsTop = chartTop + 8;
+  const axisTop = rowsTop + list.length * (ROW + ROWGAP);
+  const HEIGHT = axisTop + AXIS_H + 16;
+  const chartX = L + LABEL + GAP;
+
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" `
+    + `viewBox="0 0 ${WIDTH} ${HEIGHT}" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif">`);
+  p.push(`<rect width="100%" height="100%" fill="#ffffff"/>`);
+  p.push(`<text x="${L}" y="${top + 18}" font-size="18" font-weight="600" fill="#111827">${esc(title)}</text>`);
+
+  if (!list.length) {
+    p.push(`<text x="${L}" y="${chartTop + 24}" font-size="14" fill="#6b7280">No timing rows yet.</text>`);
+    p.push('</svg>');
+    return p.join('\n');
+  }
+
+  lx = L; let ly = legendTop;
+  for (const st of stageOrder) {
+    const w = 16 + 6 + stageLabel(st).length * 7.2;
+    if (lx + w > WIDTH - R && lx > L) { lx = L; ly += LEGEND_H; }
+    p.push(`<rect x="${lx}" y="${ly}" width="14" height="14" rx="3" fill="${colorOf.get(st)}"/>`);
+    p.push(`<text x="${lx + 20}" y="${ly + 11}" font-size="12" fill="#374151">${esc(stageLabel(st))}</text>`);
+    lx += w + 16;
+  }
+
+  const ticks = 5;
+  for (let i = 0; i <= ticks; i++) {
+    const gx = chartX + CHART * i / ticks;
+    p.push(`<line x1="${gx}" y1="${rowsTop - 8}" x2="${gx}" y2="${axisTop - AXIS_H}" stroke="#e5e7eb"/>`);
+    const anchor = i === 0 ? 'start' : i === ticks ? 'end' : 'middle';
+    p.push(`<text x="${gx}" y="${axisTop}" font-size="11" fill="#6b7280" text-anchor="${anchor}">`
+      + `${fmtDur(max * i / ticks)}</text>`);
+  }
+
+  list.forEach((v, i) => {
+    const y = rowsTop + i * (ROW + ROWGAP);
+    const label = v.title.length > 52 ? v.title.slice(0, 51) + '…' : v.title;
+    p.push(`<text x="${L}" y="${y + ROW / 2 + 4}" font-size="12" fill="#111827">${esc(label)}</text>`);
+    let bx = chartX;
+    for (const [st, sec, attempts] of v.stages) {
+      const w = (sec / max) * CHART;
+      const tip = `${esc(v.title)} — ${esc(stageLabel(st))}: ${round1(sec)}s${attempts > 1 ? ' (' + attempts + ' attempts)' : ''}`;
+      p.push(`<rect x="${bx}" y="${y}" width="${w}" height="${ROW}" rx="2" fill="${colorOf.get(st)}">`
+        + `<title>${tip}</title></rect>`);
+      bx += w;
+    }
+    p.push(`<text x="${chartX + (v.total / max) * CHART + 8}" y="${y + ROW / 2 + 4}" `
+      + `font-size="11" fill="#374151">${fmtDur(v.total)}</text>`);
+  });
+
+  p.push('</svg>');
+  return p.join('\n');
+}
+
+const svgList = mode === 'grouped'
+  ? modules.map((m) => ({ title: m.display, ...stageTotals(m.videos) }))
+  : vids.map((v) => ({ title: v.title, stages: v.stages, total: v.total }));
+const svgTitle = mode === 'grouped' ? 'Time per module, by stage' : 'Time per video, by stage';
+writeFileSync(join(outDir, 'timing.svg'), buildSvg(svgList, svgTitle));
+
+/* ---- HTML (interactive Plotly, self-contained + offline) ---- */
+function buildHtml() {
+  if (!vids.length) {
+    return '<!doctype html><html><head><meta charset="utf-8"></head>'
+      + '<body style="font-family:system-ui,sans-serif"><p>No timing rows yet.</p></body></html>';
+  }
+  const vendor = readFileSync(join(here, '..', 'vendor', 'plotly-basic.min.js'), 'utf8');
+  const chartJs = readFileSync(join(here, '..', 'src', 'timing-chart.js'), 'utf8');
+
+  const htmlModules = modules.map((m) => ({
+    name: m.name,
+    display: m.display,
+    videos: m.videos.map((v) => ({
+      index: v.index,
+      title: v.title,
+      stages: Object.fromEntries(v.stages.map(([st, sec]) => [st, sec])),
+    })),
+  }));
+  // escaping "</" keeps a title containing "</script>" from closing the tag
+  const data = JSON.stringify({ mode, stages: stageOrder.map((k) => [k, STAGE_NAMES[k] || '']), modules: htmlModules })
+    .replace(/<\//g, '<\\/');
+
+  const body = mode === 'grouped'
+    ? `<h1>Time per module</h1>
+<div id="timing-chart"></div>
+<p class="hint">Click a module bar to break it down by video.</p>
+<div id="timing-detail-wrap" hidden>
+  <h2 id="timing-detail-title"></h2>
+  <p class="hint"><a href="#" id="all-modules">&uarr; all modules</a></p>
+  <div id="timing-detail"></div>
+</div>`
+    : `<h1>Time per video, by stage</h1>
+<div id="timing-chart"></div>`;
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>timing audit</title>
+<style>
+  body { margin:0; padding:0 16px 40px; background:#fff; color:#111827;
+         font-family:system-ui,-apple-system,'Segoe UI',sans-serif; }
+  #timing-chart, #timing-detail { width:100%; }
+  h1 { font-size:17px; font-weight:600; margin:14px 0 0; }
+  h2 { font-size:15px; font-weight:600; margin:22px 0 0; }
+  .hint { font-size:11px; color:#6b7280; margin:6px 0 0; }
+  .hint a { color:#4f46e5; text-decoration:none; }
+  .hint a:hover { text-decoration:underline; }
+</style>
+</head><body>
+${body}
+<script>${vendor}</script>
+<script>window.TIMING_DATA = ${data};</script>
+<script>${chartJs}</script>
+</body></html>`;
+}
+writeFileSync(join(outDir, 'timing.html'), buildHtml());
+
+console.log(`[timing] ${rows.length} row(s) · ${order.length} video(s) · ${modules.length} module(s) · ${mode}`);
+console.log(`[out] ${join(outDir, 'timing.csv')}`);
+console.log(`[out] ${join(outDir, 'timing.md')}`);
+console.log(`[out] ${join(outDir, 'timing.svg')}`);
+console.log(`[out] ${join(outDir, 'timing.html')}`);

package/skills/explainer-video-from-coursework/tools/transcribe-gemini.mjs

@@ -0,0 +1,96 @@
+/* =============================================================================
+   transcribe-gemini.mjs — word-level timings for a narration WAV.
+
+   Gemini's TTS models return audio only (verified: the response has no timing
+   fields at all). But `gemini-3.5-transcribe` can return per-word offsets when
+   asked for them — the flag is `wordTimestamp`, which the API discovery schema
+   documents but the prose docs never show in an example:
+
+       generationConfig.audioTranscriptionConfig.wordTimestamp = true
+       -> candidates[0].content.parts[0].audioTranscription.words[]
+          { word, startOffset: "3.900s", endOffset: "4.100s" }
+
+   Two things this module deliberately does NOT do:
+     • customVocabulary — the API rejects it together with wordTimestamp.
+     • trust the transcript as text. It applies inverse text normalisation
+       ("forty" -> "40") and rewrites punctuation, so callers must align the
+       returned words back onto their own known text. See align.mjs.
+
+   Audio is sent inline (base64) — no Files API upload, one request per segment.
+   ========================================================================== */
+
+import { readFileSync } from 'node:fs';
+import { loadKey, scrub } from './key-source.mjs';
+
+const API = 'https://generativelanguage.googleapis.com/v1beta';
+export const MODEL = 'gemini-3.5-transcribe';
+
+/** "12.600s" | "1.5s" -> 12.6 | 1.5 (null when absent/unparseable) */
+export function parseOffset(d) {
+  if (typeof d === 'number') return d;
+  const m = /^(-?\d+(?:\.\d+)?)s$/.exec(String(d ?? '').trim());
+  return m ? parseFloat(m[1]) : null;
+}
+
+/**
+ * Transcribe one WAV, returning word records with float offsets in seconds.
+ *
+ * @param {{wavPath:string, key?:string, languageCode?:string, retries?:number}} opts
+ * @returns {Promise<{text:string, words:Array<{w:string,s:number,e:number}>, model:string}>}
+ */
+export async function transcribeWords({ wavPath, key, languageCode = 'en-US', retries = 3 }) {
+  const apiKey = key || loadKey().key;
+  if (!apiKey) throw new Error('No API key found — see key-source.mjs for the store command.');
+
+  const b64 = readFileSync(wavPath).toString('base64');
+  const body = {
+    contents: [{ parts: [{ inlineData: { mimeType: 'audio/wav', data: b64 } }] }],
+    generationConfig: {
+      audioTranscriptionConfig: { languageCodes: [languageCode], wordTimestamp: true },
+    },
+  };
+
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetch(`${API}/models/${MODEL}:generateContent`, {
+      method: 'POST',
+      headers: { 'x-goog-api-key': apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+
+    if (res.status === 429 && attempt < retries) {
+      await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
+      continue;
+    }
+    if (!res.ok) {
+      let msg = text.slice(0, 300);
+      try { msg = JSON.parse(text).error?.message || msg; } catch {}
+      throw new Error(`transcribe failed ${res.status}: ${scrub(msg)}`);
+    }
+
+    let json;
+    try { json = JSON.parse(text); } catch { throw new Error('transcribe returned non-JSON'); }
+    const part = json.candidates?.[0]?.content?.parts?.[0] || {};
+    const at = part.audioTranscription;
+    if (!at) {
+      throw new Error(
+        'transcribe returned no audioTranscription block — the model may have refused this audio.\n' +
+        `  parts: ${JSON.stringify(Object.keys(part))}`
+      );
+    }
+
+    const words = (at.words || []).map(w => ({
+      w: String(w.word ?? ''),
+      s: parseOffset(w.startOffset),
+      e: parseOffset(w.endOffset),
+    })).filter(w => w.s != null && w.e != null);
+
+    if (!words.length) {
+      throw new Error(
+        'transcribe returned words[] empty — wordTimestamp was set but no offsets came back.\n' +
+        '  Refusing to write a timing-less alignment (silent desync is worse than a hard failure).'
+      );
+    }
+    return { text: String(at.text ?? ''), words, model: MODEL };
+  }
+}