@jokerized/decksmith 0.4.1 → 0.5.0

package/dist/index.js

@@ -1,12 +1,176 @@
 // src/index.ts
-import { cp, mkdir as mkdir10, readdir as readdir4, readFile as readFile17, stat as stat2, writeFile as writeFile12 } from "node:fs/promises";
-import { createRequire as createRequire4 } from "node:module";
-import { dirname as dirname5, join as join17, resolve as resolve6 } from "node:path";
+import { cp as cp2, mkdir as mkdir11, readFile as readFile18, writeFile as writeFile13 } from "node:fs/promises";
+import { createRequire as createRequire5 } from "node:module";
+import { dirname as dirname6, join as join18, resolve as resolve7 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/build/files.ts
+import { cp, mkdir as mkdir2, readdir, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join as join2, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// src/pack/media.ts
+// src/source/fonts.ts
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+function familyFor(lang) {
+  const tag = lang.toLowerCase();
+  if (tag.startsWith("ko")) return "Noto Sans KR";
+  if (tag.startsWith("ja")) return "Noto Sans JP";
+  if (tag.startsWith("zh")) return /hant|-tw|-hk|-mo/.test(tag) ? "Noto Sans TC" : "Noto Sans SC";
+  return null;
+}
+var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36";
+async function bundleFont(lang, glyphs, dir) {
+  const family = familyFor(lang);
+  if (!family) return null;
+  const text2 = [...new Set(glyphs)].filter((c) => c > " ").sort().join("");
+  const stamp = `/* decksmith ${createHash("sha256").update(`${family}
+${text2}`).digest("hex").slice(0, 16)} */`;
+  await mkdir(dir, { recursive: true });
+  const cssPath = join(dir, "fonts.css");
+  const cached2 = await readFile(cssPath, "utf8").catch(() => "");
+  if (cached2.startsWith(stamp)) return { family, css: cached2, files: localNames(cached2) };
+  const res = await fetch(
+    `https://fonts.googleapis.com/css2?family=${family.replaceAll(" ", "+")}:wght@400;500;700&text=${encodeURIComponent(text2)}&display=block`,
+    { headers: { "User-Agent": UA } }
+  );
+  if (!res.ok) throw new Error(`google fonts: HTTP ${res.status}`);
+  let css = await res.text();
+  const remote = [...new Set([...css.matchAll(/url\((https:[^)]+)\)/g)].map((m) => m[1] ?? ""))];
+  const slug = family.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const files = [];
+  for (const [i, url] of remote.entries()) {
+    const font = await fetch(url);
+    if (!font.ok) throw new Error(`${url}: HTTP ${font.status}`);
+    const name = `${slug}-${i}.woff2`;
+    await writeFile(join(dir, name), Buffer.from(await font.arrayBuffer()));
+    css = css.replaceAll(url, name);
+    files.push(name);
+  }
+  css = `${stamp}
+${css}`;
+  await writeFile(cssPath, css);
+  return { family, css, files };
+}
+function localNames(css) {
+  return [...css.matchAll(/url\(([^)]+)\)/g)].map((m) => m[1] ?? "");
+}
+
+// src/build/files.ts
+function audioNames(narration) {
+  return [
+    ...new Set(
+      Object.values(narration.beats).flat().map((s) => s.audio)
+    )
+  ].sort();
+}
+async function vendorKatex(out) {
+  const require2 = createRequire(import.meta.url);
+  const dist = join2(dirname(require2.resolve("katex/package.json")), "dist");
+  const css = await readFile2(join2(dist, "katex.min.css"), "utf8");
+  const written = [];
+  await mkdir2(join2(out, "katex/fonts"), { recursive: true });
+  for (const file of await readdir(join2(dist, "fonts"))) {
+    if (!file.endsWith(".woff2")) continue;
+    await cp(join2(dist, "fonts", file), join2(out, "katex/fonts", file));
+    written.push(join2(out, "katex/fonts", file));
+  }
+  const woff2Only = css.replace(/src:([^;}]*)/g, (whole, list) => {
+    const kept = list.split(",").filter((part) => part.includes(".woff2")).join(",");
+    return kept ? `src:${kept}` : whole;
+  });
+  await writeFile2(join2(out, "katex/katex.min.css"), woff2Only);
+  written.push(join2(out, "katex/katex.min.css"));
+  return written;
+}
+async function vendorScripts(out, composition) {
+  const require2 = createRequire(import.meta.url);
+  await mkdir2(join2(out, "vendor"), { recursive: true });
+  const wanted = (name) => composition.includes(`./vendor/${name}`);
+  const written = [];
+  for (const [pkg, rel, name] of [
+    ["gsap/package.json", "dist/gsap.min.js", "gsap.min.js"],
+    ["gsap/package.json", "dist/DrawSVGPlugin.min.js", "DrawSVGPlugin.min.js"],
+    ["gsap/package.json", "dist/MorphSVGPlugin.min.js", "MorphSVGPlugin.min.js"],
+    ["katex/package.json", "dist/katex.min.js", "katex.min.js"]
+  ]) {
+    if (!wanted(name)) continue;
+    const from = join2(dirname(require2.resolve(pkg)), rel);
+    await cp(from, join2(out, "vendor", name));
+    written.push(join2(out, "vendor", name));
+  }
+  if (wanted("ds-morph.js")) {
+    await cp(
+      fileURLToPath(new URL("./ds-morph.js", import.meta.url)),
+      join2(out, "vendor", "ds-morph.js")
+    );
+    written.push(join2(out, "vendor", "ds-morph.js"));
+  }
+  return written;
+}
+async function copyAssets(sourceDir, out, figures, step) {
+  const from = join2(resolve(sourceDir), "assets");
+  if (!await stat(from).catch(() => null)) {
+    step(`build: no assets/ beside source.json, skipping`);
+    return [];
+  }
+  const wanted = new Set(
+    figures.flatMap((f) => [f.src, f.poster]).filter((n3) => n3 !== void 0).map((n3) => n3.replace(/^\.?\//, ""))
+  );
+  await mkdir2(join2(out, "assets"), { recursive: true });
+  const written = [];
+  let copied = 0;
+  for (const name of wanted) {
+    const src = resolve(join2(from, name));
+    if (!src.startsWith(`${from}/`)) continue;
+    if (!await stat(src).catch(() => null)) continue;
+    await mkdir2(dirname(join2(out, "assets", name)), { recursive: true });
+    await cp(src, join2(out, "assets", name));
+    written.push(join2(out, "assets", name));
+    copied++;
+  }
+  const fonts = join2(from, "fonts");
+  if (await stat(fonts).catch(() => null)) {
+    await cp(fonts, join2(out, "assets", "fonts"), { recursive: true });
+    written.push(join2(out, "assets", "fonts"));
+  }
+  step(`build: copied ${copied} referenced figure(s)`);
+  return written;
+}
+async function copyAudio(from, narration, out, step) {
+  const dir = join2(out, narration.dir);
+  await mkdir2(dir, { recursive: true });
+  const names = audioNames(narration);
+  for (const name of names) {
+    await cp(join2(resolve(from), name), join2(dir, name)).catch(() => {
+      throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
+    });
+  }
+  step(`narration: ${names.length} audio file(s) \u2192 ${dir}`);
+  return names.map((n3) => join2(dir, n3));
+}
+async function refreshFont(storyboard, source, out, step) {
+  try {
+    const bundle = await bundleFont(
+      storyboard.lang,
+      JSON.stringify(source) + JSON.stringify(storyboard),
+      join2(out, "assets", "fonts")
+    );
+    if (bundle) step(`build: font bundle covers ${bundle.family}`);
+    return bundle?.css;
+  } catch (err) {
+    step(
+      `build: could not refresh the font bundle (${err instanceof Error ? err.message : err}); keeping the one from ingest`
+    );
+    return void 0;
+  }
+}
+
+// src/pack/media.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFile as readFile3 } from "node:fs/promises";
 import { extname } from "node:path";
 var PLAYERS = [
   "youtube.com",
@@ -180,7 +344,7 @@ function mediaSummary(plan) {
 }
 function bakedName(id2, url, mime) {
   const slug = id2.toLowerCase().replace(/[^a-z0-9_-]+/g, "-") || "asset";
-  const hash = createHash("sha256").update(url).digest("hex").slice(0, 8);
+  const hash = createHash2("sha256").update(url).digest("hex").slice(0, 8);
   return `${slug}-${hash}${extOf(url) || extFor(mime)}`;
 }
 function extOf(url) {
@@ -235,7 +399,7 @@ async function fetchAsset(url) {
       mime: res.headers.get("content-type") ?? void 0
     };
   }
-  return { bytes: new Uint8Array(await readFile(url)) };
+  return { bytes: new Uint8Array(await readFile3(url)) };
 }
 
 // src/types.ts
@@ -904,6 +1068,18 @@ var packSchema = z.object({
   narration: narrationSchema.optional(),
   media: z.array(mediaSchema).default([])
 });
+var CAPTION_FONT_RATIO = 0.037;
+var CAPTION_MARGIN_V_RATIO = 0.09;
+var CAPTION_MARGIN_X_RATIO = 0.04;
+var CAPTION_LINE_RATIO = 1.6;
+var CAPTION_MAX_LINES = 2;
+function captionFontSize(width) {
+  return Math.round(width * CAPTION_FONT_RATIO);
+}
+function bandReserve(width, height) {
+  const line2 = Math.round(captionFontSize(width) * CAPTION_LINE_RATIO);
+  return Math.round(height * CAPTION_MARGIN_V_RATIO) + CAPTION_MAX_LINES * line2;
+}
 var DESTINATIONS = {
   // A presented deck is paced by the person clicking through it, and long-form
   // video has no ceiling worth encoding. An empty list is "unbudgeted", stated.
@@ -1223,54 +1399,6 @@ function clock(seconds) {
   return m === 0 ? `${whole}s` : `${m}m${String(whole % 60).padStart(2, "0")}s`;
 }
 
-// src/source/fonts.ts
-import { createHash as createHash2 } from "node:crypto";
-import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-function familyFor(lang) {
-  const tag = lang.toLowerCase();
-  if (tag.startsWith("ko")) return "Noto Sans KR";
-  if (tag.startsWith("ja")) return "Noto Sans JP";
-  if (tag.startsWith("zh")) return /hant|-tw|-hk|-mo/.test(tag) ? "Noto Sans TC" : "Noto Sans SC";
-  return null;
-}
-var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36";
-async function bundleFont(lang, glyphs, dir) {
-  const family = familyFor(lang);
-  if (!family) return null;
-  const text2 = [...new Set(glyphs)].filter((c) => c > " ").sort().join("");
-  const stamp = `/* decksmith ${createHash2("sha256").update(`${family}
-${text2}`).digest("hex").slice(0, 16)} */`;
-  await mkdir(dir, { recursive: true });
-  const cssPath = join(dir, "fonts.css");
-  const cached2 = await readFile2(cssPath, "utf8").catch(() => "");
-  if (cached2.startsWith(stamp)) return { family, css: cached2, files: localNames(cached2) };
-  const res = await fetch(
-    `https://fonts.googleapis.com/css2?family=${family.replaceAll(" ", "+")}:wght@400;500;700&text=${encodeURIComponent(text2)}&display=block`,
-    { headers: { "User-Agent": UA } }
-  );
-  if (!res.ok) throw new Error(`google fonts: HTTP ${res.status}`);
-  let css = await res.text();
-  const remote = [...new Set([...css.matchAll(/url\((https:[^)]+)\)/g)].map((m) => m[1] ?? ""))];
-  const slug = family.toLowerCase().replace(/[^a-z0-9]/g, "");
-  const files = [];
-  for (const [i, url] of remote.entries()) {
-    const font = await fetch(url);
-    if (!font.ok) throw new Error(`${url}: HTTP ${font.status}`);
-    const name = `${slug}-${i}.woff2`;
-    await writeFile(join(dir, name), Buffer.from(await font.arrayBuffer()));
-    css = css.replaceAll(url, name);
-    files.push(name);
-  }
-  css = `${stamp}
-${css}`;
-  await writeFile(cssPath, css);
-  return { family, css, files };
-}
-function localNames(css) {
-  return [...css.matchAll(/url\(([^)]+)\)/g)].map((m) => m[1] ?? "");
-}
-
 // src/emit/kit.ts
 var PAD_X = 110;
 var PAD_Y = 84;
@@ -1289,7 +1417,12 @@ function contentW(format) {
   return refWidth(format) - 2 * PAD_X;
 }
 function contentH(format) {
-  return refHeight(format) - 2 * PAD_Y;
+  return refHeight(format) - 2 * PAD_Y - reserveRef(format);
+}
+function reserveRef(format) {
+  const reserve = format.captionReserve ?? 0;
+  if (reserve <= 0) return 0;
+  return Math.ceil(reserve * refHeight(format) / format.height);
 }
 function raw(js2) {
   return { __raw: js2 };
@@ -1788,8 +1921,8 @@ function charUnits(c, tabular, cjkRun, hangul) {
   }
   const measured = ADVANCE[c];
   if (measured !== void 0) return [measured, true];
-  const cp2 = c.codePointAt(0) ?? 0;
-  for (const [lo, hi, units] of BLOCK_ADVANCE) if (cp2 >= lo && cp2 <= hi) return [units, false];
+  const cp3 = c.codePointAt(0) ?? 0;
+  for (const [lo, hi, units] of BLOCK_ADVANCE) if (cp3 >= lo && cp3 <= hi) return [units, false];
   return [UNMEASURED, true];
 }
 function weightFactor(weight) {
@@ -2050,11 +2183,16 @@ function baseCss(theme, format) {
          gate still catches anything taller than the canvas; it just now
          overflows symmetrically instead of only downwards. */
       .scene { position: absolute; top: 0; left: 0; width: 100%; height: 100%;
-               padding: ${PAD_Y}px ${PAD_X}px; display: flex; flex-direction: column;
+               padding: ${scenePadding(format)}; display: flex; flex-direction: column;
                justify-content: center; }
 ${referenceSpaceCss(format)}
 ${AMBIENT_KEYFRAMES}`;
 }
+function scenePadding(format) {
+  const reserve = reserveRef(format);
+  const base = `${PAD_Y}px ${PAD_X}px`;
+  return reserve > 0 ? `${base} ${PAD_Y + reserve}px` : base;
+}
 function referenceSpaceCss(format) {
   const zoom = zoomOf(format);
   if (zoom === 1) return "";
@@ -6385,6 +6523,10 @@ function planTiming(input) {
     lang: storyboard.lang,
     audioDir: segments2.length > 0 ? narration?.dir ?? "" : "",
     voice: segments2.length > 0 ? narration?.voice ?? "" : "",
+    // The format the deck was LAID OUT under, which is the only honest source:
+    // `emitDeck` and `writeTiming` are handed the same `format`, so this cannot
+    // disagree with the box the archetypes actually drew into.
+    captionReserve: format.captionReserve ?? 0,
     scenes,
     segments: segments2
   };
@@ -6677,8 +6819,8 @@ function textOf(node) {
 
 // src/source/harvest.ts
 import { createHash as createHash5 } from "node:crypto";
-import { copyFile, mkdir as mkdir4, rm as rm2, stat, writeFile as writeFile4 } from "node:fs/promises";
-import { basename as basename2, join as join4, resolve } from "node:path";
+import { copyFile, mkdir as mkdir5, rm as rm2, stat as stat2, writeFile as writeFile5 } from "node:fs/promises";
+import { basename as basename2, join as join5, resolve as resolve2 } from "node:path";
 
 // src/net/fetch.ts
 import { lookup as resolveHost } from "node:dns/promises";
@@ -6688,8 +6830,8 @@ import { isIP } from "node:net";
 import { brotliDecompressSync, gunzipSync } from "node:zlib";
 
 // src/version.ts
-import { createRequire } from "node:module";
-var VERSION = createRequire(import.meta.url)("../package.json").version;
+import { createRequire as createRequire2 } from "node:module";
+var VERSION = createRequire2(import.meta.url)("../package.json").version;
 
 // src/net/fetch.ts
 var BLOCKED_V4 = [
@@ -6884,8 +7026,8 @@ async function send(url, target, headers, signal, opts) {
     ...secure && isIP(host) === 0 ? { servername: host } : {}
   };
   try {
-    return await new Promise((resolve7, reject) => {
-      const req = (secure ? httpsRequest : httpRequest)(options, resolve7);
+    return await new Promise((resolve8, reject) => {
+      const req = (secure ? httpsRequest : httpRequest)(options, resolve8);
       req.on("error", reject);
       req.end();
     });
@@ -6968,10 +7110,10 @@ function message(err) {
 }
 
 // src/render/capture.ts
-import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { createRequire as createRequire2 } from "node:module";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { createRequire as createRequire3 } from "node:module";
 import { homedir } from "node:os";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 import { pathToFileURL } from "node:url";
 async function resolveChrome(need = "open the deck with") {
   const env = process.env.HYPERFRAMES_BROWSER_PATH || process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
@@ -6982,9 +7124,9 @@ async function resolveChrome(need = "open the deck with") {
     const ordered = [...installed2].sort((a, b) => b.buildId.localeCompare(a.buildId, "en"));
     return ordered.find((b) => b.browser === "chrome-headless-shell") ?? ordered.find((b) => b.browser === "chrome");
   };
-  const hf = await pick(join2(homedir(), ".cache", "hyperframes", "chrome"));
+  const hf = await pick(join3(homedir(), ".cache", "hyperframes", "chrome"));
   if (hf) return { path: hf.executablePath, source: "hyperframes" };
-  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join2(homedir(), ".cache", "puppeteer"));
+  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join3(homedir(), ".cache", "puppeteer"));
   if (pup) return { path: pup.executablePath, source: "puppeteer" };
   throw new Error(
     `no Chrome to ${need} \u2014 run \`npx puppeteer browsers install chrome\`, or set DECKSMITH_CHROME to a Chrome binary.`
@@ -6994,15 +7136,15 @@ async function chromePath(need = "open the deck with") {
   return (await resolveChrome(need)).path;
 }
 function runtimePath() {
-  return createRequire2(import.meta.url).resolve("hyperframes/dist/hyperframe.runtime.iife.js");
+  return createRequire3(import.meta.url).resolve("hyperframes/dist/hyperframe.runtime.iife.js");
 }
 function renderSeek(t2) {
   const player = window.__player;
   player.renderSeek(t2, { suppressEvents: true });
 }
 async function openDeck(dir, opts = {}) {
-  const index = join2(dir, "index.html");
-  const html = await readFile3(index, "utf8").catch(() => null);
+  const index = join3(dir, "index.html");
+  const html = await readFile4(index, "utf8").catch(() => null);
   if (html === null) throw new Error(`no index.html in ${dir}`);
   const width = Number(/data-width="(\d+)"/.exec(html)?.[1] ?? 0);
   const height = Number(/data-height="(\d+)"/.exec(html)?.[1] ?? 0);
@@ -7080,13 +7222,13 @@ async function openDeck(dir, opts = {}) {
 
 // src/source/assets.ts
 import { createHash as createHash4 } from "node:crypto";
-import { mkdir as mkdir3, readdir, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
-import { extname as extname2, join as join3 } from "node:path";
+import { mkdir as mkdir4, readdir as readdir2, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
+import { extname as extname2, join as join4 } from "node:path";
 import { z as z2 } from "zod";
 async function fetchFigures(source, dir, warnings) {
   const drops = warnings ?? [];
-  await mkdir3(dir, { recursive: true });
-  const cached2 = await readdir(dir).catch(() => []);
+  await mkdir4(dir, { recursive: true });
+  const cached2 = await readdir2(dir).catch(() => []);
   const figures = [];
   for (const figure of source.figures) {
     if (figure.kind === "clip") {
@@ -7111,11 +7253,11 @@ async function fetchFigures(source, dir, warnings) {
 async function localize(figure, dir, cached2) {
   const stem = assetStem(figure.id, figure.src);
   const hit = cached2.find((name) => name.startsWith(`${stem}.`));
-  const bytes = hit ? await readFile4(join3(dir, hit)) : await load(figure.src);
+  const bytes = hit ? await readFile5(join4(dir, hit)) : await load(figure.src);
   const size2 = imageSize(bytes);
   if (hit) return { ...figure, src: hit, ...size2 };
   const src = `${stem}${assetExt(bytes, figure.src)}`;
-  await writeFile3(join3(dir, src), bytes);
+  await writeFile4(join4(dir, src), bytes);
   cached2.push(src);
   return { ...figure, src, ...size2 };
 }
@@ -7140,7 +7282,7 @@ function assetExt(bytes, src) {
 var FIGURE_MAX_BYTES = 32 * 1024 * 1024;
 var FIGURE_TIMEOUT_MS = 2e4;
 async function load(src) {
-  if (!/^https?:/i.test(src)) return readFile4(src);
+  if (!/^https?:/i.test(src)) return readFile5(src);
   const got = await fetchGuarded(src, {
     maxBytes: FIGURE_MAX_BYTES,
     timeoutMs: FIGURE_TIMEOUT_MS
@@ -7676,7 +7818,7 @@ function readContentRegion() {
 }
 
 // src/source/transcode.ts
-import { readFile as readFile5, rm } from "node:fs/promises";
+import { readFile as readFile6, rm } from "node:fs/promises";
 import { basename } from "node:path";
 
 // src/render/ffmpeg.ts
@@ -7702,7 +7844,7 @@ ${tail3}`);
   }
 }
 function runLive(file, args) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = spawn(file, args, { stdio: ["ignore", "inherit", "inherit"] });
     child.on("error", (err) => {
       reject(
@@ -7710,7 +7852,7 @@ function runLive(file, args) {
       );
     });
     child.on("close", (code, signal) => {
-      if (code === 0) resolve7();
+      if (code === 0) resolve8();
       else if (signal) {
         reject(
           new Error(
@@ -7837,11 +7979,16 @@ function burnStyle(width, height, font = "Arial") {
     // here is 978px. F = 40 leaves 9% of headroom; F = 45 — which is what
     // "4% of the width" looked like on paper — overflows to a THIRD line, and a
     // three-line band covers the bottom of the slide.
-    fontSize: Math.round(width * 0.037),
+    //
+    // THE RATIOS ARE NOT HERE. They are in src/types.ts beside `bandReserve`,
+    // because `src/emit` has to reserve exactly the strip this draws into and
+    // may not import this file. A local copy of 0.037 is how the two drift back
+    // apart, which is the bug this whole path exists to close.
+    fontSize: captionFontSize(width),
     // Clear of the play button, the progress bar and the handle every vertical
     // player draws across the bottom eighth of the frame.
-    marginV: Math.round(height * 0.09),
-    marginX: Math.round(width * 0.04)
+    marginV: Math.round(height * CAPTION_MARGIN_V_RATIO),
+    marginX: Math.round(width * CAPTION_MARGIN_X_RATIO)
   };
 }
 
@@ -7907,7 +8054,7 @@ async function transcode(input, out, opts = {}) {
   const maxSeconds = opts.maxSeconds ?? MAX_CLIP_SECONDS;
   const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS;
   const name = basename(input);
-  const source = videoSize(await readFile5(input));
+  const source = videoSize(await readFile6(input));
   const box = fitBox(source.width, source.height, opts.maxEdgePx ?? CLIP_EDGE_PX);
   const kept = (why3) => ({
     path: input,
@@ -7939,7 +8086,7 @@ async function transcode(input, out, opts = {}) {
   }
   let measured;
   try {
-    measured = videoSize(await readFile5(out));
+    measured = videoSize(await readFile6(out));
   } catch (err) {
     await rm(out, { force: true });
     return kept(
@@ -7975,8 +8122,8 @@ var HTML_TYPES = /^text\/html$|^application\/xhtml\+xml$/;
 async function harvest(url, dir, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS2;
   const warnings = [];
-  const assets = resolve(dir);
-  await mkdir4(assets, { recursive: true });
+  const assets = resolve2(dir);
+  await mkdir5(assets, { recursive: true });
   const page = await fetchGuarded(url, {
     maxBytes: opts.maxBytes ?? HTML_MAX_BYTES,
     timeoutMs,
@@ -8358,8 +8505,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
           `it is ${size2.width}x${size2.height}, under ${MIN_FIGURE_PX}px \u2014 spacers, icons and tracking pixels look like this, and a slide cannot use one`
         );
       }
-      const path2 = join4(dir, assetName(url, extFor2(sniffFormat(bytes))));
-      await writeFile4(path2, bytes);
+      const path2 = join5(dir, assetName(url, extFor2(sniffFormat(bytes))));
+      await writeFile5(path2, bytes);
       assets.push(path2);
       got = { path: path2, width: size2.width, height: size2.height };
     } catch (err) {
@@ -8371,7 +8518,7 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
   };
   const shrink = async (url, path2, measured, what) => {
     if (opts.transcode === false) return { path: path2, ...measured };
-    const out2 = join4(dir, assetName(url, ".vp9.webm"));
+    const out2 = join5(dir, assetName(url, ".vp9.webm"));
     let small;
     try {
       small = await transcode(path2, out2, {
@@ -8413,8 +8560,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
     try {
       const bytes = await bytesOf(url);
       const measured = videoSize(bytes);
-      const path2 = join4(dir, assetName(url, `.${measured.container}`));
-      await writeFile4(path2, bytes);
+      const path2 = join5(dir, assetName(url, `.${measured.container}`));
+      await writeFile5(path2, bytes);
       return await shrink(url, path2, measured, what);
     } catch (err) {
       warnings.push(`${what} was not downloaded: ${url} \u2014 ${why(err)}`);
@@ -8503,7 +8650,7 @@ function unheld(policy) {
   return "the file could not be held";
 }
 async function sizeOf(path2) {
-  return await stat(path2).then(
+  return await stat2(path2).then(
     (s) => s.size,
     () => 0
   );
@@ -8711,8 +8858,8 @@ function sane(seconds) {
 }
 async function attachClips(source, clips, dir) {
   if (clips.length === 0) return source;
-  const assets = resolve(dir);
-  await mkdir4(assets, { recursive: true });
+  const assets = resolve2(dir);
+  await mkdir5(assets, { recursive: true });
   const figures = [...source.figures];
   for (const clip3 of clips) {
     const src = clip3.file ? await adopt(clip3.file, assets) : void 0;
@@ -8743,7 +8890,7 @@ async function attachClips(source, clips, dir) {
 }
 async function adopt(file, dir) {
   const name = basename2(file);
-  await copyFile(file, join4(dir, name));
+  await copyFile(file, join5(dir, name));
   return name;
 }
 function freeId(figures) {
@@ -8820,9 +8967,9 @@ ${fence}`;
 
 // src/plan/codex.ts
 import { spawn as spawn2 } from "node:child_process";
-import { mkdtemp, readFile as readFile6, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { mkdtemp, readFile as readFile7, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 import { z as z3 } from "zod";
 
 // src/plan/arc.ts
@@ -9941,11 +10088,11 @@ function schemaFor(prefs) {
 var SCHEMA = schemaFor({ genre: "general" });
 async function codexPlanner(source, opts = {}) {
   const prefs = opts.prefs ?? prefsSchema.parse({});
-  const dir = await mkdtemp(join5(tmpdir(), "decksmith-plan-"));
+  const dir = await mkdtemp(join6(tmpdir(), "decksmith-plan-"));
   try {
-    const schemaPath = join5(dir, "storyboard.schema.json");
-    const outPath = join5(dir, "storyboard.json");
-    await writeFile5(schemaPath, JSON.stringify(schemaFor(prefs)));
+    const schemaPath = join6(dir, "storyboard.schema.json");
+    const outPath = join6(dir, "storyboard.json");
+    await writeFile6(schemaPath, JSON.stringify(schemaFor(prefs)));
     await (opts.run ?? runCodex)({
       prompt: buildPrompt(source, prefs),
       schemaPath,
@@ -9953,7 +10100,7 @@ async function codexPlanner(source, opts = {}) {
       ...opts.model === void 0 ? {} : { model: opts.model },
       timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2
     });
-    const raw2 = await readFile6(outPath, "utf8").catch(() => "");
+    const raw2 = await readFile7(outPath, "utf8").catch(() => "");
     if (raw2.trim() === "") {
       throw new Error("Codex produced no final message. Re-run, or try a shorter source.");
     }
@@ -10026,7 +10173,7 @@ function codexCommand(args) {
 }
 function runCodex(args) {
   const { argv, env } = codexCommand(args);
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = spawn2("codex", argv, {
       stdio: ["pipe", "ignore", "pipe"],
       ...env === void 0 ? {} : { env }
@@ -10049,7 +10196,7 @@ function runCodex(args) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (code === 0) return resolve7();
+      if (code === 0) return resolve8();
       reject(
         new Error(`codex exec exited ${code}.
 ${stderr.trim().split("\n").slice(-8).join("\n")}`)
@@ -10061,14 +10208,14 @@ ${stderr.trim().split("\n").slice(-8).join("\n")}`)
 
 // src/images/illustrate.ts
 import { createHash as createHash7 } from "node:crypto";
-import { mkdir as mkdir5, readFile as readFile8, rename, rm as rm5, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile9, rename, rm as rm5, writeFile as writeFile8 } from "node:fs/promises";
+import { join as join8 } from "node:path";
 
 // src/images/providers.ts
 import { createHash as createHash6 } from "node:crypto";
-import { mkdtemp as mkdtemp2, readFile as readFile7, rm as rm4, writeFile as writeFile6 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, readFile as readFile8, rm as rm4, writeFile as writeFile7 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join6, resolve as resolve2 } from "node:path";
+import { join as join7, resolve as resolve3 } from "node:path";
 import { z as z4 } from "zod";
 var SIZE = {
   landscape: { width: 1536, height: 1024 },
@@ -10200,11 +10347,11 @@ function codexImages(opts = {}) {
     async check() {
     },
     async generate(req) {
-      const dir = await mkdtemp2(join6(tmpdir2(), "decksmith-image-"));
+      const dir = await mkdtemp2(join7(tmpdir2(), "decksmith-image-"));
       try {
-        const schemaPath = join6(dir, "answer.schema.json");
-        const outPath = join6(dir, "answer.json");
-        await writeFile6(schemaPath, JSON.stringify(ANSWER_SCHEMA));
+        const schemaPath = join7(dir, "answer.schema.json");
+        const outPath = join7(dir, "answer.json");
+        await writeFile7(schemaPath, JSON.stringify(ANSWER_SCHEMA));
         await run4({
           prompt: codexPrompt(req),
           schemaPath,
@@ -10213,7 +10360,7 @@ function codexImages(opts = {}) {
           cwd: dir,
           sandbox: "workspace-write"
         });
-        const raw2 = await readFile7(outPath, "utf8").catch(() => "");
+        const raw2 = await readFile8(outPath, "utf8").catch(() => "");
         const answer = answerSchema.safeParse(parseJson(Buffer.from(raw2)));
         if (!answer.success) throw new Error("codex could not generate a picture: no final answer");
         if (!answer.data.ok) {
@@ -10221,10 +10368,10 @@ function codexImages(opts = {}) {
             `codex could not generate a picture: ${answer.data.reason ?? "no reason given"}`
           );
         }
-        const candidates2 = [join6(dir, "picture.png")];
-        if (answer.data.file) candidates2.push(resolve2(dir, answer.data.file));
+        const candidates2 = [join7(dir, "picture.png")];
+        if (answer.data.file) candidates2.push(resolve3(dir, answer.data.file));
         for (const path2 of candidates2) {
-          const bytes = await readFile7(path2).catch(() => null);
+          const bytes = await readFile8(path2).catch(() => null);
           if (bytes) return raster(bytes, "codex");
         }
         throw new Error("codex said ok but wrote no picture.png");
@@ -10356,7 +10503,7 @@ async function illustrate(storyboard, source, opts) {
   const tool = last?.id === "svg" ? last : toolSvg();
   if (tool !== last) chain.push(tool);
   const dropped = /* @__PURE__ */ new Set();
-  if (pending.length > 0) await mkdir5(opts.assetsDir, { recursive: true });
+  if (pending.length > 0) await mkdir6(opts.assetsDir, { recursive: true });
   for (const [i, slot] of pending.entries()) {
     let rungs = chain;
     if (i >= images.max) {
@@ -10453,16 +10600,16 @@ function cacheKey(providerId, req) {
 async function draw(provider, req, name, dir) {
   for (const ext of Object.values(EXT2)) {
     const src2 = `${name}${ext}`;
-    const bytes = await readFile8(join7(dir, src2)).catch(() => null);
+    const bytes = await readFile9(join8(dir, src2)).catch(() => null);
     if (bytes) return { src: src2, ...sizeOf2(bytes, ext), cached: true };
   }
   await provider.check();
   const img = await provider.generate(req);
   const src = `${name}${EXT2[img.mime]}`;
-  const tmp = join7(dir, `.${name}.tmp`);
+  const tmp = join8(dir, `.${name}.tmp`);
   try {
-    await writeFile7(tmp, img.bytes);
-    await rename(tmp, join7(dir, src));
+    await writeFile8(tmp, img.bytes);
+    await rename(tmp, join8(dir, src));
   } finally {
     await rm5(tmp, { force: true });
   }
@@ -10475,9 +10622,9 @@ function sizeOf2(bytes, ext) {
 // src/narrate/tts.ts
 import { spawn as spawn3 } from "node:child_process";
 import { createHash as createHash8 } from "node:crypto";
-import { mkdir as mkdir6, readFile as readFile9, rm as rm6, writeFile as writeFile8 } from "node:fs/promises";
+import { mkdir as mkdir7, readFile as readFile10, rm as rm6, writeFile as writeFile9 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 var MISSING = [
   "edge-tts is not installed, so narration cannot be synthesised.",
   "",
@@ -10494,8 +10641,8 @@ function candidates() {
     ["edge-tts"],
     // pip --user on macOS and on Linux respectively. Neither is on PATH by
     // default, and both are where this actually lands in practice.
-    [join8(home, "Library", "Python", "3.9", "bin", "edge-tts")],
-    [join8(home, ".local", "bin", "edge-tts")],
+    [join9(home, "Library", "Python", "3.9", "bin", "edge-tts")],
+    [join9(home, ".local", "bin", "edge-tts")],
     // Last resort: the module is installed even though its console script is
     // nowhere findable, which is the normal state of a pip --user install.
     ["python3", "-m", "edge_tts"]
@@ -10520,7 +10667,7 @@ async function find2(can) {
   throw new Error(MISSING);
 }
 function runArgv(cmd, args) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     const child = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
@@ -10530,8 +10677,8 @@ function runArgv(cmd, args) {
     child.stderr.on("data", (b) => {
       stderr += b.toString();
     });
-    child.on("error", (e) => resolve7({ code: -1, stderr: String(e), stdout }));
-    child.on("close", (code) => resolve7({ code: code ?? -1, stderr, stdout }));
+    child.on("error", (e) => resolve8({ code: -1, stderr: String(e), stdout }));
+    child.on("close", (code) => resolve8({ code: code ?? -1, stderr, stdout }));
   });
 }
 var edgeTts = {
@@ -10598,7 +10745,7 @@ function edgeProvider(runner = edgeTts) {
     async speak(req) {
       const subs = `${req.audio.replace(/\.mp3$/, "")}.srt`;
       await runner.speak({ ...req, subs });
-      const raw2 = await readFile9(subs, "utf8").catch(() => "");
+      const raw2 = await readFile10(subs, "utf8").catch(() => "");
       await rm6(subs, { force: true });
       const cues = parseCues(raw2);
       const measured = await runner.measure(req.audio);
@@ -10628,11 +10775,11 @@ async function synthesize(text2, opts) {
   const provider = opts.provider ?? edgeProvider(opts.runner ?? edgeTts);
   const key = cacheKey2(text2, opts.voice, rate, pitch);
   const file = `${key}.mp3`;
-  const audio = join8(opts.dir, file);
-  const sidecar = join8(opts.dir, `${key}.json`);
+  const audio = join9(opts.dir, file);
+  const sidecar = join9(opts.dir, `${key}.json`);
   const cached2 = await readSidecar(sidecar);
   if (cached2) return { audio, file, seconds: cached2.seconds, cues: cached2.cues };
-  await mkdir6(opts.dir, { recursive: true });
+  await mkdir7(opts.dir, { recursive: true });
   const spoken = await provider.speak({ text: text2, voice: opts.voice, rate, pitch, audio });
   const { cues, seconds } = spoken;
   const clamped = cues.map((c) => ({
@@ -10641,13 +10788,13 @@ async function synthesize(text2, opts) {
     text: c.text
   }));
   const body = { seconds, cues: clamped, text: text2, voice: opts.voice };
-  await writeFile8(sidecar, `${JSON.stringify(body, null, 2)}
+  await writeFile9(sidecar, `${JSON.stringify(body, null, 2)}
 `);
   return { audio, file, seconds, cues: clamped };
 }
 async function readSidecar(path2) {
   try {
-    const parsed = JSON.parse(await readFile9(path2, "utf8"));
+    const parsed = JSON.parse(await readFile10(path2, "utf8"));
     const s = parsed;
     return typeof s?.seconds === "number" && s.seconds > 0 && Array.isArray(s.cues) ? s : null;
   } catch {
@@ -10770,8 +10917,8 @@ async function narrate(storyboard, source, prefs, opts) {
 }
 
 // src/verify/index.ts
-import { readdir as readdir3, readFile as readFile13 } from "node:fs/promises";
-import { join as join12, relative, sep } from "node:path";
+import { readdir as readdir4, readFile as readFile14 } from "node:fs/promises";
+import { join as join13, relative, sep } from "node:path";
 
 // src/verify/budget.ts
 function readCanvas(html) {
@@ -10878,8 +11025,8 @@ function clock2(seconds) {
 
 // src/verify/check.ts
 import { execFile as execFile2 } from "node:child_process";
-import { readFile as readFile10 } from "node:fs/promises";
-import { join as join9 } from "node:path";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join10 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 var run2 = promisify2(execFile2);
 var DEFAULT_TIMEOUT_MS3 = 24e4;
@@ -10909,7 +11056,7 @@ async function check(dir, opts = {}) {
 async function readComposition(dir) {
   let html;
   try {
-    html = await readFile10(join9(dir, "index.html"), "utf8");
+    html = await readFile11(join10(dir, "index.html"), "utf8");
   } catch {
     return { transit: [], duration: 0 };
   }
@@ -11060,8 +11207,8 @@ function tail(s) {
 }
 
 // src/verify/fidelity.ts
-import { readFile as readFile11 } from "node:fs/promises";
-import { join as join10 } from "node:path";
+import { readFile as readFile12 } from "node:fs/promises";
+import { join as join11 } from "node:path";
 
 // src/verify/typefloor.ts
 var TYPE_FLOOR_PX = 40;
@@ -11317,6 +11464,16 @@ var INK_FLOOR = 15e-4;
 var INK_DELTA = 12;
 var FALLBACK_BAND_TOP = 0.22;
 var CAPTION = ".headline, .eyebrow";
+var RESERVE_INK_TOLERANCE = 1e-4;
+function readReserve(timingText) {
+  if (!timingText) return 0;
+  try {
+    const reserve = JSON.parse(timingText).captionReserve;
+    return typeof reserve === "number" && reserve > 0 ? reserve : 0;
+  } catch {
+    return 0;
+  }
+}
 async function decodePng(png) {
   const buf = Buffer.from(png.buffer, png.byteOffset, png.byteLength);
   if (buf.length < 8 || buf.readUInt32BE(0) !== 2303741511) throw new Error("not a PNG");
@@ -11483,6 +11640,25 @@ function gradeFidelity(rows, floor = INK_FLOOR) {
     };
   });
 }
+function gradeReserve(rows, tolerance = RESERVE_INK_TOLERANCE) {
+  const dirty = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.reserveInk === void 0 || row.reserveInk <= tolerance) continue;
+    const seen = dirty.get(row.sid);
+    if (seen) seen.push(row);
+    else dirty.set(row.sid, [row]);
+  }
+  const pct = (v) => `${(100 * v).toFixed(3)}%`;
+  return [...dirty].map(([sid, stops]) => {
+    const worst = stops.reduce((a, b) => (a.reserveInk ?? 0) >= (b.reserveInk ?? 0) ? a : b);
+    return {
+      severity: "error",
+      gate: "fidelity",
+      rule: "ink_in_caption_reserve",
+      message: `#${sid} draws into the caption reserve ${stops.length === 1 ? "" : `at ${stops.length} stops `}\u2014 ${pct(worst.reserveInk ?? 0)} of the frame is ink inside the band at t=${worst.t}s (tolerance ${pct(tolerance)}). A burned caption would sit on top of it. Times: ${stops.map((s) => `${s.t}s`).join(", ")}.`
+    };
+  });
+}
 function captionBottom(sid, selector, fallbackPx) {
   const scene = document.querySelector(`[data-composition-id="${CSS.escape(sid)}"]`);
   let bottom = 0;
@@ -11507,11 +11683,10 @@ async function fidelity(dir, opts = {}) {
     ],
     elapsedMs: Date.now() - started
   });
-  const stops = opts.stops ?? readStops(
-    await readFile11(join10(dir, TIMING_FILE), "utf8").catch(() => null),
-    await readFile11(join10(dir, DECK_PAGE), "utf8").catch(() => null)
-  );
+  const timingText = await readFile12(join11(dir, TIMING_FILE), "utf8").catch(() => null);
+  const stops = opts.stops ?? readStops(timingText, await readFile12(join11(dir, DECK_PAGE), "utf8").catch(() => null));
   if (stops.length === 0) return notMeasured("the deck declares no stops");
+  const reserve = opts.captionReserve ?? readReserve(timingText);
   let deck = null;
   try {
     deck = await openDeck(dir, { timeoutMs: opts.timeoutMs });
@@ -11540,7 +11715,13 @@ async function fidelity(dir, opts = {}) {
       measured.push({
         ...stop,
         ink: inkBelow(frame, bandTopPx),
-        bandTop: Math.round(1e3 * bandTopPx / height) / 1e3
+        bandTop: Math.round(1e3 * bandTopPx / height) / 1e3,
+        // THE SAME FRAME, a second strip. Free: it is one more pass over pixels
+        // that are already decoded, so the gate that stops the caption
+        // collision regressing costs no extra capture, no extra seek and no
+        // extra browser. That matters — a gate with its own capture is a gate
+        // someone turns off.
+        ...reserve > 0 ? { reserveInk: inkBelow(frame, height - reserve) } : {}
       });
     }
     for (const mid of midpoints(stops)) {
@@ -11551,6 +11732,7 @@ async function fidelity(dir, opts = {}) {
       stops: measured,
       findings: [
         ...gradeFidelity(measured, floor),
+        ...gradeReserve(measured),
         ...gradeOverprint(collided),
         ...gradeApparent(apparent)
       ],
@@ -11567,9 +11749,9 @@ async function fidelity(dir, opts = {}) {
 // src/verify/drift.ts
 import { execFile as execFile3 } from "node:child_process";
 import { createHash as createHash9 } from "node:crypto";
-import { mkdtemp as mkdtemp3, readdir as readdir2, readFile as readFile12, rm as rm7 } from "node:fs/promises";
+import { mkdtemp as mkdtemp3, readdir as readdir3, readFile as readFile13, rm as rm7 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 import { promisify as promisify3 } from "node:util";
 var run3 = promisify3(execFile3);
 var FLOOR_DB = 40;
@@ -11608,9 +11790,9 @@ function measureMotion(hashes, scenes, seconds) {
 async function drift(dir, opts = {}) {
   const mode = opts.mode ?? "psnr";
   const floorDb = opts.floorDb ?? FLOOR_DB;
-  const work = opts.workDir ?? await mkdtemp3(join11(tmpdir3(), "decksmith-drift-"));
-  const a = join11(work, "a");
-  const b = join11(work, "b");
+  const work = opts.workDir ?? await mkdtemp3(join12(tmpdir3(), "decksmith-drift-"));
+  const a = join12(work, "a");
+  const b = join12(work, "b");
   const report = await compare(dir, a, b, mode, floorDb, opts);
   const keep = opts.keep || !report.passed;
   if (keep) report.kept = { a, b };
@@ -11665,11 +11847,11 @@ async function compare(dir, a, b, mode, floorDb, opts) {
   const differing = [];
   const ha = [];
   for (const [i, name] of fa.entries()) {
-    const one = await sha(join11(a, name));
+    const one = await sha(join12(a, name));
     ha.push(one);
-    if (one !== await sha(join11(b, name))) differing.push(i + 1);
+    if (one !== await sha(join12(b, name))) differing.push(i + 1);
   }
-  const html = await readFile12(join11(dir, COMPOSITION_PAGE), "utf8").catch(() => "");
+  const html = await readFile13(join12(dir, COMPOSITION_PAGE), "utf8").catch(() => "");
   const motion = measureMotion(ha, readScenes(html), readCanvas(html)?.seconds ?? 0);
   let worst;
   if (differing.length > 0) {
@@ -11780,11 +11962,11 @@ async function render(dir, out, opts) {
   }
 }
 async function frames(dir) {
-  const names = await readdir2(dir).catch(() => []);
+  const names = await readdir3(dir).catch(() => []);
   return names.filter((n3) => n3.endsWith(".png")).sort();
 }
 async function sha(file) {
-  return createHash9("sha256").update(await readFile12(file)).digest("hex");
+  return createHash9("sha256").update(await readFile13(file)).digest("hex");
 }
 var STAT = /^n:(\d+)\b.*\bpsnr_avg:(inf|-?[\d.]+)/;
 function framePattern(name) {
@@ -11817,11 +11999,11 @@ async function psnr(a, b, firstFrame) {
         "-start_number",
         String(seq.start),
         "-i",
-        join11(a, seq.pattern),
+        join12(a, seq.pattern),
         "-start_number",
         String(seq.start),
         "-i",
-        join11(b, seq.pattern),
+        join12(b, seq.pattern),
         "-lavfi",
         "psnr=stats_file=-",
         "-f",
@@ -11896,7 +12078,7 @@ async function verify(dir, opts = {}, storyboard, kept, source) {
   const html = await readCompositions(dir);
   const determinism = html.flatMap(([file, text2]) => scanDeterminism(text2, file));
   const narration = scanNarration(
-    await readFile13(join12(dir, DECK_PAGE), "utf8").catch(() => ""),
+    await readFile14(join13(dir, DECK_PAGE), "utf8").catch(() => ""),
     await listFiles(dir)
   );
   const budget2 = html.flatMap(([, text2]) => scanBudget(text2, storyboard, kept));
@@ -11933,8 +12115,8 @@ async function verify(dir, opts = {}, storyboard, kept, source) {
 }
 async function declaredStops(dir) {
   return readStops(
-    await readFile13(join12(dir, TIMING_FILE), "utf8").catch(() => null),
-    await readFile13(join12(dir, DECK_PAGE), "utf8").catch(() => null)
+    await readFile14(join13(dir, TIMING_FILE), "utf8").catch(() => null),
+    await readFile14(join13(dir, DECK_PAGE), "utf8").catch(() => null)
   );
 }
 var NARRATION_ISLAND = /<script type="application\/decksmith-narration\+json">([\s\S]*?)<\/script>/;
@@ -11974,7 +12156,7 @@ function scanNarration(page, files) {
   ];
 }
 async function readTiming(dir) {
-  const raw2 = await readFile13(join12(dir, TIMING_FILE), "utf8").catch(() => "");
+  const raw2 = await readFile14(join13(dir, TIMING_FILE), "utf8").catch(() => "");
   if (!raw2) return void 0;
   try {
     const parsed = JSON.parse(raw2);
@@ -11984,9 +12166,9 @@ async function readTiming(dir) {
   }
 }
 async function listFiles(dir) {
-  const entries = await readdir3(dir, { recursive: true, withFileTypes: true }).catch(() => []);
+  const entries = await readdir4(dir, { recursive: true, withFileTypes: true }).catch(() => []);
   return new Set(
-    entries.filter((e) => e.isFile()).map((e) => relative(dir, join12(e.parentPath, e.name)).split(sep).join("/"))
+    entries.filter((e) => e.isFile()).map((e) => relative(dir, join13(e.parentPath, e.name)).split(sep).join("/"))
   );
 }
 var INSTEAD = {
@@ -12242,22 +12424,22 @@ function scanDeterminism(html, file) {
   return findings;
 }
 async function readCompositions(dir) {
-  const entries = await readdir3(dir, { recursive: true, withFileTypes: true }).catch(() => []);
+  const entries = await readdir4(dir, { recursive: true, withFileTypes: true }).catch(() => []);
   const files = entries.filter(
     (e) => e.isFile() && e.name.endsWith(".html") && e.name !== DECK_PAGE && !e.parentPath.includes("node_modules")
-  ).map((e) => join12(e.parentPath, e.name));
+  ).map((e) => join13(e.parentPath, e.name));
   return Promise.all(
-    files.map(async (f) => [relative(dir, f), await readFile13(f, "utf8")])
+    files.map(async (f) => [relative(dir, f), await readFile14(f, "utf8")])
   );
 }
 
 // src/render/render.ts
-import { mkdir as mkdir8, readFile as readFile14, rename as rename2, rm as rm8, writeFile as writeFile10 } from "node:fs/promises";
-import { basename as basename3, dirname, join as join14, resolve as resolve3 } from "node:path";
+import { mkdir as mkdir9, readFile as readFile15, rename as rename2, rm as rm8, writeFile as writeFile11 } from "node:fs/promises";
+import { basename as basename3, dirname as dirname2, join as join15, resolve as resolve4 } from "node:path";
 
 // src/render/captions.ts
-import { mkdir as mkdir7, writeFile as writeFile9 } from "node:fs/promises";
-import { join as join13 } from "node:path";
+import { mkdir as mkdir8, writeFile as writeFile10 } from "node:fs/promises";
+import { join as join14 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var DECK_FONT_CSS = "assets/fonts/fonts.css";
 function cssString(value) {
@@ -12348,11 +12530,11 @@ async function captionBlocker() {
 }
 async function renderCaptions(cues, style, deck, work) {
   if (cues.length === 0) throw new Error("renderCaptions was given no cues.");
-  const fontCss = join13(deck, DECK_FONT_CSS);
+  const fontCss = join14(deck, DECK_FONT_CSS);
   const href = await import("node:fs/promises").then((fs) => fs.stat(fontCss).catch(() => null)) ? pathToFileURL2(fontCss).href : null;
-  const page = join13(work, "captions.html");
-  await mkdir7(work, { recursive: true });
-  await writeFile9(page, captionPage(cues, style, href));
+  const page = join14(work, "captions.html");
+  await mkdir8(work, { recursive: true });
+  await writeFile10(page, captionPage(cues, style, href));
   const { default: puppeteer } = await import("puppeteer-core");
   const browser = await puppeteer.launch({
     executablePath: await chromePath(CAPTION_NEED),
@@ -12372,7 +12554,7 @@ async function renderCaptions(cues, style, deck, work) {
       const name = `cap${String(i).padStart(4, "0")}.png`;
       await tab.evaluate((id2) => document.getElementById(id2)?.classList.add("on"), `c${i}`);
       await tab.screenshot({
-        path: join13(work, name),
+        path: join14(work, name),
         type: "png",
         omitBackground: true,
         clip: { x: box.x, y: box.y, width: box.width, height: box.height }
@@ -12413,9 +12595,9 @@ function subtitlePlan(mode) {
 async function render2(opts) {
   const log = opts.log ?? (() => {
   });
-  const deck = resolve3(opts.deck);
-  const out = resolve3(opts.out);
-  const work = join14(dirname(out), `.${basename3(out)}.parts`);
+  const deck = resolve4(opts.deck);
+  const out = resolve4(opts.out);
+  const work = join15(dirname2(out), `.${basename3(out)}.parts`);
   const timing = await readTiming2(deck);
   if (opts.targetSeconds && !opts.allowFastPlayback) {
     const refusal = playbackRefusal(
@@ -12427,13 +12609,17 @@ async function render2(opts) {
   }
   const plan0 = subtitlePlan(opts.subtitles ?? "sidecar");
   if (plan0.burn) {
+    if (!timing.captionReserve)
+      throw new Error(
+        "This deck was built without room for a burned caption, so the band would sit on the slide's own text. Rebuild with `decksmith build --reserve-captions`, or render with `--subtitles sidecar`."
+      );
     const blocker = await captionBlocker();
     if (blocker) throw new Error(`Cannot burn in captions: ${blocker}`);
   }
   const burnable = plan0.burn;
-  await mkdir8(work, { recursive: true });
+  await mkdir9(work, { recursive: true });
   try {
-    const raw2 = opts.video ? resolve3(opts.video) : await capture(deck, join14(work, "raw.mp4"), opts, log);
+    const raw2 = opts.video ? resolve4(opts.video) : await capture(deck, join15(work, "raw.mp4"), opts, log);
     const shot = await probe(raw2);
     log(
       `render: ${shot.frames} frames, ${shot.width}\xD7${shot.height}, ${shot.fps.toFixed(3)} fps, ${shot.seconds.toFixed(2)}s`
@@ -12446,18 +12632,18 @@ async function render2(opts) {
       );
     }
     const retimed = await retime(raw2, plan, work, log);
-    const srtPath = join14(dirname(out), SRT_NAME(out));
+    const srtPath = join15(dirname2(out), SRT_NAME(out));
     const playback = opts.targetSeconds ? playbackFactor(plan.frames / shot.fps, opts.targetSeconds) : 1;
     const cues = playback > 1 ? plan.cues.map((c) => scaleCue(c, playback)) : plan.cues;
     const srt = plan0.sidecar ? toSrt(cues) : "";
-    if (srt) await writeFile10(srtPath, srt);
+    if (srt) await writeFile11(srtPath, srt);
     const burn = burnable && srt.length > 0;
     await mux(retimed, timing, plan, deck, out, work, burn ? plan.cues : void 0, shot.fps, log);
     if (playback > 1) {
       log(`render: speeding playback ${playback}\xD7 to reach ${opts.targetSeconds}s`);
       const warning = playbackWarning(playback, p95CueRate(plan.cues));
       if (warning) log(`render: ${warning}`);
-      const fast = join14(work, `fast.${basename3(out)}`);
+      const fast = join15(work, `fast.${basename3(out)}`);
       const muxed = await probe(out);
       await runTool(
         "ffmpeg",
@@ -12487,8 +12673,8 @@ async function render2(opts) {
   }
 }
 async function readTiming2(deck) {
-  const path2 = join14(deck, TIMING_FILE);
-  const text2 = await readFile14(path2, "utf8").catch(() => {
+  const path2 = join15(deck, TIMING_FILE);
+  const text2 = await readFile15(path2, "utf8").catch(() => {
     throw new Error(
       `${path2} is missing. \`render\` needs the timing manifest \`build\` writes; rebuild the deck.`
     );
@@ -12527,20 +12713,20 @@ async function retime(raw2, plan, work, log) {
   if (plan.pieces.every((p) => p.freeze === 0)) return raw2;
   const list = [];
   for (const [i, piece] of plan.pieces.entries()) {
-    const file = join14(work, `p${String(i).padStart(4, "0")}.ts`);
+    const file = join15(work, `p${String(i).padStart(4, "0")}.ts`);
     await runTool("ffmpeg", pieceArgs(raw2, piece.from, piece.motion, piece.freeze, plan.fps, file));
     list.push(file);
     if ((i + 1) % 10 === 0 || i === plan.pieces.length - 1) {
       log(`render: retimed ${i + 1}/${plan.pieces.length} pieces`);
     }
   }
-  const listFile = join14(work, "pieces.txt");
-  await writeFile10(
+  const listFile = join15(work, "pieces.txt");
+  await writeFile11(
     listFile,
     `${list.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n")}
 `
   );
-  const joined = join14(work, "retimed.mp4");
+  const joined = join15(work, "retimed.mp4");
   await runTool("ffmpeg", [
     "-y",
     "-hide_banner",
@@ -12562,7 +12748,7 @@ async function retime(raw2, plan, work, log) {
 }
 async function mux(video, timing, plan, deck, out, work, burnCues, fps, log) {
   const inputs = plan.audio.map((a) => ({
-    file: join14(deck, timing.audioDir, a.audio),
+    file: join15(deck, timing.audioDir, a.audio),
     delayMs: a.delayMs
   }));
   const args = ["-y", "-hide_banner", "-loglevel", "error", "-i", video];
@@ -12583,8 +12769,8 @@ async function mux(video, timing, plan, deck, out, work, burnCues, fps, log) {
     graph.push(audioGraph(inputs, plan.frames / fps, 1 + (band?.files.length ?? 0)));
   }
   if (graph.length > 0) {
-    const script = join14(work, "mux.filter");
-    await writeFile10(script, `${graph.join(";\n")}
+    const script = join15(work, "mux.filter");
+    await writeFile11(script, `${graph.join(";\n")}
 `);
     args.push("-filter_complex_script", script);
   }
@@ -12599,13 +12785,13 @@ async function mux(video, timing, plan, deck, out, work, burnCues, fps, log) {
   log(
     `render: muxing ${inputs.length} segment(s)${burnCues ? " and burning in the captions" : ""} \u2192 ${out}`
   );
-  await mkdir8(dirname(out), { recursive: true });
+  await mkdir9(dirname2(out), { recursive: true });
   await runTool("ffmpeg", args, { cwd: work });
 }
 
 // src/pack/pack.ts
-import { mkdir as mkdir9, readFile as readFile15, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname2, extname as extname3 } from "node:path";
+import { mkdir as mkdir10, readFile as readFile16, writeFile as writeFile12 } from "node:fs/promises";
+import { dirname as dirname3, extname as extname3 } from "node:path";
 import { unzipSync, zipSync } from "fflate";
 var MTIME = Date.UTC(1980, 0, 2, 12);
 var STORED = /* @__PURE__ */ new Set([
@@ -12644,12 +12830,12 @@ async function writePack(pack2, files, out) {
     entries[path2] = STORED.has(extname3(path2).toLowerCase()) ? [bytes, { level: 0 }] : bytes;
   }
   const zip = zipSync(entries, { mtime: MTIME });
-  await mkdir9(dirname2(out), { recursive: true });
-  await writeFile11(out, zip);
+  await mkdir10(dirname3(out), { recursive: true });
+  await writeFile12(out, zip);
   return zip.length;
 }
 async function readPack(path2) {
-  return openPack(new Uint8Array(await readFile15(path2)), path2);
+  return openPack(new Uint8Array(await readFile16(path2)), path2);
 }
 function openPack(bytes, label = "pack") {
   if (bytes.length < 4 || bytes[0] !== 80 || bytes[1] !== 75)
@@ -12693,8 +12879,8 @@ function why2(error) {
 }
 
 // src/prefs.ts
-import { readFile as readFile16 } from "node:fs/promises";
-import { dirname as dirname3, join as join15, resolve as resolve4 } from "node:path";
+import { readFile as readFile17 } from "node:fs/promises";
+import { dirname as dirname4, join as join16, resolve as resolve5 } from "node:path";
 var CONFIG_FILE = "decksmith.config.json";
 var PREF_KEYS = Object.keys(prefsSchema.shape);
 var NARRATION_KEYS = Object.keys(prefsSchema.shape.narration.unwrap().shape);
@@ -12711,10 +12897,10 @@ async function loadPrefs(overrides = {}, cwd = process.cwd(), source) {
   return parsed;
 }
 async function findConfig(from) {
-  let dir = resolve4(from);
+  let dir = resolve5(from);
   for (; ; ) {
-    const path2 = join15(dir, CONFIG_FILE);
-    const text2 = await readFile16(path2, "utf8").catch(() => void 0);
+    const path2 = join16(dir, CONFIG_FILE);
+    const text2 = await readFile17(path2, "utf8").catch(() => void 0);
     if (text2 !== void 0) {
       try {
         return { path: path2, value: JSON.parse(text2) };
@@ -12722,7 +12908,7 @@ async function findConfig(from) {
         throw new Error(`${path2} is not valid JSON.`);
       }
     }
-    const up = dirname3(dir);
+    const up = dirname4(dir);
     if (up === dir) return void 0;
     dir = up;
   }
@@ -12768,26 +12954,26 @@ ${issues}`);
 
 // src/tmpdir.ts
 import { realpathSync } from "node:fs";
-import { createRequire as createRequire3 } from "node:module";
+import { createRequire as createRequire4 } from "node:module";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename as basename4, dirname as dirname4, join as join16, resolve as resolve5, sep as sep2 } from "node:path";
+import { basename as basename4, dirname as dirname5, join as join17, resolve as resolve6, sep as sep2 } from "node:path";
 var cached;
 function real(dir) {
-  let at = resolve5(dir);
+  let at = resolve6(dir);
   const tail3 = [];
   for (; ; ) {
     try {
-      return join16(realpathSync(at), ...tail3);
+      return join17(realpathSync(at), ...tail3);
     } catch {
-      const up = dirname4(at);
-      if (up === at) return resolve5(dir);
+      const up = dirname5(at);
+      if (up === at) return resolve6(dir);
       tail3.unshift(basename4(at));
       at = up;
     }
   }
 }
 function packageRoot() {
-  cached ??= real(dirname4(createRequire3(import.meta.url).resolve("../package.json")));
+  cached ??= real(dirname5(createRequire4(import.meta.url).resolve("../package.json")));
   return cached;
 }
 function insideRoot(dir) {
@@ -12820,8 +13006,8 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   if (!format) throw new Error("no deck-16x9 format");
   const step = opts.onStep ?? (() => {
   });
-  const out = resolve6(outDir);
-  await mkdir10(out, { recursive: true });
+  const out = resolve7(outDir);
+  await mkdir11(out, { recursive: true });
   const speed = opts.speed ?? 1;
   const fontCss = await refreshFont(storyboard, source, out, step);
   const deck = emitDeck(storyboard, source, format, await deckRuntime(), {
@@ -12834,47 +13020,48 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   });
   const files = [];
   const write = async (name, text2) => {
-    await writeFile12(join17(out, name), text2);
-    files.push(join17(out, name));
+    await writeFile13(join18(out, name), text2);
+    files.push(join18(out, name));
   };
   await write("index.html", deck.composition);
   await write("hyperframes.json", HYPERFRAMES_JSON);
-  if (opts.narration) {
-    try {
-      const timing = planTiming({
-        storyboard,
-        source,
-        format,
-        composition: deck.composition,
-        // What was drawn, not what the threshold would have kept: a budgeted
-        // format cuts to its own length as well, and the two lists differ.
-        beats: deck.cut.kept,
-        narration: opts.narration,
-        speed,
-        ...opts.theme ? { theme: opts.theme } : {}
-      });
-      await write(TIMING_FILE, `${JSON.stringify(timing, null, 2)}
+  try {
+    const timing = planTiming({
+      storyboard,
+      source,
+      format,
+      composition: deck.composition,
+      // What was drawn, not what the threshold would have kept: a budgeted
+      // format cuts to its own length as well, and the two lists differ.
+      beats: deck.cut.kept,
+      speed,
+      ...opts.narration ? { narration: opts.narration } : {},
+      ...opts.theme ? { theme: opts.theme } : {}
+    });
+    await write(TIMING_FILE, `${JSON.stringify(timing, null, 2)}
 `);
-      step(`build: timing for ${timing.segments.length} narration segment(s)`);
-    } catch (err) {
-      step(
-        `build: cannot place narration on this deck, so no ${TIMING_FILE} was written and \`render\` will refuse. ${err instanceof Error ? err.message : err}`
-      );
-    }
+    step(`build: timing for ${timing.segments.length} narration segment(s)`);
+  } catch (err) {
+    step(
+      `build: cannot place narration on this deck, so no ${TIMING_FILE} was written and \`render\` will refuse. ${err instanceof Error ? err.message : err}`
+    );
   }
   if (deck.page) {
     await write(DECK_PAGE, deck.page);
-    await cp(playerBundle(), join17(out, PLAYER_FILE));
-    files.push(join17(out, PLAYER_FILE));
+    await cp2(playerBundle(), join18(out, PLAYER_FILE));
+    files.push(join18(out, PLAYER_FILE));
   }
   files.push(...await vendorKatex(out));
-  if (opts.assetsFrom) files.push(...await copyAssets(opts.assetsFrom, out));
+  files.push(...await vendorScripts(out, deck.composition));
+  if (opts.assetsFrom) {
+    files.push(...await copyAssets(opts.assetsFrom, out, source.figures, step));
+  }
   if (opts.narration && opts.audioFrom) {
-    files.push(...await copyAudio(opts.audioFrom, opts.narration, out));
+    files.push(...await copyAudio(opts.audioFrom, opts.narration, out, step));
   }
   const of = deck.cut.kept.length === storyboard.beats.length ? "" : ` of ${storyboard.beats.length}`;
   step(
-    `build: ${deck.cut.kept.length}${of} beats at ${format.width}\xD7${format.height} \u2192 ${join17(out, "index.html")}`
+    `build: ${deck.cut.kept.length}${of} beats at ${format.width}\xD7${format.height} \u2192 ${join18(out, "index.html")}`
   );
   for (const d of deck.cut.dropped) step(`build:   cut ${d.beat.id} \u2014 ${d.reason}`);
   for (const d of deck.cut.dangling) step(`build:   check the wording \u2014 ${d.reason}`);
@@ -12890,79 +13077,28 @@ var HYPERFRAMES_JSON = `${JSON.stringify(
 )}
 `;
 async function deckRuntime() {
-  const path2 = fileURLToPath(new URL(`./${"deck-runtime.js"}`, import.meta.url));
+  const path2 = fileURLToPath2(new URL(`./${"deck-runtime.js"}`, import.meta.url));
   try {
-    return await readFile17(path2, "utf8");
+    return await readFile18(path2, "utf8");
   } catch {
     throw new Error(`Deck runtime missing at ${path2}. Run "npm run build" first.`);
   }
 }
 function playerBundle() {
-  const require2 = createRequire4(import.meta.url);
+  const require2 = createRequire5(import.meta.url);
   try {
-    return join17(dirname5(require2.resolve("hyperframes/package.json")), "dist", PLAYER_FILE);
+    return join18(dirname6(require2.resolve("hyperframes/package.json")), "dist", PLAYER_FILE);
   } catch {
     throw new Error('Cannot locate the hyperframes player. Run "npm install".');
   }
 }
-async function vendorKatex(out) {
-  const require2 = createRequire4(import.meta.url);
-  const dist = join17(dirname5(require2.resolve("katex/package.json")), "dist");
-  const css = await readFile17(join17(dist, "katex.min.css"), "utf8");
-  const written = [];
-  await mkdir10(join17(out, "katex/fonts"), { recursive: true });
-  for (const file of await readdir4(join17(dist, "fonts"))) {
-    if (!file.endsWith(".woff2")) continue;
-    await cp(join17(dist, "fonts", file), join17(out, "katex/fonts", file));
-    written.push(join17(out, "katex/fonts", file));
-  }
-  const woff2Only = css.replace(/src:([^;}]*)/g, (whole, list) => {
-    const kept = list.split(",").filter((part) => part.includes(".woff2")).join(",");
-    return kept ? `src:${kept}` : whole;
-  });
-  await writeFile12(join17(out, "katex/katex.min.css"), woff2Only);
-  written.push(join17(out, "katex/katex.min.css"));
-  return written;
-}
-async function copyAssets(sourceDir, out) {
-  const from = join17(resolve6(sourceDir), "assets");
-  if (!await stat2(from).catch(() => null)) return [];
-  await cp(from, join17(out, "assets"), { recursive: true });
-  return [join17(out, "assets")];
-}
-async function copyAudio(from, narration, out) {
-  const dir = join17(out, narration.dir);
-  await mkdir10(dir, { recursive: true });
-  const names = [
-    ...new Set(
-      Object.values(narration.beats).flat().map((s) => s.audio)
-    )
-  ].sort();
-  for (const name of names) {
-    await cp(join17(resolve6(from), name), join17(dir, name)).catch(() => {
-      throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
-    });
-  }
-  return names.map((n3) => join17(dir, n3));
-}
-async function refreshFont(storyboard, source, out, step) {
-  try {
-    const bundle = await bundleFont(
-      storyboard.lang,
-      JSON.stringify(source) + JSON.stringify(storyboard),
-      join17(out, "assets", "fonts")
-    );
-    if (bundle) step(`build: font bundle covers ${bundle.family}`);
-    return bundle?.css;
-  } catch (err) {
-    step(
-      `build: could not refresh the font bundle (${err instanceof Error ? err.message : err}); keeping the one from ingest`
-    );
-    return void 0;
-  }
-}
 export {
   ARCHETYPE_FAMILY,
+  CAPTION_FONT_RATIO,
+  CAPTION_LINE_RATIO,
+  CAPTION_MARGIN_V_RATIO,
+  CAPTION_MARGIN_X_RATIO,
+  CAPTION_MAX_LINES,
   COMFORTABLE_CPS,
   CONFIG_FILE,
   DECK_PAGE,
@@ -12992,6 +13128,7 @@ export {
   assertInsideResolves,
   assertRefsResolve,
   attachClips,
+  bandReserve,
   barCompareParamsSchema,
   beatRoleSchema,
   beatSchema,
@@ -13000,6 +13137,7 @@ export {
   calloutParamsSchema,
   canvasProblem,
   canvasWarnings,
+  captionFontSize,
   check,
   claimFigureParamsSchema,
   codexPlanner,