@graphlearning/shell 0.1.0 → 0.3.0

package/scripts/record-reels.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// record-reels.mjs — [STEP 3, PORTRAIT REELS] one course → NINE standalone 1080×1920 MP4s.
+//
+//   node scripts/record-reels.mjs <course> [--force] [--only <id[,id]>]
+//
+// The vertical-video sibling of record-course.mjs. Deliberately SELF-CONTAINED (no shared module) so
+// the two recorders can diverge freely. What's different from the 4K recorder:
+//   • PORTRAIT 1080×1920 (9:16, the standard Reels/Shorts frame). At this viewport the app's portrait
+//     CSS kicks in: the slide becomes an off-canvas drawer (hidden under ?capture=1), so the recorded
+//     frame is a SCENE-ONLY full-bleed 9:16 — the narration carries the words.
+//   • NINE INDEPENDENT files (out/reels/<course>-<id>.mp4), one per section — NOT concatenated. Each
+//     reel is its own upload, so there is NO separator bell and NO lead-in sting.
+//   • Otherwise the capture contract is identical: navigate the hash → wait for the painted,
+//     fitView-settled frame → screencast for the wav's duration (ffprobe) + a short tail → mux.
+//
+// TRUE portrait pixels: the layout is fluid, so we set the puppeteer VIEWPORT to 1080×1920 directly
+// and page.screencast() records at exactly that CSS size. Audio is read straight off disk from
+// public/audio/<course>/<id>.wav; a missing clip falls back to 3s silence so the run never hangs.
+//
+// Prerequisites: ffmpeg + ffprobe on PATH (Homebrew ffmpeg preferred — libx264 + gradfun deband).
+
+import { execFile, spawn } from 'node:child_process'
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { promisify } from 'node:util'
+import { join, resolve } from 'node:path'
+
+const run = promisify(execFile)
+import { loadPeer, repoDir, dataDir } from './_paths.mjs'
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const sha = (data) => createHash('sha256').update(data).digest('hex').slice(0, 16)
+const pad2 = (n) => String(n).padStart(2, '0')
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, 'utf8')) } catch { return null } }
+
+// ---- portrait reel frame ----------------------------------------------------------------
+const CW = process.env.WIDTH ? +process.env.WIDTH : 1080
+const CH = process.env.HEIGHT ? +process.env.HEIGHT : 1920
+const FPS = process.env.FPS ? +process.env.FPS : 30
+// A short held tail so the reel doesn't cut on the last syllable.
+const TAIL_MS = process.env.TAIL_MS ? +process.env.TAIL_MS : 500
+
+const FFMPEG =
+  process.env.FFMPEG ??
+  ['/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg'].find(existsSync) ??
+  'ffmpeg'
+const HAS_X264 = FFMPEG !== 'ffmpeg'
+const VIDEO_CODEC = process.env.VIDEO_CODEC ?? (HAS_X264 ? 'libx264' : 'h264_videotoolbox')
+const IS_X26X = /^libx26[45]$/.test(VIDEO_CODEC)
+const CRF = process.env.VIDEO_CRF ?? '18'
+const PRESET = process.env.VIDEO_PRESET ?? 'slow'
+const BITRATE = process.env.VIDEO_BITRATE ?? '16M' // 1080×1920 ≈ 1080p pixel budget
+const ENCODE_SIG = IS_X26X ? `${VIDEO_CODEC}:crf${CRF}:${PRESET}` : `${VIDEO_CODEC}:b${BITRATE}`
+
+// ---- ffmpeg helpers ---------------------------------------------------------------------
+async function ffprobeDuration(file) {
+  const { stdout } = await run('ffprobe', [
+    '-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file,
+  ])
+  return parseFloat(stdout.trim())
+}
+
+// Mux one reel's webm + clip → a standalone MP4. Same crisp encode as the 4K recorder (gradfun
+// deband, yuv420p, faststart) but this is a FINAL file, not a concat segment, so it needs no uniform
+// timescale. `total` (clip + tail) bounds both streams; apad extends the clip with silence to fill.
+async function encodeReel(webm, clip, total, outMp4) {
+  const quality = IS_X26X ? ['-preset', PRESET, '-crf', CRF] : ['-b:v', BITRATE]
+  await run(FFMPEG, [
+    '-y', '-i', webm, '-i', clip,
+    '-map', '0:v:0', '-map', '1:a:0',
+    '-vf', 'gradfun=strength=0.9:radius=16',
+    '-r', String(FPS), '-vsync', 'cfr',
+    '-c:v', VIDEO_CODEC, ...quality, '-pix_fmt', 'yuv420p',
+    '-af', 'apad', '-t', total.toFixed(3),
+    '-c:a', 'aac', '-b:a', '192k', '-ar', '44100', '-ac', '1',
+    '-movflags', '+faststart',
+    outMp4,
+  ])
+}
+
+// ---- the app dev server -----------------------------------------------------------------
+async function startDevServer() {
+  console.log(`Starting dev server: ${repoDir} …`)
+  const child = spawn('npm', ['run', 'dev'], { cwd: repoDir, env: process.env })
+  const url = await new Promise((res, rej) => {
+    const to = setTimeout(() => rej(new Error('dev server did not print a URL within 60s')), 60000)
+    const onData = (buf) => {
+      const m = String(buf).match(/https?:\/\/localhost:\d+\/?/)
+      if (m) { clearTimeout(to); child.stdout.off('data', onData); res(m[0].replace(/\/?$/, '/')) }
+    }
+    child.stdout.on('data', onData)
+    child.stderr.on('data', (b) => process.env.DEBUG && process.stderr.write(b))
+    child.on('exit', (code) => rej(new Error(`dev server exited early (code ${code})`)))
+  })
+  for (let i = 0; i < 40; i++) {
+    try { if ((await fetch(url)).ok) break } catch { /* not up yet */ }
+    await sleep(250)
+  }
+  console.log(`  dev server at ${url}`)
+  return { child, url }
+}
+
+// Navigate to a section and wait for its scene to be painted AND fitView-settled. A fresh goto per
+// reel forces a clean react-flow remount (it keys on scene id), so no stale prior scene is in frame.
+async function gotoSection(page, appBase, slug) {
+  await page.goto(`${appBase}?capture=1#/${slug}`, { waitUntil: 'networkidle2' })
+  await page.waitForSelector('.react-flow__node', { timeout: 15000 })
+  await page.evaluate(async () => { if (document.fonts?.ready) await document.fonts.ready })
+  await sleep(700) // fitView (instant) + ResizeObserver re-fit + edge-pulse settle
+}
+
+// CDP screencast only emits a frame on a VISUAL CHANGE, so an otherwise-static reel records an EMPTY
+// webm and the mux fails. A 1px, ~1%-opacity speck nudged every animation frame keeps frames flowing;
+// it is quantized away by x264. Removed on stop.
+async function startKeepalive(page) {
+  await page.evaluate(() => {
+    const d = document.createElement('div')
+    d.id = '__cap_keepalive'
+    d.style.cssText =
+      'position:fixed;left:0;top:0;width:1px;height:1px;background:#888;opacity:0.01;' +
+      'pointer-events:none;z-index:2147483647;will-change:transform'
+    document.body.appendChild(d)
+    let x = 0
+    const loop = () => {
+      x = (x + 3) % 30
+      d.style.transform = `translate3d(${x}px,0,0)`
+      window.__cap_raf = requestAnimationFrame(loop)
+    }
+    loop()
+  })
+}
+async function stopKeepalive(page) {
+  await page.evaluate(() => {
+    if (window.__cap_raf) cancelAnimationFrame(window.__cap_raf)
+    document.getElementById('__cap_keepalive')?.remove()
+  })
+}
+
+// ---- record -----------------------------------------------------------------------------
+async function recordReels(course, { force = false, only = [] } = {}) {
+  const tmp = join(dataDir, '.tmp', `${course}-reels`)
+  const outDir = join(dataDir, 'out', 'reels')
+  for (const d of [tmp, outDir]) mkdirSync(d, { recursive: true })
+
+  let server = null
+  const base = process.env.APP_URL ? process.env.APP_URL.replace(/\/?$/, '/') : null
+  const appBase = base ?? (server = await startDevServer(), server.url)
+
+  const puppeteer = (await loadPeer('puppeteer')).default
+  let browser
+  const made = []
+  try {
+    browser = await puppeteer.launch({
+      headless: true,
+      defaultViewport: { width: CW, height: CH, deviceScaleFactor: 1 },
+      args: [`--window-size=${CW},${CH}`],
+    })
+    const page = await browser.newPage()
+    await page.goto(`${appBase}?capture=1#/${course}`, { waitUntil: 'networkidle2' })
+
+    await page.waitForFunction(() => !!window.__scene, { timeout: 20000 })
+    const plan = await page.evaluate(() => window.__scene.plan())
+    if (!plan?.length) throw new Error(`course "${course}" has no sections (bad id?)`)
+    console.log(`Course ${course}: ${plan.length} reels @ ${CW}×${CH}\n`)
+
+    let n = 0
+    for (const sec of plan) {
+      n++
+      const tag = `${course}-${sec.id}`
+      // Each reel is its own file, so --only truly RESTRICTS the set: skip any section not listed.
+      if (only.length && !only.some((t) => sec.id.includes(t) || tag.includes(t))) continue
+      const outMp4 = join(outDir, `${tag}.mp4`)
+      const sidecar = join(tmp, `${pad2(n)}-${sec.id}.json`)
+      const clip = join(tmp, `${pad2(n)}-${sec.id}.wav`)
+
+      // Narration wav straight off disk. Missing → 3s silence so the run never hangs.
+      const wav = resolve(repoDir, 'public', 'audio', sec.course, `${sec.id}.wav`)
+      let dur, audioHash
+      if (existsSync(wav)) {
+        const buf = readFileSync(wav)
+        writeFileSync(clip, buf)
+        audioHash = sha(buf)
+        dur = await ffprobeDuration(clip)
+      } else {
+        await run(FFMPEG, ['-y', '-f', 'lavfi', '-i', 'anullsrc=r=44100:cl=mono', '-t', '3', clip])
+        audioHash = 'silence3'
+        dur = 3
+        console.warn(`  §${n} ${sec.id}: no audio → 3s silence`)
+      }
+
+      // Incremental reuse: re-record iff missing/changed (or --force / --only match).
+      const fp = sha(JSON.stringify({ v: 1, audioHash, w: CW, h: CH, fps: FPS, tail: TAIL_MS, enc: ENCODE_SIG }))
+      if (!(force || !existsSync(outMp4) || readJson(sidecar)?.fp !== fp)) {
+        console.log(`  §${n} ${sec.id}  reuse`)
+        made.push(outMp4)
+        continue
+      }
+
+      const total = dur + TAIL_MS / 1000
+      await gotoSection(page, appBase, sec.slug)
+
+      const webm = join(tmp, `${pad2(n)}-${sec.id}.webm`)
+      const recorder = await page.screencast({ path: webm })
+      await startKeepalive(page)
+      console.log(`  §${n} ${sec.id}  ▶ record (${dur.toFixed(1)}s)`)
+      await sleep(Math.round(total * 1000))
+      await recorder.stop()
+      await stopKeepalive(page)
+
+      await encodeReel(webm, clip, total, outMp4)
+      writeFileSync(sidecar, JSON.stringify({ fp, builtAt: new Date().toISOString() }, null, 2))
+      made.push(outMp4)
+      console.log(`  §${n} ${sec.id}  ✓ reels/${tag}.mp4`)
+    }
+  } finally {
+    if (browser) await browser.close()
+    if (server) server.child.kill('SIGTERM')
+  }
+
+  console.log(`\n✅ ${made.length} reel(s) → scripts/out/reels/`)
+  return made
+}
+
+// ---- CLI --------------------------------------------------------------------------------
+function parse(argv) {
+  const pos = []
+  const only = []
+  let force = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--force') force = true
+    else if (a === '--only') only.push(...(argv[++i] ?? '').split(',').filter(Boolean))
+    else if (a.startsWith('--only=')) only.push(...a.slice(7).split(',').filter(Boolean))
+    else pos.push(a)
+  }
+  return { pos, only, force }
+}
+
+const { pos, only, force } = parse(process.argv.slice(2))
+const [course] = pos
+if (!course) {
+  console.error('usage: node scripts/record-reels.mjs <course> [--force] [--only <id[,id]>]')
+  process.exit(2)
+}
+recordReels(course, { force, only }).catch((e) => {
+  console.error('\n✗', e.message)
+  process.exit(1)
+})

