@graphlearning/shell 0.1.0 → 0.2.0

package/README.md

@@ -77,3 +77,43 @@ regression is visible here before it reaches any content repo.
 second react-flow store) inside this package. The content repo pins the engine itself and must get
 exactly one copy — and a wide peer range (`>=0.5.0 <1.0.0`) means an engine minor does not force a
 republish of this package.
+
+## The toolchain
+
+The capture / record / publish scripts ship with this package too — they were byte-identical in all
+seven repos and they drive the route contract above, so they version with the shell that defines it.
+They are `bin` entries, wired through each repo's `npm run`:
+
+| command | what it does |
+|---|---|
+| `npm run record` | one course → a 3840×2160 MP4 |
+| `npm run record:reels` | one course → portrait reels |
+| `npm run shots:4k` | one PNG per section, no ffmpeg |
+| `npm run thumb` | a branded YouTube thumbnail |
+| `npm run gen:desc` | video descriptions + chapters |
+| `npm run gen:audio` | the narration manifest |
+
+**Where things live.** Scripts resolve two roots explicitly (`scripts/_paths.mjs`), because from
+`node_modules` they can no longer use their own directory:
+
+- `repoDir` = `process.cwd()` — the content repo. `npm run` sets cwd to the package root.
+- `dataDir` = `repoDir/scripts` — the repo's script data (`concept.json`, `titles.json`,
+  `audio-manifest.json`) **and every output** (`out/`, `segments/`, `.tmp/`), at exactly the paths
+  they used before the extraction, so existing `.gitignore` entries still hold.
+- `pkgDir` — machinery that ships here (`thumb-template.html`).
+
+**Peer resolution.** `puppeteer` and `esbuild` are optional peers, loaded via `loadPeer()` which
+resolves them **from the repo**, not from this package. A bare `import('puppeteer')` resolves by
+walking up from the importing file, which under a local `file:` install lands in `ui-shell/` and
+never reaches the repo's `node_modules`.
+
+**`scripts/concept.json`** is the per-repo publishing identity — the values that used to be
+hardcoded defaults in each repo's copy, which is precisely why they drifted:
+
+```json
+{ "concept": "Apache Spark", "kicker": "SPARK", "site": "https://graphl.in",
+  "appPath": "/apache-spark", "hashtags": "#ApacheSpark …", "panelBg": "radial-gradient(…)" }
+```
+
+`concept` is the name used in descriptions; `kicker` is the thumbnail panel's label and defaults to
+`concept` — they differ only where a long name will not fit the panel (apache-spark).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@graphlearning/shell",
-  "version": "0.1.0",
-  "description": "The GraphL concept-app shell — hash router, section view (scene left / slide right), slide panel, course catalog and narration channel. A content repo supplies courses + scenes; the shell is everything around them.",
+  "version": "0.2.0",
+  "description": "The GraphL concept-app shell \u2014 hash router, section view (scene left / slide right), slide panel, course catalog and narration channel, plus the capture/record/publish toolchain that drives them. A content repo supplies courses + scenes.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "scripts"
   ],
   "publishConfig": {
     "access": "public"
@@ -32,7 +33,9 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-markdown": "^10.1.0",
-    "remark-gfm": "^4.0.1"
+    "remark-gfm": "^4.0.1",
+    "puppeteer": ">=24",
+    "esbuild": ">=0.20"
   },
   "devDependencies": {
     "@graphlearning/flow": "^0.5.0",
@@ -47,5 +50,22 @@
     "remark-gfm": "^4.0.1",
     "typescript": "~5.7.2",
     "vite": "^6.0.5"
+  },
+  "bin": {
+    "graphl-record": "scripts/record-course.mjs",
+    "graphl-record-reels": "scripts/record-reels.mjs",
+    "graphl-shots-4k": "scripts/shots-4k.mjs",
+    "graphl-capture-shots": "scripts/capture-shots.mjs",
+    "graphl-gen-audio": "scripts/gen-audio-manifest.mjs",
+    "graphl-gen-desc": "scripts/gen-descriptions.mjs",
+    "graphl-thumb": "scripts/thumb.mjs"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    }
   }
 }

package/scripts/_paths.mjs

@@ -0,0 +1,72 @@
+// Where these scripts read and write, now that they live in a package rather than in each repo.
+//
+// They used to resolve everything relative to their own file (`here = dirname(import.meta.url)`),
+// which worked only because scripts/ sat inside the app. From node_modules that points at the
+// package, so the two roots are now explicit:
+//
+//   repoDir — the content repo being built. npm run <script> sets cwd to the package root, so
+//             process.cwd() IS the repo. Source, public/audio and the dev server live here.
+//   dataDir — repoDir/scripts: the repo's own script DATA (titles.json, audio-manifest.json) and
+//             every output (out/, segments/, .tmp/). Deliberately the same paths as before the
+//             extraction, so .gitignore entries and muscle memory still hold.
+//   pkgDir  — this package's scripts/: machinery that ships with the shell (thumb-template.html).
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const pkgDir = dirname(fileURLToPath(import.meta.url))
+export const repoDir = process.cwd()
+export const dataDir = join(repoDir, 'scripts')
+
+if (!existsSync(join(repoDir, 'package.json'))) {
+  console.error(`No package.json in ${repoDir} — run this from a content repo's root (npm run …).`)
+  process.exit(1)
+}
+
+// scripts/concept.json — the per-repo publishing identity. These used to be hardcoded defaults in
+// each repo's copy of thumb.mjs / gen-descriptions.mjs, which is exactly why they drifted (aws's
+// panel gradient was still AWS-orange in sql's copy for a while). Env vars still override, as before.
+const CONFIG_PATH = join(dataDir, 'concept.json')
+const raw = existsSync(CONFIG_PATH) ? JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) : {}
+
+export const concept = {
+  // The concept name used in video DESCRIPTIONS ("Apache Spark"). Not necessarily the app's
+  // subject — databricks-data-engineer publishes as "Databricks".
+  name: process.env.CONCEPT ?? raw.concept ?? 'GraphL',
+  // The THUMBNAIL kicker, which is not always the same string: apache-spark's descriptions say
+  // "Apache Spark" while its thumbnails say "SPARK" (a long name does not fit the panel). The two
+  // lived in separate script copies before the extraction, so the divergence was invisible —
+  // collapsing them into one field silently rebrands that concept's thumbnails.
+  kicker: process.env.CONCEPT_KICKER ?? raw.kicker ?? process.env.CONCEPT ?? raw.concept ?? 'GraphL',
+  site: process.env.SITE ?? raw.site ?? 'https://graphl.in',
+  // The catalog path the app deploys under — usually /<repo>, but aws deploys at /aws-content.
+  appPath: (process.env.APP_PATH ?? raw.appPath ?? '/').replace(/\/$/, ''),
+  hashtags: process.env.HASHTAGS ?? raw.hashtags ?? '#TechEducation',
+  // The thumbnail's right-hand panel gradient, anchored on the concept's --brand.
+  panelBg: process.env.PANEL_BG ?? raw.panelBg ?? 'radial-gradient(118% 104% at 70% 34%, #5b8cff 0%, #2a4fb8 44%, #0b1330 100%)',
+}
+
+// Load a peer dependency (puppeteer, esbuild) from the CONTENT REPO, not from this package.
+//
+// A bare `import('puppeteer')` resolves by walking up from the importing FILE. These scripts live in
+// node_modules/@graphlearning/shell/scripts, and under a local `file:../ui-shell` install that path
+// is a symlink — node resolves it to the real ui-shell/ directory and walks up from there, never
+// reaching the repo's node_modules. Anchoring the resolution at repoDir works under both layouts,
+// and it is also the honest description of the dependency: these are the REPO's tools, which the
+// scripts borrow. (esbuild previously resolved only by accident, via ui-shell's own vite install —
+// that would have failed outright once this package was consumed from the registry.)
+const requireFromRepo = createRequire(join(repoDir, 'package.json'))
+
+export async function loadPeer(name) {
+  try {
+    return await import(pathToFileURL(requireFromRepo.resolve(name)).href)
+  } catch {
+    console.error(`Missing "${name}" in ${repoDir}. It is an optional peer of @graphlearning/shell, ` +
+                  `needed by the capture/record scripts — install it there: npm i -D ${name}`)
+    process.exit(1)
+  }
+}
+
+export { resolve }