package/scripts/shots-4k.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Quick 4K visual check — one PNG per section at 3840×2160, no screencast/audio/ffmpeg.
+// Mirrors record-course.mjs's viewport + capture route + fit-wait, so the framing matches the video.
+//   node scripts/shots-4k.mjs [course] [--only id[,id]]
+import { spawn } from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { loadPeer, repoDir, dataDir } from './_paths.mjs'
+const outDir = join(dataDir, 'out', 'shots-4k')
+mkdirSync(outDir, { recursive: true })
+const CW = +(process.env.WIDTH ?? 3840), CH = +(process.env.HEIGHT ?? 2160)
+const course = process.argv[2] && !process.argv[2].startsWith('--') ? process.argv[2] : 'foundations'
+const onlyArg = process.argv.indexOf('--only')
+const only = onlyArg !== -1 ? (process.argv[onlyArg + 1] ?? '').split(',').filter(Boolean) : []
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+// Reuse an already-running server (e.g. the frozen `npm run capture` snapshot on :5181) via APP_URL so
+// you can keep editing source meanwhile; otherwise spawn a throwaway dev server.
+let child = null, url = process.env.APP_URL ? process.env.APP_URL.replace(/\/?$/, '/') : null
+if (!url) {
+  child = spawn('npm', ['run', 'dev'], { cwd: repoDir, env: process.env })
+  url = await new Promise((res, rej) => {
+    const to = setTimeout(() => rej(new Error('no dev url in 60s')), 60000)
+    child.stdout.on('data', (b) => { const m = String(b).match(/https?:\/\/localhost:\d+\/?/); if (m) { clearTimeout(to); res(m[0].replace(/\/?$/, '/')) } })
+    child.on('exit', (c) => rej(new Error(`dev exited ${c}`)))
+  })
+}
+for (let i = 0; i < 40; i++) { try { if ((await fetch(url)).ok) break } catch {} await sleep(250) }
+console.log(`server ${url} — shooting ${CW}×${CH}`)
+
+const puppeteer = (await loadPeer('puppeteer')).default
+const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox'] })
+const page = await browser.newPage()
+await page.setViewport({ width: CW, height: CH, deviceScaleFactor: 1 })
+
+await page.goto(`${url}?capture=1#/`, { waitUntil: 'networkidle2' })
+await page.waitForFunction(() => !!window.__scene, { timeout: 20000 })
+let plan = await page.evaluate(() => window.__scene.plan())
+plan = plan.filter((p) => p.course === course && (only.length === 0 || only.includes(p.id)))
+
+let n = 0
+for (const p of plan) {
+  await page.goto(`${url}?capture=1#/${p.slug}`, { waitUntil: 'networkidle2' })
+  await page.waitForSelector('.react-flow__node', { timeout: 15000 })
+  await page.evaluate(async () => { if (document.fonts?.ready) await document.fonts.ready })
+  await sleep(900) // fitView + ResizeObserver re-fit + edge-pulse settle (matches recorder)
+  const file = join(outDir, `${String(++n).padStart(2, '0')}-${p.id}.png`)
+  await page.screenshot({ path: file })
+  console.log(`  ${p.slug} → ${file}`)
+}
+await browser.close(); child?.kill('SIGTERM')
+console.log(`\n✅ ${n} shots in ${outDir}`)
+process.exit(0)