package/scripts/capture-shots.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// capture-shots.mjs — [STEP 2, not yet wired] screenshot every slug's scene + record node coords.
+//
+//   node scripts/capture-shots.mjs [--only <slug[,slug]>]
+//
+// Plan (blueprint: ../../graphl-studio/aws-lab/scripts/capture-shots.mjs):
+//   1. spawn `npm run dev`, open it headless at 4K (3840×2160) with ?capture=1.
+//   2. read window.__scene.plan() → the list of slugs (scene + focus node).
+//   3. for each slug: render its scene, wait for the painted frame, screenshot → images/<slug>.png
+//      (full-frame background), and MEASURE node bounding boxes (react-flow node rects) → coords,
+//      including the focus node's box. Coords are written to a sidecar so the compose step can float
+//      the text panel clear of the narrating node.
+//
+// The full-frame PNG is the video background; the coords drive dynamic panel placement.
+
+console.error('capture-shots.mjs is a step-2 stub — not wired yet. See the header for the plan.')
+process.exit(1)

package/scripts/gen-audio-manifest.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// gen-audio-manifest.mjs — flatten the typed course catalog into the audio manifest.
+//
+// The Colab/Chatterbox notebook can't parse our TypeScript course files, so this is the bridge:
+// it evaluates the REAL `COURSES` registry (esbuild strips the type-only `../types` imports, so the
+// content files have no runtime deps) and folds every SECTION into one flat JSON entry, keyed to the
+// audio contract path  `<courseId>/<section-id>.wav`.
+//
+// Unlike graphl-studio (one wav per BEAT → `<course>/<section>-<beat>.wav`), this repo's model is
+// one section = one unit = one narration, so there is NO beat index — just `<course>/<section>.wav`.
+//
+//   Output: scripts/audio-manifest.json   →  { count, entries: [{ course, section, file, narration }] }
+//
+// Run:  npm run gen:audio   (then commit the json so the notebook sees it)
+
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { loadPeer, repoDir, dataDir } from './_paths.mjs'
+const { build } = await loadPeer('esbuild')
+const entry = resolve(repoDir, 'src/content/index.ts')
+const outFile = resolve(dataDir, 'audio-manifest.json')
+
+// Bundle the content registry to an in-memory ESM string. The content files import ONLY `../types`
+// (`import type` → erased), so the bundle has zero runtime deps and imports cleanly in Node.
+const result = await build({
+  entryPoints: [entry],
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+  write: false,
+})
+const code = result.outputFiles[0].text
+const mod = await import('data:text/javascript;base64,' + Buffer.from(code).toString('base64'))
+const { COURSES } = mod
+
+const entries = []
+for (const course of Object.values(COURSES)) {
+  course.sections.forEach((section) => {
+    entries.push({
+      course: course.id,
+      section: section.id,
+      file: `${course.id}/${section.id}.wav`,
+      narration: section.narration,
+    })
+  })
+}
+
+const manifest = { count: entries.length, entries }
+writeFileSync(outFile, JSON.stringify(manifest, null, 2) + '\n', 'utf-8')
+
+// A short human summary — how many sections per course, so a bad fold is obvious at a glance.
+const perCourse = {}
+for (const e of entries) perCourse[e.course] = (perCourse[e.course] ?? 0) + 1
+console.log(`Wrote ${entries.length} section(s) -> scripts/audio-manifest.json`)
+for (const c of Object.values(COURSES))
+  console.log(`  ${c.id.padEnd(12)} ${perCourse[c.id] ?? 0} section(s)`)

package/scripts/gen-descriptions.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// gen-descriptions.mjs — write a YouTube description .txt per course.
+//
+//   node scripts/gen-descriptions.mjs            # all courses
+//   node scripts/gen-descriptions.mjs foundations   # just one
+//
+// Adapted from ../../graphl-studio/aws/scripts/gen-descriptions.mjs for this SECTION-based repo. The
+// reference was beat-based and read slide titles from the live DOM (driven in ?capture=1); here one
+// SECTION = one scene + one slide + one narration wav, and every section already carries its own
+// `title` in the typed registry — so we need NO browser at all. We evaluate the real COURSES registry
+// via esbuild (the same bridge scripts/gen-audio-manifest.mjs uses) and read chapter titles straight
+// off it; chapter TIMES are ffprobe'd off each section's wav and summed with record-course.mjs's own
+// per-section timing (bell STING lead + clip + TAIL), so they line up with the concatenated MP4.
+//
+// Each description carries: a title + intro, CHAPTER timestamps (one per section, so YouTube
+// auto-chapters the video), the full course series with deep links, and hashtags. Output lands at
+// scripts/out/<course>.txt, next to the course's .mp4 / .png.
+//
+// Prerequisites: ffprobe on PATH; the app's audio present under public/audio/<course>/.
+
+import { execFile } from 'node:child_process'
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { promisify } from 'node:util'
+import { join, resolve } from 'node:path'
+
+const run = promisify(execFile)
+import { loadPeer, repoDir, dataDir, concept } from './_paths.mjs'
+const { build } = await loadPeer('esbuild')
+
+// Match record-course.mjs's timing so chapter marks align with the concatenated video.
+const STING_MS = process.env.NO_STING ? 0 : process.env.STING_MS ? +process.env.STING_MS : 2800
+const TAIL_MS = process.env.TAIL_MS ? +process.env.TAIL_MS : 500
+const CIRCLED = ['①', '②', '③', '④', '⑤', '⑥', '⑦', '⑧', '⑨', '⑩', '⑪', '⑫']
+
+// The concept + where the app deploys, from the repo's scripts/concept.json (env vars still
+// override — see _paths.mjs). Deep link is `${SITE}${APP_PATH}/#/<course>` (hash routing).
+const CONCEPT = concept.name
+const SITE = concept.site
+const APP_PATH = concept.appPath
+const HASHTAGS = concept.hashtags
+
+// Curated PUBLISH titles (scripts/titles.json), keyed by course id — the search-facing name a course
+// carries on YouTube ("SQL Queries"), deliberately distinct from the registry's narrative
+// in-app title ("Data Ingestion"). Used for this video's headline AND every series entry, so the
+// description names courses the same way the thumbnails and video titles do. Absent file → registry.
+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 {}
+  }
+})()
+const publishTitle = (course) => PUBLISH_TITLES[course.id] ?? course.title
+
+const titleCase = (slug) => slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
+// m:ss (or h:mm:ss past an hour) — YouTube chapter format; first chapter must be 0:00.
+function stamp(sec) {
+  const s = Math.floor(sec), h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), ss = s % 60
+  const p2 = (n) => String(n).padStart(2, '0')
+  return h > 0 ? `${h}:${p2(m)}:${p2(ss)}` : `${m}:${p2(ss)}`
+}
+
+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())
+}
+
+// Evaluate the typed COURSES registry. The content files import ONLY `../types` (`import type` →
+// erased), so the bundle has zero runtime deps and imports cleanly from memory.
+async function loadRegistry() {
+  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
+  return import('data:text/javascript;base64,' + Buffer.from(code).toString('base64'))
+}
+
+// Build the description text for one course. Blocks are separated by a VISIBLE rule (not blank lines)
+// so grouping survives even if YouTube trims empty lines on paste; chapters stay one-per-line
+// (required for auto-chapters) and each series entry is a single line ending in its URL (clickable).
+const RULE = '━━━━━━━━━━━━━━━━'
+function compose({ course, chapters, series }) {
+  const L = []
+  // Headline: "<title> · <concept>", but drop the suffix when the publish title already leads with the
+  // concept ("SQL Queries · SQL" stammers; the publish title is the whole name).
+  const headline = publishTitle(course)
+  L.push(headline.toLowerCase().startsWith(CONCEPT.toLowerCase()) ? headline : `${headline} · ${CONCEPT}`)
+  L.push(RULE)
+  // NB: this used to claim "the diagram assembles top-to-bottom as the narration walks through each
+  // idea" — boilerplate inherited from the graphl-studio reveal-engine, where a camera really did
+  // build a scene up beat by beat. THIS engine draws each scene SOLID (see record-course.mjs: "no
+  // reveal fold, no seek/transition/pan machinery"), so nothing assembles and the sentence described
+  // a video that does not exist. Same wrong line is still in the other concept repos' copies.
+  L.push(
+    `Part of GraphL's ${CONCEPT} series — every section pairs one diagram with the idea it explains, ` +
+    `so the picture and the words land together.`,
+  )
+  L.push(RULE)
+  L.push('⏱ CHAPTERS')
+  for (const c of chapters) L.push(`${stamp(c.start)} ${c.title}`)
+  L.push(RULE)
+  L.push(`▶ ${CONCEPT.toUpperCase()} — THE SERIES`)
+  series.forEach((s, i) => {
+    const label = s.id === course.id ? `${publishTitle(s)}  ◀ this video` : publishTitle(s)
+    L.push(`${CIRCLED[i] ?? '•'} ${label} → ${SITE}${APP_PATH}/#/${s.id}`)
+  })
+  L.push(RULE)
+  L.push(`🔗 Watch interactively on GraphL → ${SITE}${APP_PATH}/#/${course.id}`)
+  L.push(`🌐 More concepts → ${SITE}`)
+  L.push(RULE)
+  L.push(HASHTAGS)
+  return L.join('\n') + '\n'
+}
+
+async function main() {
+  const [oneCourse] = process.argv.slice(2)
+
+  const reg = await loadRegistry()
+  const series = Object.values(reg.COURSES) // catalog order (registry insertion order)
+  const targets = oneCourse ? series.filter((c) => c.id === oneCourse) : series
+  if (!targets.length) {
+    console.error(`✗ no such course "${oneCourse}" (have: ${series.map((c) => c.id).join(', ')})`)
+    process.exit(1)
+  }
+
+  const outDir = join(dataDir, 'out')
+  mkdirSync(outDir, { recursive: true })
+
+  for (const course of targets) {
+    const audioDir = join(repoDir, 'public', 'audio', course.id)
+    const chapters = []
+    let t = 0
+    let missing = 0
+    for (const section of course.sections) {
+      // Chapter starts at this section's bell lead-in (its first frame) — record-course.mjs holds the
+      // opening frame for STING_MS under the bell, then the narration clip, then a TAIL.
+      chapters.push({ start: t, title: section.title || titleCase(section.id) })
+      const wav = join(audioDir, `${section.id}.wav`)
+      const dur = existsSync(wav) ? await ffprobeDuration(wav) : (missing++, 3)
+      t += STING_MS / 1000 + dur + TAIL_MS / 1000
+    }
+
+    const text = compose({ course, chapters, series })
+    const out = join(outDir, `${course.id}.txt`)
+    writeFileSync(out, text)
+    const warn = missing ? `  ⚠ ${missing} section(s) had no wav (3s fallback)` : ''
+    console.log(`✅ ${out}   (${chapters.length} chapters, ${stamp(t)} total)${warn}`)
+  }
+}
+
+main().catch((e) => { console.error('\n✗', e.message); process.exit(1) })