package/scripts/thumb-template.html

@@ -0,0 +1,52 @@
+<!-- thumb-template.html — the branded thumbnail layout, filled by thumb.mjs.
+     Left = the course scene (screenshot of the .scene-area, no slide); right = an HTML/CSS panel
+     driven by the concept + course (kicker + title) with the GraphL wordmark (+ optional logo mark).
+     Sizes are in vw/vh so the layout is resolution-independent: thumb.mjs injects this into the app's
+     own 4K viewport (fonts inherited), screenshots it, then downscales to 1280×720.
+     thumb.mjs substitutes the double-brace tokens below (SCENE, KICKER, NUMBER, TITLE, LOGO, PANEL_BG). -->
+<style>
+  html, body { margin: 0; padding: 0; height: 100%; background: #1e2127; }
+  .thumb {
+    display: flex;
+    width: 100vw;
+    height: 100vh;
+    overflow: hidden;
+    background: #1e2127;               /* letterbox surround (Zed-slate theme) */
+    font-family: 'IBM Plex Sans', ui-sans-serif, system-ui, sans-serif;
+  }
+  /* LEFT — the course scene, as it renders. cover + left anchor lets the diagram bleed off the
+     left edge (poster look) while filling the panel. */
+  .thumb__scene { flex: 0 0 58%; height: 100%; position: relative; background: #1e2127; }
+  .thumb__scene img { width: 100%; height: 100%; object-fit: cover; object-position: left center; display: block; }
+  /* A soft seam so the scene reads as continuing under the panel rather than a hard cut. */
+  .thumb__scene::after {
+    content: ''; position: absolute; top: 0; right: 0; width: 8%; height: 100%;
+    background: linear-gradient(90deg, rgba(30,33,39,0), rgba(30,33,39,0.55));
+  }
+  /* RIGHT — the branded panel. Gradient is substituted ({{PANEL_BG}}) so a course can override it. */
+  .thumb__panel {
+    flex: 1; position: relative; display: flex; flex-direction: column;
+    padding: 6.4vh 3.8vw;
+    color: #fff;
+    background: {{PANEL_BG}};
+  }
+  .thumb__kicker {
+    font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+    text-transform: uppercase; letter-spacing: 0.26em; font-weight: 500;
+    font-size: 3.5vh; color: rgba(255, 255, 255, 0.94);
+  }
+  .thumb__titlewrap { margin-top: auto; margin-bottom: auto; }
+  .thumb__number { font-weight: 700; font-size: 14vh; line-height: 0.98; letter-spacing: -0.01em; }
+  .thumb__title  { font-weight: 700; font-size: 9.4vh; line-height: 1.03; letter-spacing: -0.025em; margin-top: 0.6vh; }
+  .thumb__foot { display: flex; align-items: center; gap: 1.5vh; }
+  .thumb__logo { width: 5vh; height: 5vh; border-radius: 1.1vh; display: block; }
+  .thumb__brand { font-weight: 700; font-size: 3.1vh; letter-spacing: -0.01em; }
+</style>
+<div class="thumb">
+  <div class="thumb__scene"><img src="{{SCENE}}" alt=""></div>
+  <div class="thumb__panel">
+    <div class="thumb__kicker">{{KICKER}}</div>
+    <div class="thumb__titlewrap">{{NUMBER}}<div class="thumb__title">{{TITLE}}</div></div>
+    <div class="thumb__foot">{{LOGO}}<div class="thumb__brand">GraphL</div></div>
+  </div>
+</div>

package/scripts/thumb.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// thumb.mjs — a crisp, branded YouTube thumbnail for a course.
+//
+//   node scripts/thumb.mjs <course> [--section N]
+//                          [--title T] [--kicker K] [--number NN] [--panel css] [--out file] [--full4k] [--at ms]
+//
+// Adapted from ../../graphl-studio/aws/scripts/thumb.mjs for this SECTION-based repo. The reference
+// was beat-based (--section/--beat, driven off window.__capture); here one SECTION = one scene, so it
+// navigates the app's hash to a section's slug (like record-course.mjs) and there is no --beat. It
+// reads the course layout from window.__scene.plan() (see src/App.tsx) to pick which section's scene
+// to shoot (default: the first).
+//
+// The thumbnail is a TEMPLATE (thumb-template.html): LEFT = the course scene as it renders (a lossless
+// screenshot of the .scene-area — no slide), RIGHT = an HTML/CSS panel driven by the concept + course
+// (kicker = concept, title = course title) with the GraphL wordmark (+ an optional logo mark).
+//
+// It's composited in the app's OWN page so the panel inherits the app's self-hosted Plex fonts (no
+// CDN, crisp text — never ffmpeg drawtext). Like record-course.mjs it drives the app in ?capture=1,
+// spawns the app's `npm run dev` unless APP_URL reuses a server, supersamples to SCALE× (4K), then
+// downscales to 1280×720 (Lanczos).
+//
+// Prerequisites: ffmpeg on PATH (Homebrew preferred, as with record-course.mjs).
+
+import { execFile, spawn } from 'node:child_process'
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { promisify } from 'node:util'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve, isAbsolute } from 'node:path'
+
+const run = promisify(execFile)
+import { loadPeer, repoDir, dataDir, pkgDir, concept } from './_paths.mjs'
+const { build } = await loadPeer('esbuild')
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+// Same supersampling as record-course.mjs: render the 1920×1080 stage at SCALE× device pixels so text
+// re-rasterizes crisp, then downscale. SCALE=2 → a 3840×2160 master → 1280×720 thumbnail.
+const W = 1920
+const H = 1080
+const SCALE = process.env.SCALE ? +process.env.SCALE : 2
+const CW = W * SCALE
+const CH = H * SCALE
+
+// Prefer a Homebrew ffmpeg (same choice record-course.mjs makes) for the Lanczos downscale.
+const FFMPEG =
+  process.env.FFMPEG ??
+  ['/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg'].find(existsSync) ??
+  'ffmpeg'
+
+const TEMPLATE = join(pkgDir, 'thumb-template.html') // ships with the package
+// Optional GraphL mark for the panel foot. Drop an SVG at any of these paths to show it; otherwise the
+// foot renders the "GraphL" wordmark alone. Override with LOGO_SVG=/path.
+const LOGO_CANDIDATES = [
+  process.env.LOGO_SVG,
+  join(dataDir, 'logo.svg'),
+  join(repoDir, 'public', 'icon.svg'),
+].filter(Boolean)
+const LOGO_SVG = LOGO_CANDIDATES.find(existsSync) ?? null
+
+// The concept shown as the panel kicker.
+const CONCEPT = concept.kicker
+// The right-side panel gradient (brand block). Python-blue by default — it echoes the language's
+// brand and reads well against the Zed-slate scene on the left. Override per-thumb with --panel.
+const DEFAULT_PANEL_BG = concept.panelBg
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+// A slug → display fallback ("data-engineering" → "Data Engineering") when the registry lacks it.
+const titleCase = (slug) => slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
+
+// ---- CLI --------------------------------------------------------------------------------
+function parse(argv) {
+  const pos = []
+  const opt = { section: 0, at: 900, out: null, full4k: false, title: null, kicker: null, number: null, panel: null }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--section') opt.section = +argv[++i]
+    else if (a === '--at') opt.at = +argv[++i]
+    else if (a === '--out') opt.out = argv[++i]
+    else if (a === '--title') opt.title = argv[++i]
+    else if (a === '--kicker') opt.kicker = argv[++i]
+    else if (a === '--number') opt.number = argv[++i]
+    else if (a === '--panel') opt.panel = argv[++i]
+    else if (a === '--full4k') opt.full4k = true
+    else pos.push(a)
+  }
+  return { pos, opt }
+}
+
+// ---- the app dev server (same handshake as record-course.mjs) ---------------------------
+async function startDevServer(conceptDir) {
+  console.log(`Starting dev server: ${conceptDir} …`)
+  const child = spawn('npm', ['run', 'dev'], { cwd: conceptDir, env: process.env })
+  const url = await new Promise((res, rej) => {
+    const to = setTimeout(() => rej(new Error('dev server did not print a URL within 60s')), 60000)
+    const onData = (buf) => {
+      const m = String(buf).match(/https?:\/\/localhost:\d+\/?/)
+      if (m) { clearTimeout(to); child.stdout.off('data', onData); res(m[0].replace(/\/?$/, '/')) }
+    }
+    child.stdout.on('data', onData)
+    child.stderr.on('data', (b) => process.env.DEBUG && process.stderr.write(b))
+    child.on('exit', (code) => rej(new Error(`dev server exited early (code ${code})`)))
+  })
+  for (let i = 0; i < 40; i++) {
+    try { if ((await fetch(url)).ok) break } catch { /* not up yet */ }
+    await sleep(250)
+  }
+  console.log(`  dev server at ${url}`)
+  return { child, url }
+}
+
+// Curated PUBLISH titles (scripts/titles.json), keyed by course id — the header a thumbnail wears on
+// YouTube ("Python Data Structures"), which is search-facing and so deliberately differs from the
+// registry's narrative in-app title ("Data structures"). Optional: absent file → registry title.
+const PUBLISH_TITLES = (() => {
+  const f = join(dataDir, 'titles.json')
+  if (!existsSync(f)) return {}
+  try {
+    const { _comment, ...titles } = JSON.parse(readFileSync(f, 'utf8'))
+    return titles
+  } catch {
+    return {}
+  }
+})()
+
+// course title: titles.json override first, else the typed COURSES registry, so the panel copy matches
+// what ships. The content files import ONLY `../types` (erased) → the bundle has no runtime deps.
+async function courseTitle(course) {
+  if (PUBLISH_TITLES[course]) return PUBLISH_TITLES[course]
+  try {
+    const result = await build({
+      entryPoints: [resolve(repoDir, 'src/content/index.ts')],
+      bundle: true, format: 'esm', platform: 'node', write: false,
+    })
+    const code = result.outputFiles[0].text
+    const reg = await import('data:text/javascript;base64,' + Buffer.from(code).toString('base64'))
+    return reg.COURSES?.[course]?.title ?? null
+  } catch {
+    return null
+  }
+}
+
+// ---- thumbnail --------------------------------------------------------------------------
+async function makeThumb(course, opt) {
+  if (!existsSync(TEMPLATE)) throw new Error(`template not found: ${TEMPLATE}`)
+
+  const outDir = join(dataDir, 'out')
+  mkdirSync(outDir, { recursive: true })
+  const outArg = opt.out ?? `${course}.png`
+  const out = isAbsolute(outArg) || outArg.includes('/') ? outArg : join(outDir, outArg)
+
+  // Spawn the dev server (unless APP_URL reuses an existing one).
+  let server = null
+  const base = process.env.APP_URL ? process.env.APP_URL.replace(/\/?$/, '/') : null
+  const appBase = base ?? (server = await startDevServer(repoDir), server.url)
+
+  const puppeteer = (await loadPeer('puppeteer')).default
+  let browser
+  try {
+    browser = await puppeteer.launch({
+      headless: true,
+      defaultViewport: { width: CW, height: CH, deviceScaleFactor: 1 },
+      args: [`--window-size=${CW},${CH}`, '--autoplay-policy=no-user-gesture-required'],
+    })
+    const page = await browser.newPage()
+
+    // Read the course layout (list of sections + their slugs) from the app's own capture contract.
+    await page.goto(`${appBase}?capture=1#/${course}`, { waitUntil: 'networkidle2' })
+    await page.waitForFunction(() => !!window.__scene, { timeout: 20000 })
+    const plan = await page.evaluate(() => window.__scene.plan())
+    if (!plan?.length) throw new Error(`course "${course}" has no sections (bad id?)`)
+    const sec = plan[opt.section]
+    if (!sec) throw new Error(`section ${opt.section} out of range (course has ${plan.length})`)
+
+    // Navigate to the chosen section's slug and wait for the painted, fitView-settled scene (a fresh
+    // goto forces a clean react-flow remount — no stale prior scene in the frame), same as the recorder.
+    await page.goto(`${appBase}?capture=1#/${sec.slug}`, { waitUntil: 'networkidle2' })
+    await page.waitForSelector('.react-flow__node', { timeout: 15000 })
+    await page.evaluate(async () => { if (document.fonts?.ready) await document.fonts.ready })
+    await sleep(opt.at) // fitView + ResizeObserver re-fit + edge-pulse settle
+
+    // LEFT — screenshot just the scene area (no slide) → data URI for the template.
+    const scenePane = await page.$('.scene-area')
+    if (!scenePane) throw new Error('.scene-area not found (SectionView markup changed?)')
+    const sceneB64 = await scenePane.screenshot({ encoding: 'base64' })
+    const sceneUri = `data:image/png;base64,${sceneB64}`
+
+    // Panel copy: kicker = concept, title = course title (registry/titles.json → flags override → slug).
+    const title = opt.title ?? (await courseTitle(course)) ?? titleCase(course)
+    const kicker = opt.kicker ?? CONCEPT
+    const numberHtml = opt.number ? `<div class="thumb__number">${esc(opt.number)}</div>` : ''
+    // Logo is optional: show the mark if one is present, else just the wordmark.
+    const logoSvg = LOGO_SVG ? readFileSync(LOGO_SVG, 'utf8').replace('<svg ', '<svg class="thumb__logo" ') : ''
+    const panelBg = opt.panel ?? DEFAULT_PANEL_BG
+
+    const html = readFileSync(TEMPLATE, 'utf8')
+      .replaceAll('{{SCENE}}', sceneUri)
+      .replaceAll('{{KICKER}}', esc(kicker))
+      .replaceAll('{{NUMBER}}', numberHtml)
+      .replaceAll('{{TITLE}}', esc(title))
+      .replaceAll('{{LOGO}}', logoSvg)
+      .replaceAll('{{PANEL_BG}}', panelBg)
+
+    // Composite IN the app page so the panel inherits the loaded Plex fonts: replace only the BODY
+    // (keeping the head's @fontsource @font-face rules), then wait for the fonts + a layout tick.
+    await page.evaluate((h) => { document.body.innerHTML = h }, html)
+    await page.evaluate(() => document.fonts.ready)
+    await sleep(200)
+
+    // Lossless 4K screenshot of the composed frame → downscale to 1280×720 (Lanczos).
+    mkdirSync(dirname(out), { recursive: true })
+    const shot = opt.full4k ? out : join(tmpdir(), `thumb-4k-${Date.now()}.png`)
+    await page.screenshot({ path: shot })
+    if (!opt.full4k) {
+      await run(FFMPEG, ['-y', '-loglevel', 'error', '-i', shot, '-vf', 'scale=1280:720:flags=lanczos', out])
+      rmSync(shot, { force: true })
+    }
+    console.log(`\n✅ ${out}   (${kicker} — ${title})`)
+    return out
+  } finally {
+    if (browser) await browser.close()
+    if (server) server.child.kill('SIGTERM')
+  }
+}
+
+const { pos, opt } = parse(process.argv.slice(2))
+const [course] = pos
+if (!course) {
+  console.error('usage: node scripts/thumb.mjs <course> [--section N] [--title T] [--kicker K] [--number NN] [--panel css-gradient] [--out file] [--full4k] [--at ms]')
+  process.exit(2)
+}
+makeThumb(course, opt).catch((e) => {
+  console.error('\n✗', e.message)
+  process.exit(1)
+})