package/scripts/record-course.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// record-course.mjs — [STEP 3, 4K LANDSCAPE] one course → one 3840×2160 MP4 for YouTube.
+//
+//   node scripts/record-course.mjs <course> [--force] [--only <id[,id]>]
+//
+// Blueprint: ../../graphl-studio/aws/scripts/record-course.mjs — the concat-safe encode contract
+// (forced CFR + fixed timescale + gradfun deband + identical codec/pix/audio per segment so the
+// final `-c copy` join is glitch-free) is lifted verbatim. What's DIFFERENT here: this app is
+// SECTION-based, not beat-based — one section = one scene + one slide + one narration wav — so there
+// is no reveal fold, no seek/transition/pan machinery. Each section is just: navigate the hash to
+// its slug → wait for the painted, fitView-settled frame → hold for the clip → next.
+//
+// TRUE 4K (no fixed-stage trick): this app's layout is FLUID (react-flow fitView scales the scene
+// into its pane; the slide's useSlideScale zooms its 806px design width to the live pane), so we set
+// the puppeteer VIEWPORT directly to 3840×2160. page.screencast() records at the CSS viewport size
+// (it ignores deviceScaleFactor), so the frames are exactly 3840×2160 = 2160p, natively.
+//
+// THE BELL = the section SEPARATOR: a synthesized three-note brand bell plays as a lead-in at the
+// START of every section (the opening frame is held for STING_MS under the bell, then narration
+// begins). Bell-at-each-start → a bell between all nine sections, combined into one video.
+//
+// Timing is driven by the wav length (ffprobe), never by playback: a missing clip falls back to 3s
+// silence so the pipeline yields a video rather than hanging. Audio is read straight from
+// public/audio/<course>/<id>.wav on disk (same-repo), not fetched over HTTP.
+//
+// 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 } }
+
+// ---- 4K landscape frame -----------------------------------------------------------------
+const CW = process.env.WIDTH ? +process.env.WIDTH : 3840
+const CH = process.env.HEIGHT ? +process.env.HEIGHT : 2160
+const FPS = process.env.FPS ? +process.env.FPS : 30
+// A brief held tail after each section so it breathes and audio is never clipped at the join.
+const TAIL_MS = process.env.TAIL_MS ? +process.env.TAIL_MS : 500
+// The brand bell lead-in that opens (and so separates) each section. STING_MS=0 or NO_STING disables.
+const STING_MS = process.env.NO_STING ? 0 : process.env.STING_MS ? +process.env.STING_MS : 2800
+const STING_SIG = STING_MS > 0 ? `bell-arp:v1:${STING_MS}` : 'none'
+
+// Prefer a Homebrew ffmpeg (libx264 + gradfun deband kills dark-gradient banding on YouTube's codec);
+// fall back to Apple hardware, then plain ffmpeg.
+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 ?? '40M' // 4K needs more than 1080p's 16M
+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())
+}
+
+// Concatenate audio inputs into one mono 44.1 kHz WAV via the concat FILTER (per-input resample): the
+// bell bed is 44.1 kHz but a narration clip may be another rate, and the concat DEMUXER corrupts the
+// timeline on a mismatch. The filter resamples each input first, so the join is clean.
+async function concatAudio(inputs, dst) {
+  const inArgs = inputs.flatMap((f) => ['-i', f])
+  const chains = inputs.map((_, i) => `[${i}:a]aresample=44100[a${i}]`).join(';')
+  const joins = inputs.map((_, i) => `[a${i}]`).join('')
+  const filter = `${chains};${joins}concat=n=${inputs.length}:v=0:a=1[out]`
+  await run(FFMPEG, ['-y', ...inArgs, '-filter_complex', filter, '-map', '[out]', '-ar', '44100', '-ac', '1', dst])
+}
+
+// Render the brand bell once → bell.wav, and return a helper that pads/trims it to a lead of STING_MS
+// onto `dst`. No-op (returns null) when the sting is disabled.
+async function prepareBell(tmp) {
+  if (STING_MS <= 0) return null
+  const bell = join(tmp, 'bell.wav')
+  await run(FFMPEG, ['-y', '-filter_complex',
+    'sine=f=587.33:d=2.4:sample_rate=44100,afade=t=out:st=0:d=2.4:curve=exp[a];' +
+    'sine=f=880:d=2.4:sample_rate=44100,afade=t=out:st=0:d=2.4:curve=exp,adelay=200[b];' +
+    'sine=f=1174.66:d=2.4:sample_rate=44100,afade=t=out:st=0:d=2.4:curve=exp,adelay=400[c];' +
+    '[a][b][c]amix=inputs=3:normalize=0,volume=0.22,lowpass=f=3500,aformat=channel_layouts=mono',
+    '-t', '2.6', bell])
+  const secs = (STING_MS / 1000).toFixed(2)
+  return (dst) => run(FFMPEG, ['-y', '-i', bell, '-af', `apad,atrim=0:${secs}`, '-ar', '44100', '-ac', '1', dst])
+}
+
+// Mux one section's webm + audio → MP4 with CONCAT-SAFE settings so the final `-c copy` concat is
+// glitch-free: forced CFR, fixed video timescale, gradfun deband, and identical codec/pix/audio params
+// for every segment. `total` (bell lead + clip + tail) bounds both streams; apad fills the tail.
+async function encodeSegment(webm, audio, total, outMp4) {
+  const quality = IS_X26X ? ['-preset', PRESET, '-crf', CRF] : ['-b:v', BITRATE]
+  await run(FFMPEG, [
+    '-y', '-i', webm, '-i', audio,
+    '-map', '0:v:0', '-map', '1:a:0',
+    '-vf', 'gradfun=strength=0.9:radius=16',
+    '-r', String(FPS), '-vsync', 'cfr', '-video_track_timescale', '90000',
+    '-c:v', VIDEO_CODEC, ...quality, '-pix_fmt', 'yuv420p',
+    '-af', 'apad', '-t', total.toFixed(3),
+    '-c:a', 'aac', '-b:a', '192k', '-ar', '44100', '-ac', '1',
+    outMp4,
+  ])
+}
+
+// ---- the app dev server -----------------------------------------------------------------
+// Spawn `npm run dev` and resolve once Vite prints its Local URL. Set APP_URL to reuse a 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 — the deterministic
+// frame the reproducible-layout model depends on. A fresh goto per section forces a clean react-flow
+// remount (it keys on scene id), so there is never a stale prior scene in the 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 section records an
+// EMPTY webm (0 frames) and the mux fails. A 1px, ~1%-opacity speck nudged every animation frame
+// keeps frames flowing; at 4K that sub-perceptible pixel 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 recordCourse(course, { force = false, only = [] } = {}) {
+  const tmp = join(dataDir, '.tmp', course)
+  const segDir = join(dataDir, 'segments', course)
+  const outDir = join(dataDir, 'out')
+  for (const d of [tmp, segDir, outDir]) mkdirSync(d, { recursive: true })
+
+  const bellBed = await prepareBell(tmp)
+
+  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 segments = [] // ordered { mp4 } to concat
+  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' })
+
+    // The app lays out its own course for the recorder (slug + course + section id + scene per section).
+    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} sections @ ${CW}×${CH}\n`)
+
+    let n = 0
+    for (const sec of plan) {
+      n++
+      const tag = `${pad2(n)}-${sec.id}`
+      // --only RESTRICTS which segments are (re)recorded; a run with it refreshes those segments and
+      // SKIPS the final merge (a partial set can't concat into a whole video). A full run merges all.
+      if (only.length && !only.some((t) => sec.id.includes(t) || tag.includes(t))) continue
+      const segMp4 = join(segDir, `${tag}.mp4`)
+      const sidecar = join(segDir, `${tag}.json`)
+      const clip = join(tmp, `${tag}.wav`)
+
+      // Narration wav straight off disk (same repo). 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, sting: STING_SIG,
+      }))
+      const have = existsSync(segMp4) && existsSync(sidecar)
+      if (!(force || !have || readJson(sidecar)?.fp !== fp)) {
+        console.log(`  §${n} ${sec.id}  reuse`)
+        segments.push(segMp4)
+        continue
+      }
+
+      // Position → wait for the painted, framed frame → roll → hold (bell lead + clip + tail).
+      const total = STING_MS / 1000 + dur + TAIL_MS / 1000
+      await gotoSection(page, appBase, sec.slug)
+
+      const webm = join(tmp, `${tag}.webm`)
+      const recorder = await page.screencast({ path: webm })
+      await startKeepalive(page)
+      const lead = STING_MS > 0 ? `♪ ${(STING_MS / 1000).toFixed(1)}s + ` : ''
+      console.log(`  §${n} ${sec.id}  ▶ record (${lead}${dur.toFixed(1)}s)`)
+      await sleep(Math.round(total * 1000))
+      await recorder.stop()
+      await stopKeepalive(page)
+
+      // Segment audio: bell lead + this section's clip; mirrors the video hold.
+      let segAudio = clip
+      if (STING_MS > 0 && bellBed) {
+        const stingWav = join(tmp, `${tag}-sting.wav`)
+        await bellBed(stingWav)
+        segAudio = join(tmp, `${tag}-audio.wav`)
+        await concatAudio([stingWav, clip], segAudio)
+      }
+      await encodeSegment(webm, segAudio, total, segMp4)
+      writeFileSync(sidecar, JSON.stringify({ fp, builtAt: new Date().toISOString() }, null, 2))
+      segments.push(segMp4)
+      console.log(`  §${n} ${sec.id}  ✓ ${tag}.mp4`)
+    }
+  } finally {
+    if (browser) await browser.close()
+    if (server) server.child.kill('SIGTERM')
+  }
+
+  // A --only run refreshed just a subset of segments → there is no complete set to merge. Stop here;
+  // a later full run (no --only) reuses every unchanged segment and concatenates the whole course.
+  if (only.length) {
+    console.log(`\n✔ recorded ${segments.length} segment(s) (--only) — skipping merge. Run without --only to build ${course}.mp4.`)
+    return null
+  }
+
+  // Merge: concat demuxer + stream copy (uniform params → clean joins, seconds).
+  const listFile = join(tmp, 'concat.txt')
+  writeFileSync(listFile, segments.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join('\n') + '\n')
+  const out = join(outDir, `${course}.mp4`)
+  console.log(`\nMerging ${segments.length} segments → scripts/out/${course}.mp4`)
+  await run(FFMPEG, ['-y', '-f', 'concat', '-safe', '0', '-i', listFile, '-c', 'copy', '-movflags', '+faststart', out])
+  console.log(`\n✅ ${out}`)
+  return out
+}
+
+// ---- 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-course.mjs <course> [--force] [--only <id[,id]>]')
+  process.exit(2)
+}
+recordCourse(course, { force, only }).catch((e) => {
+  console.error('\n✗', e.message)
+  process.exit(1)
+})

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)
+})