@jokerized/decksmith 0.4.1 → 0.5.0

package/dist/cli.js

@@ -1,16 +1,181 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { cp, mkdir as mkdir10, mkdtemp as mkdtemp4, readdir as readdir4, readFile as readFile17, rm as rm9, stat as stat2, writeFile as writeFile12 } from "node:fs/promises";
-import { createRequire as createRequire4 } from "node:module";
+import { cp as cp2, mkdir as mkdir11, mkdtemp as mkdtemp4, readFile as readFile18, rm as rm9, stat as stat3, writeFile as writeFile13 } from "node:fs/promises";
+import { createRequire as createRequire5 } from "node:module";
 import { tmpdir as tmpdir5 } from "node:os";
-import { dirname as dirname5, join as join17, relative as relative2, resolve as resolve6 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { dirname as dirname6, join as join18, relative as relative2, resolve as resolve7 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Command } from "commander";
 
-// src/pack/media.ts
+// 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/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, glyphs2, dir) {
+  const family = familyFor(lang);
+  if (!family) return null;
+  const text2 = [...new Set(glyphs2)].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, url2] of remote.entries()) {
+    const font = await fetch(url2);
+    if (!font.ok) throw new Error(`${url2}: HTTP ${font.status}`);
+    const name = `${slug}-${i}.woff2`;
+    await writeFile(join(dir, name), Buffer.from(await font.arrayBuffer()));
+    css = css.replaceAll(url2, 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
+var AUDIO_DIR = "audio";
+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, step2) {
+  const from = join2(resolve(sourceDir), "assets");
+  if (!await stat(from).catch(() => null)) {
+    step2(`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"));
+  }
+  step2(`build: copied ${copied} referenced figure(s)`);
+  return written;
+}
+async function copyAudio(from, narration, out, step2) {
+  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\`.`);
+    });
+  }
+  step2(`narration: ${names.length} audio file(s) \u2192 ${dir}`);
+  return names.map((n3) => join2(dir, n3));
+}
+async function refreshFont(storyboard, source, out, step2) {
+  try {
+    const bundle = await bundleFont(
+      storyboard.lang,
+      JSON.stringify(source) + JSON.stringify(storyboard),
+      join2(out, "assets", "fonts")
+    );
+    if (bundle) step2(`build: font bundle covers ${bundle.family}`);
+    return bundle?.css;
+  } catch (err) {
+    step2(
+      `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",
@@ -184,7 +349,7 @@ function mediaSummary(plan) {
 }
 function bakedName(id2, url2, mime) {
   const slug = id2.toLowerCase().replace(/[^a-z0-9_-]+/g, "-") || "asset";
-  const hash = createHash("sha256").update(url2).digest("hex").slice(0, 8);
+  const hash = createHash2("sha256").update(url2).digest("hex").slice(0, 8);
   return `${slug}-${hash}${extOf(url2) || extFor(mime)}`;
 }
 function extOf(url2) {
@@ -239,7 +404,7 @@ async function fetchAsset(url2) {
       mime: res.headers.get("content-type") ?? void 0
     };
   }
-  return { bytes: new Uint8Array(await readFile(url2)) };
+  return { bytes: new Uint8Array(await readFile3(url2)) };
 }
 
 // src/types.ts
@@ -908,6 +1073,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.
@@ -1224,54 +1401,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, glyphs2, dir) {
-  const family = familyFor(lang);
-  if (!family) return null;
-  const text2 = [...new Set(glyphs2)].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, url2] of remote.entries()) {
-    const font = await fetch(url2);
-    if (!font.ok) throw new Error(`${url2}: HTTP ${font.status}`);
-    const name = `${slug}-${i}.woff2`;
-    await writeFile(join(dir, name), Buffer.from(await font.arrayBuffer()));
-    css = css.replaceAll(url2, 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;
@@ -1290,7 +1419,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 };
@@ -1789,8 +1923,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) {
@@ -2051,11 +2185,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 "";
@@ -6189,13 +6328,13 @@ function rnd(n3) {
 
 // src/images/illustrate.ts
 import { createHash as createHash5 } from "node:crypto";
-import { mkdir as mkdir3, readFile as readFile6, rename, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
-import { join as join5 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile7, rename, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
+import { join as join6 } from "node:path";
 
 // src/source/assets.ts
 import { createHash as createHash3 } from "node:crypto";
-import { mkdir as mkdir2, readdir, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { extname as extname2, join as join2 } from "node:path";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { extname as extname2, join as join3 } from "node:path";
 import { z as z2 } from "zod";
 
 // src/net/fetch.ts
@@ -6206,8 +6345,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 = [
@@ -6402,8 +6541,8 @@ async function send(url2, 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();
     });
@@ -6488,8 +6627,8 @@ function message(err) {
 // src/source/assets.ts
 async function fetchFigures(source, dir, warnings) {
   const drops = warnings ?? [];
-  await mkdir2(dir, { recursive: true });
-  const cached2 = await readdir(dir).catch(() => []);
+  await mkdir3(dir, { recursive: true });
+  const cached2 = await readdir2(dir).catch(() => []);
   const figures = [];
   for (const figure of source.figures) {
     if (figure.kind === "clip") {
@@ -6514,11 +6653,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 readFile3(join2(dir, hit)) : await load(figure.src);
+  const bytes = hit ? await readFile4(join3(dir, hit)) : await load(figure.src);
   const size3 = imageSize(bytes);
   if (hit) return { ...figure, src: hit, ...size3 };
   const src = `${stem}${assetExt(bytes, figure.src)}`;
-  await writeFile2(join2(dir, src), bytes);
+  await writeFile3(join3(dir, src), bytes);
   cached2.push(src);
   return { ...figure, src, ...size3 };
 }
@@ -6543,7 +6682,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 readFile3(src);
+  if (!/^https?:/i.test(src)) return readFile4(src);
   const got = await fetchGuarded(src, {
     maxBytes: FIGURE_MAX_BYTES,
     timeoutMs: FIGURE_TIMEOUT_MS
@@ -6788,16 +6927,16 @@ function cssPixels(value) {
 
 // src/images/providers.ts
 import { createHash as createHash4 } from "node:crypto";
-import { mkdtemp as mkdtemp2, readFile as readFile5, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, readFile as readFile6, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join4, resolve } from "node:path";
+import { join as join5, resolve as resolve2 } from "node:path";
 import { z as z4 } from "zod";
 
 // src/plan/codex.ts
 import { spawn } from "node:child_process";
-import { mkdtemp, readFile as readFile4, rm, writeFile as writeFile3 } from "node:fs/promises";
+import { mkdtemp, readFile as readFile5, rm, writeFile as writeFile4 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 import { z as z3 } from "zod";
 
 // src/plan/arc.ts
@@ -7916,11 +8055,11 @@ function schemaFor(prefs) {
 var SCHEMA = schemaFor({ genre: "general" });
 async function codexPlanner(source, opts = {}) {
   const prefs = opts.prefs ?? prefsSchema.parse({});
-  const dir = await mkdtemp(join3(tmpdir(), "decksmith-plan-"));
+  const dir = await mkdtemp(join4(tmpdir(), "decksmith-plan-"));
   try {
-    const schemaPath = join3(dir, "storyboard.schema.json");
-    const outPath = join3(dir, "storyboard.json");
-    await writeFile3(schemaPath, JSON.stringify(schemaFor(prefs)));
+    const schemaPath = join4(dir, "storyboard.schema.json");
+    const outPath = join4(dir, "storyboard.json");
+    await writeFile4(schemaPath, JSON.stringify(schemaFor(prefs)));
     await (opts.run ?? runCodex)({
       prompt: buildPrompt(source, prefs),
       schemaPath,
@@ -7928,7 +8067,7 @@ async function codexPlanner(source, opts = {}) {
       ...opts.model === void 0 ? {} : { model: opts.model },
       timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
     });
-    const raw2 = await readFile4(outPath, "utf8").catch(() => "");
+    const raw2 = await readFile5(outPath, "utf8").catch(() => "");
     if (raw2.trim() === "") {
       throw new Error("Codex produced no final message. Re-run, or try a shorter source.");
     }
@@ -8001,7 +8140,7 @@ function codexCommand(args) {
 }
 function runCodex(args) {
   const { argv, env } = codexCommand(args);
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = spawn("codex", argv, {
       stdio: ["pipe", "ignore", "pipe"],
       ...env === void 0 ? {} : { env }
@@ -8024,7 +8163,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")}`)
@@ -8165,11 +8304,11 @@ function codexImages(opts = {}) {
     async check() {
     },
     async generate(req) {
-      const dir = await mkdtemp2(join4(tmpdir2(), "decksmith-image-"));
+      const dir = await mkdtemp2(join5(tmpdir2(), "decksmith-image-"));
       try {
-        const schemaPath = join4(dir, "answer.schema.json");
-        const outPath = join4(dir, "answer.json");
-        await writeFile4(schemaPath, JSON.stringify(ANSWER_SCHEMA));
+        const schemaPath = join5(dir, "answer.schema.json");
+        const outPath = join5(dir, "answer.json");
+        await writeFile5(schemaPath, JSON.stringify(ANSWER_SCHEMA));
         await run4({
           prompt: codexPrompt(req),
           schemaPath,
@@ -8178,7 +8317,7 @@ function codexImages(opts = {}) {
           cwd: dir,
           sandbox: "workspace-write"
         });
-        const raw2 = await readFile5(outPath, "utf8").catch(() => "");
+        const raw2 = await readFile6(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) {
@@ -8186,10 +8325,10 @@ function codexImages(opts = {}) {
             `codex could not generate a picture: ${answer.data.reason ?? "no reason given"}`
           );
         }
-        const candidates2 = [join4(dir, "picture.png")];
-        if (answer.data.file) candidates2.push(resolve(dir, answer.data.file));
+        const candidates2 = [join5(dir, "picture.png")];
+        if (answer.data.file) candidates2.push(resolve2(dir, answer.data.file));
         for (const path2 of candidates2) {
-          const bytes = await readFile5(path2).catch(() => null);
+          const bytes = await readFile6(path2).catch(() => null);
           if (bytes) return raster(bytes, "codex");
         }
         throw new Error("codex said ok but wrote no picture.png");
@@ -8321,7 +8460,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 mkdir3(opts.assetsDir, { recursive: true });
+  if (pending.length > 0) await mkdir4(opts.assetsDir, { recursive: true });
   for (const [i, slot] of pending.entries()) {
     let rungs = chain;
     if (i >= images.max) {
@@ -8418,16 +8557,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 readFile6(join5(dir, src2)).catch(() => null);
+    const bytes = await readFile7(join6(dir, src2)).catch(() => null);
     if (bytes) return { src: src2, ...sizeOf(bytes, ext), cached: true };
   }
   await provider.check();
   const img = await provider.generate(req);
   const src = `${name}${EXT2[img.mime]}`;
-  const tmp = join5(dir, `.${name}.tmp`);
+  const tmp = join6(dir, `.${name}.tmp`);
   try {
-    await writeFile5(tmp, img.bytes);
-    await rename(tmp, join5(dir, src));
+    await writeFile6(tmp, img.bytes);
+    await rename(tmp, join6(dir, src));
   } finally {
     await rm3(tmp, { force: true });
   }
@@ -8440,9 +8579,9 @@ function sizeOf(bytes, ext) {
 // src/narrate/tts.ts
 import { spawn as spawn2 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
-import { mkdir as mkdir4, readFile as readFile7, rm as rm4, writeFile as writeFile6 } from "node:fs/promises";
+import { mkdir as mkdir5, readFile as readFile8, rm as rm4, writeFile as writeFile7 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var MISSING = [
   "edge-tts is not installed, so narration cannot be synthesised.",
   "",
@@ -8459,8 +8598,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.
-    [join6(home, "Library", "Python", "3.9", "bin", "edge-tts")],
-    [join6(home, ".local", "bin", "edge-tts")],
+    [join7(home, "Library", "Python", "3.9", "bin", "edge-tts")],
+    [join7(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"]
@@ -8485,7 +8624,7 @@ async function find2(can) {
   throw new Error(MISSING);
 }
 function runArgv(cmd, args) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     const child = spawn2(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
@@ -8495,8 +8634,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 = {
@@ -8563,7 +8702,7 @@ function edgeProvider(runner = edgeTts) {
     async speak(req) {
       const subs = `${req.audio.replace(/\.mp3$/, "")}.srt`;
       await runner.speak({ ...req, subs });
-      const raw2 = await readFile7(subs, "utf8").catch(() => "");
+      const raw2 = await readFile8(subs, "utf8").catch(() => "");
       await rm4(subs, { force: true });
       const cues = parseCues(raw2);
       const measured = await runner.measure(req.audio);
@@ -8581,11 +8720,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 = join6(opts.dir, file);
-  const sidecar = join6(opts.dir, `${key}.json`);
+  const audio = join7(opts.dir, file);
+  const sidecar = join7(opts.dir, `${key}.json`);
   const cached2 = await readSidecar(sidecar);
   if (cached2) return { audio, file, seconds: cached2.seconds, cues: cached2.cues };
-  await mkdir4(opts.dir, { recursive: true });
+  await mkdir5(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) => ({
@@ -8594,13 +8733,13 @@ async function synthesize(text2, opts) {
     text: c.text
   }));
   const body = { seconds, cues: clamped, text: text2, voice: opts.voice };
-  await writeFile6(sidecar, `${JSON.stringify(body, null, 2)}
+  await writeFile7(sidecar, `${JSON.stringify(body, null, 2)}
 `);
   return { audio, file, seconds, cues: clamped };
 }
 async function readSidecar(path2) {
   try {
-    const parsed = JSON.parse(await readFile7(path2, "utf8"));
+    const parsed = JSON.parse(await readFile8(path2, "utf8"));
     const s = parsed;
     return typeof s?.seconds === "number" && s.seconds > 0 && Array.isArray(s.cues) ? s : null;
   } catch {
@@ -8720,8 +8859,8 @@ async function narrate(storyboard, source, prefs, opts) {
 }
 
 // src/pack/pack.ts
-import { mkdir as mkdir5, readFile as readFile8, writeFile as writeFile7 } from "node:fs/promises";
-import { dirname, extname as extname3 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile9, writeFile as writeFile8 } from "node:fs/promises";
+import { dirname as dirname2, extname as extname3 } from "node:path";
 import { unzipSync, zipSync } from "fflate";
 var MTIME = Date.UTC(1980, 0, 2, 12);
 var STORED = /* @__PURE__ */ new Set([
@@ -8760,12 +8899,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 mkdir5(dirname(out), { recursive: true });
-  await writeFile7(out, zip);
+  await mkdir6(dirname2(out), { recursive: true });
+  await writeFile8(out, zip);
   return zip.length;
 }
 async function readPack(path2) {
-  return openPack(new Uint8Array(await readFile8(path2)), path2);
+  return openPack(new Uint8Array(await readFile9(path2)), path2);
 }
 function openPack(bytes, label = "pack") {
   if (bytes.length < 4 || bytes[0] !== 80 || bytes[1] !== 75)
@@ -8809,8 +8948,8 @@ function why(error) {
 }
 
 // src/prefs.ts
-import { readFile as readFile9 } from "node:fs/promises";
-import { dirname as dirname2, join as join7, resolve as resolve2 } from "node:path";
+import { readFile as readFile10 } from "node:fs/promises";
+import { dirname as dirname3, join as join8, resolve as resolve3 } 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);
@@ -8856,10 +8995,10 @@ function prefsFromFlags(flags2) {
   return patch;
 }
 async function findConfig(from) {
-  let dir = resolve2(from);
+  let dir = resolve3(from);
   for (; ; ) {
-    const path2 = join7(dir, CONFIG_FILE);
-    const text2 = await readFile9(path2, "utf8").catch(() => void 0);
+    const path2 = join8(dir, CONFIG_FILE);
+    const text2 = await readFile10(path2, "utf8").catch(() => void 0);
     if (text2 !== void 0) {
       try {
         return { path: path2, value: JSON.parse(text2) };
@@ -8867,7 +9006,7 @@ async function findConfig(from) {
         throw new Error(`${path2} is not valid JSON.`);
       }
     }
-    const up = dirname2(dir);
+    const up = dirname3(dir);
     if (up === dir) return void 0;
     dir = up;
   }
@@ -8917,10 +9056,10 @@ function number(flag, value) {
 }
 
 // src/render/capture.ts
-import { mkdir as mkdir6, readFile as readFile10, writeFile as writeFile8 } from "node:fs/promises";
-import { createRequire as createRequire2 } from "node:module";
+import { mkdir as mkdir7, readFile as readFile11, writeFile as writeFile9 } from "node:fs/promises";
+import { createRequire as createRequire3 } from "node:module";
 import { homedir as homedir2 } from "node:os";
-import { join as join8 } from "node:path";
+import { join as join9 } 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;
@@ -8931,9 +9070,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(join8(homedir2(), ".cache", "hyperframes", "chrome"));
+  const hf = await pick(join9(homedir2(), ".cache", "hyperframes", "chrome"));
   if (hf) return { path: hf.executablePath, source: "hyperframes" };
-  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join8(homedir2(), ".cache", "puppeteer"));
+  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join9(homedir2(), ".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.`
@@ -8943,15 +9082,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 = join8(dir, "index.html");
-  const html = await readFile10(index, "utf8").catch(() => null);
+  const index = join9(dir, "index.html");
+  const html = await readFile11(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);
@@ -9032,7 +9171,7 @@ function frameName(index, t2, total) {
 }
 async function captureFrames(dir, times, outDir, opts = {}) {
   if (times.length === 0) return [];
-  await mkdir6(outDir, { recursive: true });
+  await mkdir7(outDir, { recursive: true });
   const deck = await openDeck(dir, opts);
   try {
     const out = [];
@@ -9040,8 +9179,8 @@ async function captureFrames(dir, times, outDir, opts = {}) {
       const t2 = Math.round(raw2 * 1e3) / 1e3;
       await deck.seek(t2);
       const png = await deck.shoot();
-      const path2 = join8(outDir, frameName(i, t2, times.length));
-      await writeFile8(path2, png);
+      const path2 = join9(outDir, frameName(i, t2, times.length));
+      await writeFile9(path2, png);
       out.push({ t: t2, path: path2, bytes: png.length });
     }
     return out;
@@ -9052,12 +9191,12 @@ async function captureFrames(dir, times, outDir, opts = {}) {
 }
 
 // src/render/render.ts
-import { mkdir as mkdir8, readFile as readFile11, rename as rename2, rm as rm5, writeFile as writeFile10 } from "node:fs/promises";
-import { basename, dirname as dirname3, join as join10, resolve as resolve3 } from "node:path";
+import { mkdir as mkdir9, readFile as readFile12, rename as rename2, rm as rm5, writeFile as writeFile11 } from "node:fs/promises";
+import { basename, dirname as dirname4, join as join11, resolve as resolve4 } from "node:path";
 
 // src/render/captions.ts
-import { mkdir as mkdir7, writeFile as writeFile9 } from "node:fs/promises";
-import { join as join9 } from "node:path";
+import { mkdir as mkdir8, writeFile as writeFile10 } from "node:fs/promises";
+import { join as join10 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 // src/deck/subtitles.ts
@@ -9256,6 +9395,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
   };
@@ -9444,11 +9587,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 = join9(deck, DECK_FONT_CSS);
+  const fontCss = join10(deck, DECK_FONT_CSS);
   const href = await import("node:fs/promises").then((fs) => fs.stat(fontCss).catch(() => null)) ? pathToFileURL2(fontCss).href : null;
-  const page = join9(work, "captions.html");
-  await mkdir7(work, { recursive: true });
-  await writeFile9(page, captionPage(cues, style, href));
+  const page = join10(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),
@@ -9468,7 +9611,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: join9(work, name),
+        path: join10(work, name),
         type: "png",
         omitBackground: true,
         clip: { x: box.x, y: box.y, width: box.width, height: box.height }
@@ -9524,7 +9667,7 @@ ${tail3}`);
   }
 }
 function runLive(file, args) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = spawn3(file, args, { stdio: ["ignore", "inherit", "inherit"] });
     child.on("error", (err) => {
       reject(
@@ -9532,7 +9675,7 @@ function runLive(file, args) {
       );
     });
     child.on("close", (code, signal) => {
-      if (code === 0) resolve7();
+      if (code === 0) resolve8();
       else if (signal) {
         reject(
           new Error(
@@ -9659,11 +9802,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)
   };
 }
 
@@ -9675,9 +9823,9 @@ function subtitlePlan(mode) {
 async function render(opts) {
   const log = opts.log ?? (() => {
   });
-  const deck = resolve3(opts.deck);
-  const out = resolve3(opts.out);
-  const work = join10(dirname3(out), `.${basename(out)}.parts`);
+  const deck = resolve4(opts.deck);
+  const out = resolve4(opts.out);
+  const work = join11(dirname4(out), `.${basename(out)}.parts`);
   const timing = await readTiming(deck);
   if (opts.targetSeconds && !opts.allowFastPlayback) {
     const refusal = playbackRefusal(
@@ -9689,13 +9837,17 @@ async function render(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, join10(work, "raw.mp4"), opts, log);
+    const raw2 = opts.video ? resolve4(opts.video) : await capture(deck, join11(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`
@@ -9708,18 +9860,18 @@ async function render(opts) {
       );
     }
     const retimed = await retime(raw2, plan, work, log);
-    const srtPath = join10(dirname3(out), SRT_NAME(out));
+    const srtPath = join11(dirname4(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 = join10(work, `fast.${basename(out)}`);
+      const fast = join11(work, `fast.${basename(out)}`);
       const muxed = await probe(out);
       await runTool(
         "ffmpeg",
@@ -9749,8 +9901,8 @@ async function render(opts) {
   }
 }
 async function readTiming(deck) {
-  const path2 = join10(deck, TIMING_FILE);
-  const text2 = await readFile11(path2, "utf8").catch(() => {
+  const path2 = join11(deck, TIMING_FILE);
+  const text2 = await readFile12(path2, "utf8").catch(() => {
     throw new Error(
       `${path2} is missing. \`render\` needs the timing manifest \`build\` writes; rebuild the deck.`
     );
@@ -9789,20 +9941,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 = join10(work, `p${String(i).padStart(4, "0")}.ts`);
+    const file = join11(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 = join10(work, "pieces.txt");
-  await writeFile10(
+  const listFile = join11(work, "pieces.txt");
+  await writeFile11(
     listFile,
     `${list.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n")}
 `
   );
-  const joined = join10(work, "retimed.mp4");
+  const joined = join11(work, "retimed.mp4");
   await runTool("ffmpeg", [
     "-y",
     "-hide_banner",
@@ -9824,7 +9976,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: join10(deck, timing.audioDir, a.audio),
+    file: join11(deck, timing.audioDir, a.audio),
     delayMs: a.delayMs
   }));
   const args = ["-y", "-hide_banner", "-loglevel", "error", "-i", video];
@@ -9845,8 +9997,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 = join10(work, "mux.filter");
-    await writeFile10(script, `${graph.join(";\n")}
+    const script = join11(work, "mux.filter");
+    await writeFile11(script, `${graph.join(";\n")}
 `);
     args.push("-filter_complex_script", script);
   }
@@ -9861,14 +10013,14 @@ 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(dirname3(out), { recursive: true });
+  await mkdir9(dirname4(out), { recursive: true });
   await runTool("ffmpeg", args, { cwd: work });
 }
 
 // src/source/harvest.ts
 import { createHash as createHash7 } from "node:crypto";
-import { copyFile, mkdir as mkdir9, rm as rm7, stat, writeFile as writeFile11 } from "node:fs/promises";
-import { basename as basename3, join as join11, resolve as resolve4 } from "node:path";
+import { copyFile, mkdir as mkdir10, rm as rm7, stat as stat2, writeFile as writeFile12 } from "node:fs/promises";
+import { basename as basename3, join as join12, resolve as resolve5 } from "node:path";
 
 // src/source/readability.ts
 var CONTENT_MARKER = "data-ds-content";
@@ -10163,7 +10315,7 @@ function readContentRegion() {
 }
 
 // src/source/transcode.ts
-import { readFile as readFile12, rm as rm6 } from "node:fs/promises";
+import { readFile as readFile13, rm as rm6 } from "node:fs/promises";
 import { basename as basename2 } from "node:path";
 var CLIP_EDGE_PX = 1280;
 var MAX_CLIP_SECONDS = 60;
@@ -10226,7 +10378,7 @@ async function transcode(input, out, opts = {}) {
   const maxSeconds = opts.maxSeconds ?? MAX_CLIP_SECONDS;
   const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS;
   const name = basename2(input);
-  const source = videoSize(await readFile12(input));
+  const source = videoSize(await readFile13(input));
   const box = fitBox(source.width, source.height, opts.maxEdgePx ?? CLIP_EDGE_PX);
   const kept = (why3) => ({
     path: input,
@@ -10258,7 +10410,7 @@ async function transcode(input, out, opts = {}) {
   }
   let measured;
   try {
-    measured = videoSize(await readFile12(out));
+    measured = videoSize(await readFile13(out));
   } catch (err) {
     await rm6(out, { force: true });
     return kept(
@@ -10294,8 +10446,8 @@ var HTML_TYPES = /^text\/html$|^application\/xhtml\+xml$/;
 async function harvest(url2, dir, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS2;
   const warnings = [];
-  const assets = resolve4(dir);
-  await mkdir9(assets, { recursive: true });
+  const assets = resolve5(dir);
+  await mkdir10(assets, { recursive: true });
   const page = await fetchGuarded(url2, {
     maxBytes: opts.maxBytes ?? HTML_MAX_BYTES,
     timeoutMs,
@@ -10677,8 +10829,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
           `it is ${size3.width}x${size3.height}, under ${MIN_FIGURE_PX}px \u2014 spacers, icons and tracking pixels look like this, and a slide cannot use one`
         );
       }
-      const path2 = join11(dir, assetName(url2, extFor2(sniffFormat(bytes))));
-      await writeFile11(path2, bytes);
+      const path2 = join12(dir, assetName(url2, extFor2(sniffFormat(bytes))));
+      await writeFile12(path2, bytes);
       assets.push(path2);
       got = { path: path2, width: size3.width, height: size3.height };
     } catch (err) {
@@ -10690,7 +10842,7 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
   };
   const shrink = async (url2, path2, measured, what) => {
     if (opts.transcode === false) return { path: path2, ...measured };
-    const out2 = join11(dir, assetName(url2, ".vp9.webm"));
+    const out2 = join12(dir, assetName(url2, ".vp9.webm"));
     let small;
     try {
       small = await transcode(path2, out2, {
@@ -10732,8 +10884,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
     try {
       const bytes = await bytesOf(url2);
       const measured = videoSize(bytes);
-      const path2 = join11(dir, assetName(url2, `.${measured.container}`));
-      await writeFile11(path2, bytes);
+      const path2 = join12(dir, assetName(url2, `.${measured.container}`));
+      await writeFile12(path2, bytes);
       return await shrink(url2, path2, measured, what);
     } catch (err) {
       warnings.push(`${what} was not downloaded: ${url2} \u2014 ${why2(err)}`);
@@ -10822,7 +10974,7 @@ function unheld(policy) {
   return "the file could not be held";
 }
 async function sizeOf2(path2) {
-  return await stat(path2).then(
+  return await stat2(path2).then(
     (s) => s.size,
     () => 0
   );
@@ -11030,8 +11182,8 @@ function sane(seconds) {
 }
 async function attachClips(source, clips, dir) {
   if (clips.length === 0) return source;
-  const assets = resolve4(dir);
-  await mkdir9(assets, { recursive: true });
+  const assets = resolve5(dir);
+  await mkdir10(assets, { recursive: true });
   const figures = [...source.figures];
   for (const clip3 of clips) {
     const src = clip3.file ? await adopt(clip3.file, assets) : void 0;
@@ -11062,7 +11214,7 @@ async function attachClips(source, clips, dir) {
 }
 async function adopt(file, dir) {
   const name = basename3(file);
-  await copyFile(file, join11(dir, name));
+  await copyFile(file, join12(dir, name));
   return name;
 }
 function freeId(figures) {
@@ -11331,26 +11483,26 @@ function textOf(node) {
 
 // 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 tmpdir3 } from "node:os";
-import { basename as basename4, dirname as dirname4, join as join12, resolve as resolve5, sep } from "node:path";
+import { basename as basename4, dirname as dirname5, join as join13, resolve as resolve6, sep } from "node:path";
 var cached;
 function real(dir) {
-  let at = resolve5(dir);
+  let at = resolve6(dir);
   const tail3 = [];
   for (; ; ) {
     try {
-      return join12(realpathSync(at), ...tail3);
+      return join13(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) {
@@ -11378,8 +11530,8 @@ function guardTmpdir() {
 }
 
 // src/verify/index.ts
-import { readdir as readdir3, readFile as readFile16 } from "node:fs/promises";
-import { join as join16, relative, sep as sep2 } from "node:path";
+import { readdir as readdir4, readFile as readFile17 } from "node:fs/promises";
+import { join as join17, relative, sep as sep2 } from "node:path";
 
 // src/verify/budget.ts
 function readCanvas(html) {
@@ -11486,8 +11638,8 @@ function clock2(seconds) {
 
 // src/verify/check.ts
 import { execFile as execFile2 } from "node:child_process";
-import { readFile as readFile13 } from "node:fs/promises";
-import { join as join13 } from "node:path";
+import { readFile as readFile14 } from "node:fs/promises";
+import { join as join14 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 var run2 = promisify2(execFile2);
 var DEFAULT_TIMEOUT_MS3 = 24e4;
@@ -11517,7 +11669,7 @@ async function check2(dir, opts = {}) {
 async function readComposition(dir) {
   let html;
   try {
-    html = await readFile13(join13(dir, "index.html"), "utf8");
+    html = await readFile14(join14(dir, "index.html"), "utf8");
   } catch {
     return { transit: [], duration: 0 };
   }
@@ -11665,8 +11817,8 @@ function tail(s) {
 }
 
 // src/verify/fidelity.ts
-import { readFile as readFile14 } from "node:fs/promises";
-import { join as join14 } from "node:path";
+import { readFile as readFile15 } from "node:fs/promises";
+import { join as join15 } from "node:path";
 
 // src/verify/typefloor.ts
 var TYPE_FLOOR_PX = 40;
@@ -11922,6 +12074,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");
@@ -12088,6 +12250,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;
@@ -12112,11 +12293,10 @@ async function fidelity(dir, opts = {}) {
     ],
     elapsedMs: Date.now() - started
   });
-  const stops = opts.stops ?? readStops(
-    await readFile14(join14(dir, TIMING_FILE), "utf8").catch(() => null),
-    await readFile14(join14(dir, DECK_PAGE), "utf8").catch(() => null)
-  );
+  const timingText = await readFile15(join15(dir, TIMING_FILE), "utf8").catch(() => null);
+  const stops = opts.stops ?? readStops(timingText, await readFile15(join15(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 });
@@ -12145,7 +12325,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)) {
@@ -12156,6 +12342,7 @@ async function fidelity(dir, opts = {}) {
       stops: measured,
       findings: [
         ...gradeFidelity(measured, floor),
+        ...gradeReserve(measured),
         ...gradeOverprint(collided),
         ...gradeApparent(apparent)
       ],
@@ -12172,9 +12359,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 readFile15, rm as rm8 } from "node:fs/promises";
+import { mkdtemp as mkdtemp3, readdir as readdir3, readFile as readFile16, rm as rm8 } from "node:fs/promises";
 import { tmpdir as tmpdir4 } from "node:os";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 import { promisify as promisify3 } from "node:util";
 var run3 = promisify3(execFile3);
 var FLOOR_DB = 40;
@@ -12213,9 +12400,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(join15(tmpdir4(), "decksmith-drift-"));
-  const a = join15(work, "a");
-  const b = join15(work, "b");
+  const work = opts.workDir ?? await mkdtemp3(join16(tmpdir4(), "decksmith-drift-"));
+  const a = join16(work, "a");
+  const b = join16(work, "b");
   const report2 = await compare(dir, a, b, mode, floorDb, opts);
   const keep = opts.keep || !report2.passed;
   if (keep) report2.kept = { a, b };
@@ -12270,11 +12457,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(join15(a, name));
+    const one = await sha(join16(a, name));
     ha.push(one);
-    if (one !== await sha(join15(b, name))) differing.push(i + 1);
+    if (one !== await sha(join16(b, name))) differing.push(i + 1);
   }
-  const html = await readFile15(join15(dir, COMPOSITION_PAGE), "utf8").catch(() => "");
+  const html = await readFile16(join16(dir, COMPOSITION_PAGE), "utf8").catch(() => "");
   const motion = measureMotion(ha, readScenes(html), readCanvas(html)?.seconds ?? 0);
   let worst;
   if (differing.length > 0) {
@@ -12385,11 +12572,11 @@ async function render2(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 readFile15(file)).digest("hex");
+  return createHash9("sha256").update(await readFile16(file)).digest("hex");
 }
 var STAT = /^n:(\d+)\b.*\bpsnr_avg:(inf|-?[\d.]+)/;
 function framePattern(name) {
@@ -12422,11 +12609,11 @@ async function psnr(a, b, firstFrame) {
         "-start_number",
         String(seq.start),
         "-i",
-        join15(a, seq.pattern),
+        join16(a, seq.pattern),
         "-start_number",
         String(seq.start),
         "-i",
-        join15(b, seq.pattern),
+        join16(b, seq.pattern),
         "-lavfi",
         "psnr=stats_file=-",
         "-f",
@@ -12501,7 +12688,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 readFile16(join16(dir, DECK_PAGE), "utf8").catch(() => ""),
+    await readFile17(join17(dir, DECK_PAGE), "utf8").catch(() => ""),
     await listFiles(dir)
   );
   const budget3 = html.flatMap(([, text2]) => scanBudget(text2, storyboard, kept));
@@ -12538,8 +12725,8 @@ async function verify(dir, opts = {}, storyboard, kept, source) {
 }
 async function declaredStops(dir) {
   return readStops(
-    await readFile16(join16(dir, TIMING_FILE), "utf8").catch(() => null),
-    await readFile16(join16(dir, DECK_PAGE), "utf8").catch(() => null)
+    await readFile17(join17(dir, TIMING_FILE), "utf8").catch(() => null),
+    await readFile17(join17(dir, DECK_PAGE), "utf8").catch(() => null)
   );
 }
 var NARRATION_ISLAND = /<script type="application\/decksmith-narration\+json">([\s\S]*?)<\/script>/;
@@ -12579,7 +12766,7 @@ function scanNarration(page, files) {
   ];
 }
 async function readTiming2(dir) {
-  const raw2 = await readFile16(join16(dir, TIMING_FILE), "utf8").catch(() => "");
+  const raw2 = await readFile17(join17(dir, TIMING_FILE), "utf8").catch(() => "");
   if (!raw2) return void 0;
   try {
     const parsed = JSON.parse(raw2);
@@ -12589,9 +12776,9 @@ async function readTiming2(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, join16(e.parentPath, e.name)).split(sep2).join("/"))
+    entries.filter((e) => e.isFile()).map((e) => relative(dir, join17(e.parentPath, e.name)).split(sep2).join("/"))
   );
 }
 var INSTEAD = {
@@ -12847,72 +13034,35 @@ 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) => join16(e.parentPath, e.name));
+  ).map((e) => join17(e.parentPath, e.name));
   return Promise.all(
-    files.map(async (f) => [relative(dir, f), await readFile16(f, "utf8")])
+    files.map(async (f) => [relative(dir, f), await readFile17(f, "utf8")])
   );
 }
 
 // src/cli.ts
 guardTmpdir();
-var AUDIO_DIR = "audio";
 var NARRATION_FILE = "narration.json";
 var DEFAULTS = prefsSchema.parse({});
 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");
-  await mkdir10(join17(out, "katex/fonts"), { recursive: true });
-  for (const file of await readdir4(join17(dist, "fonts"))) {
-    if (file.endsWith(".woff2"))
-      await cp(join17(dist, "fonts", file), 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);
-}
-async function vendorScripts(out, composition) {
-  const require2 = createRequire4(import.meta.url);
-  await mkdir10(join17(out, "vendor"), { recursive: true });
-  const wanted = (name) => composition.includes(`./vendor/${name}`);
-  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 = join17(dirname5(require2.resolve(pkg)), rel);
-    await cp(from, join17(out, "vendor", name));
-  }
-  if (wanted("ds-morph.js")) {
-    await cp(
-      fileURLToPath(new URL("./ds-morph.js", import.meta.url)),
-      join17(out, "vendor", "ds-morph.js")
-    );
-  }
-}
 var HYPERFRAMES_JSON = `${JSON.stringify(
   {
     $schema: "https://hyperframes.heygen.com/schema/hyperframes.json",
@@ -13014,13 +13164,13 @@ program.command("ingest").description("Parse a document or a web page into sourc
   "--max-clip-seconds <n>",
   "URL only: seconds of each clip kept, the rest trimmed (maxClipSeconds; default 60)"
 ).option("--no-transcode", "URL only: ship each clip as the page served it, unshrunk").action(async (input, o) => {
-  const assets = join17(dirname5(resolve6(o.out)), "assets");
-  const scratch = url(input) ? await mkdtemp4(join17(tmpdir5(), "decksmith-harvest-")) : void 0;
+  const assets = join18(dirname6(resolve7(o.out)), "assets");
+  const scratch = url(input) ? await mkdtemp4(join18(tmpdir5(), "decksmith-harvest-")) : void 0;
   try {
     let md;
     let clips = [];
     if (scratch === void 0) {
-      md = await readFile17(resolve6(input), "utf8").catch(() => {
+      md = await readFile18(resolve7(input), "utf8").catch(() => {
         throw new Error(`Cannot read ${input}.`);
       });
     } else {
@@ -13041,7 +13191,7 @@ program.command("ingest").description("Parse a document or a web page into sourc
     const dropped = [];
     const source = await fetchFigures(withClips, assets, dropped);
     for (const why3 of dropped) step(`ingest: ${why3}`);
-    const bundle = await bundleFont(source.lang, glyphs(source), join17(assets, "fonts"));
+    const bundle = await bundleFont(source.lang, glyphs(source), join18(assets, "fonts"));
     if (bundle) step(`ingest: bundled ${bundle.family} for ${source.lang}`);
     await writeJson(o.out, source);
     step(`ingest: wrote ${o.out}`);
@@ -13102,7 +13252,7 @@ imageFlags(
   program.command("illustrate").description("Draw the pictures the plan asked for, and point the storyboard at them.").argument("<storyboard>", "storyboard.json carrying illustration briefs").requiredOption("--source <file>", "source.json the storyboard was planned from")
 ).action(async (sbPath, o) => {
   const storyboard = await readValidated(sbPath, storyboardSchema, "storyboard");
-  const sourcePath = resolve6(String(o.source));
+  const sourcePath = resolve7(String(o.source));
   const source = await readValidated(sourcePath, sourceSchema, "source");
   assertRefsResolve(storyboard, source, { pending: "allow" });
   const prefs = await loadPrefs(prefsFromFlags({ ...flags(o), images: true }));
@@ -13116,7 +13266,7 @@ imageFlags(
   );
   const drawn = await illustrate(storyboard, source, {
     prefs,
-    assetsDir: join17(dirname5(sourcePath), "assets"),
+    assetsDir: join18(dirname6(sourcePath), "assets"),
     onStep: step
   });
   for (const p of drawn.illustrated) {
@@ -13141,34 +13291,44 @@ voiceFlags(
   const format = pickFormat(String(o.format), o.width, o.height);
   const chosen = await loadPrefs(prefsFromFlags(flags(o)));
   const prefs = stated(chosen, "lang") ? chosen : { ...chosen, lang: storyboard.lang };
-  const dir = resolve6(String(o.out));
+  const dir = resolve7(String(o.out));
   const speaking = storyboard.beats.filter((b) => b.narration?.trim()).length;
   if (speaking === 0) {
     throw new Error(`No beat in ${sbPath} has a "narration" field, so there is nothing to speak.`);
   }
   step(`narrate: ${speaking} of ${storyboard.beats.length} beats have narration`);
   const narration = await narrate(storyboard, source, prefs, { dir, format });
-  await writeJson(join17(dir, NARRATION_FILE), narration);
+  await writeJson(join18(dir, NARRATION_FILE), narration);
   const segments2 = Object.values(narration.beats).flat();
   const seconds = segments2.reduce((sum, s) => sum + s.seconds, 0);
   step(
-    `narrate: ${segments2.length} segments, ${seconds.toFixed(1)}s in ${narration.voice} \u2192 ${join17(dir, NARRATION_FILE)}`
+    `narrate: ${segments2.length} segments, ${seconds.toFixed(1)}s in ${narration.voice} \u2192 ${join18(dir, NARRATION_FILE)}`
   );
 });
 lookFlags(
   sizeFlags(
-    lengthFlags(program.command("build")).description("Emit the composition, write its assets, and run the gates.").argument("<storyboard>", "storyboard.json, edited to taste").requiredOption("--source <file>", "source.json the storyboard was planned from").requiredOption("-o, --out <dir>", "directory to write the deck into").option("--format <id>", `output profile: ${Object.keys(FORMATS).join(" | ")}`, "deck-16x9").option("--min-weight <n>", "keep only beats at or above this weight \u2014 see the budget gate").option("--genre <genre>", "general | paper \u2014 report when a paper deck lacks its arc").option("--narration <file>", `${NARRATION_FILE} from \`decksmith narrate\``).option("--no-narration", "ignore narration sitting beside the storyboard").option("--no-fidelity", "skip the frame check \u2014 only for a machine with no browser")
+    lengthFlags(program.command("build")).description("Emit the composition, write its assets, and run the gates.").argument("<storyboard>", "storyboard.json, edited to taste").requiredOption("--source <file>", "source.json the storyboard was planned from").requiredOption("-o, --out <dir>", "directory to write the deck into").option("--format <id>", `output profile: ${Object.keys(FORMATS).join(" | ")}`, "deck-16x9").option("--min-weight <n>", "keep only beats at or above this weight \u2014 see the budget gate").option("--genre <genre>", "general | paper \u2014 report when a paper deck lacks its arc").option("--narration <file>", `${NARRATION_FILE} from \`decksmith narrate\``).option("--no-narration", "ignore narration sitting beside the storyboard").option(
+      "--reserve-captions",
+      "keep the bottom of the frame clear for a burned caption \u2014 required by `render --subtitles burn`"
+    ).option("--no-fidelity", "skip the frame check \u2014 only for a machine with no browser")
   )
 ).action(
   async (sbPath, o) => {
     const storyboard = await readValidated(sbPath, storyboardSchema, "storyboard");
     const source = await readValidated(o.source, sourceSchema, "source");
     assertRefsResolve(storyboard, source);
-    const format = withMinWeight(pickFormat(o.format, o.width, o.height), o.minWeight);
+    const format = withCaptionReserve(
+      withMinWeight(pickFormat(o.format, o.width, o.height), o.minWeight),
+      o.reserveCaptions === true
+    );
+    if (format.captionReserve)
+      step(
+        `build: reserving ${format.captionReserve}px at the bottom for burned captions \u2014 ${(100 * format.captionReserve / format.height).toFixed(1)}% of the frame`
+      );
     const prefs = await loadPrefs(prefsFromFlags(flags(o)), process.cwd(), source);
     const theme = stated(prefs, "theme") ?? storyboard.theme;
-    const out = resolve6(o.out);
-    await mkdir10(out, { recursive: true });
+    const out = resolve7(o.out);
+    await mkdir11(out, { recursive: true });
     const found = await findNarration(sbPath, o.narration);
     const narration = found ? await loadNarration(found) : void 0;
     if (narration) {
@@ -13181,7 +13341,7 @@ lookFlags(
     const paced = durationPlan(prefs, storyboard.beats.length);
     for (const f of scanBeatCount(storyboard, prefs)) step(`build: ${f.message}`);
     for (const w of paced.warnings) step(`build: ${w}`);
-    const fontCss = await refreshFont(storyboard, source, out);
+    const fontCss = await refreshFont(storyboard, source, out, step);
     const deck = emitDeck(storyboard, source, format, await deckRuntime(), {
       theme,
       ...fontCss ? { fontCss } : {},
@@ -13198,8 +13358,8 @@ lookFlags(
       // place anyone learns it is not.
       onBeatWarning: (id2, warning) => step(`build: kept ${id2} \u2014 ${warning}`)
     });
-    await writeFile12(join17(out, "index.html"), deck.composition);
-    await writeFile12(join17(out, "hyperframes.json"), HYPERFRAMES_JSON);
+    await writeFile13(join18(out, "index.html"), deck.composition);
+    await writeFile13(join18(out, "hyperframes.json"), HYPERFRAMES_JSON);
     await writeTiming(out, {
       storyboard,
       source,
@@ -13215,36 +13375,36 @@ lookFlags(
       ...narration ? { narration } : {}
     });
     if (deck.page) {
-      await writeFile12(join17(out, DECK_PAGE), deck.page);
-      await cp(playerBundle(), join17(out, PLAYER_FILE));
+      await writeFile13(join18(out, DECK_PAGE), deck.page);
+      await cp2(playerBundle(), join18(out, PLAYER_FILE));
     }
     await vendorKatex(out);
     await vendorScripts(out, deck.composition);
-    await copyAssets(dirname5(resolve6(o.source)), out, source.figures);
-    if (found && narration) await copyAudio(dirname5(found), narration, out);
+    await copyAssets(dirname6(resolve7(o.source)), out, source.figures, step);
+    if (found && narration) await copyAudio(dirname6(found), narration, out, step);
     const look = [theme, paced.speed === 1 ? "" : `${paced.speed}\xD7 speed`].filter(Boolean).join(", ");
     const { cut } = deck;
     const floor = cut.dropped.filter((d) => d.rule === "below_min_weight").length;
     const of = cut.kept.length === storyboard.beats.length ? "" : ` of ${storyboard.beats.length}`;
     step(
-      `build: ${cut.kept.length}${of} beats at ${format.width}\xD7${format.height} in ${look}${floor > 0 ? ` (${floor} below minWeight ${format.minWeight})` : ""} \u2192 ${join17(out, "index.html")}`
+      `build: ${cut.kept.length}${of} beats at ${format.width}\xD7${format.height} in ${look}${floor > 0 ? ` (${floor} below minWeight ${format.minWeight})` : ""} \u2192 ${join18(out, "index.html")}`
     );
     for (const f of scanPaperArc({ ...storyboard, beats: cut.kept }, prefs))
       step(`build: ${f.message}`);
     reportCut(cut);
-    if (deck.page) step(`build: navigable deck \u2192 ${join17(out, DECK_PAGE)}`);
+    if (deck.page) step(`build: navigable deck \u2192 ${join18(out, DECK_PAGE)}`);
     await gate(out, false, storyboard, cut.kept, o.fidelity !== false, source);
   }
 );
 program.command("verify").description("Re-run the gates on a built deck.").argument("<dir>", "a built deck directory").option("--snapshots", "also write the contrast-pass PNGs to <dir>/snapshots", false).option("--no-fidelity", "skip the frame check \u2014 only for a machine with no browser").action(async (dir, o) => {
-  await gate(resolve6(dir), o.snapshots, void 0, void 0, o.fidelity !== false);
+  await gate(resolve7(dir), o.snapshots, void 0, void 0, o.fidelity !== false);
 });
 program.command("frames").description("Write PNGs of a built deck through the capture path the renderer uses.").argument("<dir>", "a built deck directory").option(
   "--at <seconds...>",
   "absolute times to photograph; defaults to every hold the deck declares"
 ).option("--out <dir>", "where to write the PNGs (default: <dir>/frames)").action(async (dir, o) => {
-  const deck = resolve6(dir);
-  const out = resolve6(o.out ?? join17(deck, "frames"));
+  const deck = resolve7(dir);
+  const out = resolve7(o.out ?? join18(deck, "frames"));
   let times;
   if (o.at?.length) {
     times = o.at.map((raw2) => {
@@ -13254,8 +13414,8 @@ program.command("frames").description("Write PNGs of a built deck through the ca
     });
   } else {
     times = readStops(
-      await readFile17(join17(deck, TIMING_FILE), "utf8").catch(() => null),
-      await readFile17(join17(deck, DECK_PAGE), "utf8").catch(() => null)
+      await readFile18(join18(deck, TIMING_FILE), "utf8").catch(() => null),
+      await readFile18(join18(deck, DECK_PAGE), "utf8").catch(() => null)
     ).map((s) => s.t);
     if (times.length === 0)
       throw new Error(
@@ -13269,7 +13429,7 @@ program.command("frames").description("Write PNGs of a built deck through the ca
 program.command("drift").description("Render a built deck twice and compare, frame by frame. Minutes, not seconds.").argument("<dir>", "a built deck directory").option("--identical", "require every frame byte-identical \u2014 image-free decks only", false).option("--floor <dB>", "per-frame PSNR floor", String(FLOOR_DB)).option("--keep", "keep both frame directories even when they agree").option("--workers <n>", "pin both renders to one worker count (default: 1 vs 3)").action(
   async (dir, o) => {
     step("drift: rendering twice, several minutes a render");
-    const verdict = await drift(resolve6(dir), {
+    const verdict = await drift(resolve7(dir), {
       mode: o.identical ? "identical" : "psnr",
       floorDb: Number(o.floor),
       ...o.keep ? { keep: true } : {},
@@ -13296,8 +13456,8 @@ program.command("render").description("Render a built deck to a finished video:
       throw new Error(`Unknown --subtitles "${o.subtitles}". Use sidecar, burn or none.`);
     }
     const result = await render({
-      deck: resolve6(dir),
-      out: resolve6(o.out),
+      deck: resolve7(dir),
+      out: resolve7(o.out),
       subtitles: o.subtitles,
       protocolTimeoutMs: Number(o.protocolTimeout),
       log: step,
@@ -13325,7 +13485,7 @@ voiceFlags(
   )
 ).action(async (sbPath, o) => {
   const storyboard = await readValidated(sbPath, storyboardSchema, "storyboard");
-  const sourcePath = resolve6(String(o.source));
+  const sourcePath = resolve7(String(o.source));
   const source = await readValidated(sourcePath, sourceSchema, "source");
   assertRefsResolve(storyboard, source);
   if (o.bake && o.link) throw new Error("Choose --bake or --link, not both.");
@@ -13340,7 +13500,7 @@ voiceFlags(
   const prefer = o.link ? "link" : "bake";
   const plan = await planMedia(figureAssets(source, sourcePath, prefer));
   const files = { ...plan.files };
-  if (found && narration) Object.assign(files, await audioFiles(dirname5(found), narration));
+  if (found && narration) Object.assign(files, await audioFiles(dirname6(found), narration));
   const pack2 = {
     version: PACK_VERSION,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -13355,7 +13515,7 @@ voiceFlags(
     ...narration ? { narration } : {},
     media: plan.media
   };
-  const out = resolve6(String(o.out));
+  const out = resolve7(String(o.out));
   const bytes = await writePack(pack2, files, out);
   if (plan.demoted.length) {
     step(`pack: kept as links, not bakeable \u2014 ${plan.demoted.join(", ")}`);
@@ -13369,19 +13529,19 @@ voiceFlags(
   step(`pack: ${size2(bytes)} \u2192 ${out}`);
 });
 program.command("unpack").description("Open a .deck back into the files build reads.").argument("<file>", "a .deck archive").requiredOption("-o, --out <dir>", "directory to open it into").action(async (file, o) => {
-  const { pack: pack2, files } = await readPack(resolve6(file));
-  const out = resolve6(o.out);
-  await writeJson(join17(out, "source.json"), pack2.source);
-  await writeJson(join17(out, "storyboard.json"), pack2.storyboard);
-  await writeJson(join17(out, "decksmith.config.json"), pack2.prefs);
-  if (pack2.narration) await writeJson(join17(out, AUDIO_DIR, NARRATION_FILE), pack2.narration);
+  const { pack: pack2, files } = await readPack(resolve7(file));
+  const out = resolve7(o.out);
+  await writeJson(join18(out, "source.json"), pack2.source);
+  await writeJson(join18(out, "storyboard.json"), pack2.storyboard);
+  await writeJson(join18(out, "decksmith.config.json"), pack2.prefs);
+  if (pack2.narration) await writeJson(join18(out, AUDIO_DIR, NARRATION_FILE), pack2.narration);
   const figures = new Map(pack2.source.figures.map((f) => [f.id, f.src]));
   for (const [path2, bytes] of Object.entries(files)) {
     const media = pack2.media.find((m) => m.path === path2);
     const src = media && figures.get(media.id);
-    const to = src ? join17("assets", src) : path2;
-    await mkdir10(dirname5(join17(out, to)), { recursive: true });
-    await writeFile12(join17(out, to), bytes);
+    const to = src ? join18("assets", src) : path2;
+    await mkdir11(dirname6(join18(out, to)), { recursive: true });
+    await writeFile13(join18(out, to), bytes);
   }
   const linked = pack2.media.filter((m) => m.policy !== "bake");
   step(`unpack: "${pack2.title}", ${pack2.storyboard.beats.length} beats \u2192 ${out}`);
@@ -13391,7 +13551,7 @@ program.command("unpack").description("Open a .deck back into the files build re
     );
   }
   step(
-    `unpack: decksmith build ${join17(relative2(process.cwd(), out) || ".", "storyboard.json")} --source ${join17(relative2(process.cwd(), out) || ".", "source.json")} -o deck`
+    `unpack: decksmith build ${join18(relative2(process.cwd(), out) || ".", "storyboard.json")} --source ${join18(relative2(process.cwd(), out) || ".", "source.json")} -o deck`
   );
 });
 program.parseAsync(process.argv).catch((err) => {
@@ -13412,7 +13572,7 @@ async function gate(dir, snapshots = false, storyboard, kept, fidelity2 = true,
   );
   const verdict = await verify(dir, { snapshots, fidelity: fidelity2 }, storyboard, kept, source);
   process.stdout.write(report(verdict));
-  if (snapshots) step(`verify: snapshots in ${join17(dir, "snapshots")}`);
+  if (snapshots) step(`verify: snapshots in ${join18(dir, "snapshots")}`);
   if (!verdict.passed) process.exitCode = 1;
 }
 function report(v) {
@@ -13429,13 +13589,13 @@ function report(v) {
 async function findNarration(sbPath, flag) {
   if (flag === false) return void 0;
   if (typeof flag === "string") {
-    const path2 = resolve6(flag);
-    if (!await stat2(path2).catch(() => null)) throw new Error(`Cannot read narration ${flag}.`);
+    const path2 = resolve7(flag);
+    if (!await stat3(path2).catch(() => null)) throw new Error(`Cannot read narration ${flag}.`);
     return path2;
   }
-  const beside = dirname5(resolve6(sbPath));
-  for (const candidate of [join17(beside, AUDIO_DIR, NARRATION_FILE), join17(beside, NARRATION_FILE)]) {
-    if (await stat2(candidate).catch(() => null)) {
+  const beside = dirname6(resolve7(sbPath));
+  for (const candidate of [join18(beside, AUDIO_DIR, NARRATION_FILE), join18(beside, NARRATION_FILE)]) {
+    if (await stat3(candidate).catch(() => null)) {
       step(`narration: using ${candidate}`);
       return candidate;
     }
@@ -13446,28 +13606,10 @@ async function loadNarration(path2) {
   const narration = await readValidated(path2, narrationSchema, "narration");
   return { voice: narration.voice, dir: AUDIO_DIR, beats: narration.beats };
 }
-function audioNames(narration) {
-  return [
-    ...new Set(
-      Object.values(narration.beats).flat().map((s) => s.audio)
-    )
-  ].sort();
-}
-async function copyAudio(from, narration, out) {
-  const dir = join17(out, AUDIO_DIR);
-  await mkdir10(dir, { recursive: true });
-  const names = audioNames(narration);
-  for (const name of names) {
-    await cp(join17(from, name), join17(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}`);
-}
 async function audioFiles(from, narration) {
   const files = {};
   for (const name of audioNames(narration)) {
-    const bytes = await readFile17(join17(from, name)).catch(() => {
+    const bytes = await readFile18(join18(from, name)).catch(() => {
       throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
     });
     files[`${AUDIO_DIR}/${name}`] = new Uint8Array(bytes);
@@ -13489,9 +13631,9 @@ function wrapScript(text2, width) {
 async function writeTiming(out, input) {
   try {
     const timing = planTiming(input);
-    await writeJson(join17(out, TIMING_FILE), timing);
+    await writeJson(join18(out, TIMING_FILE), timing);
     step(
-      `build: timing for ${timing.segments.length} narration segment(s) \u2192 ${join17(out, TIMING_FILE)}`
+      `build: timing for ${timing.segments.length} narration segment(s) \u2192 ${join18(out, TIMING_FILE)}`
     );
   } catch (err) {
     step(
@@ -13500,10 +13642,10 @@ async function writeTiming(out, input) {
   }
 }
 function figureAssets(source, sourcePath, prefer) {
-  const assets = join17(dirname5(sourcePath), "assets");
+  const assets = join18(dirname6(sourcePath), "assets");
   return source.figures.map((f) => ({
     id: f.id,
-    url: /^[a-z][a-z0-9+.-]*:/i.test(f.src) ? f.src : join17(assets, f.src),
+    url: /^[a-z][a-z0-9+.-]*:/i.test(f.src) ? f.src : join18(assets, f.src),
     prefer
   }));
 }
@@ -13521,6 +13663,10 @@ function pickFormat(id2, width, height) {
   for (const warning of canvasWarnings(format.width, format.height)) step(`format: ${warning}`);
   return format;
 }
+function withCaptionReserve(format, on) {
+  if (!on) return format;
+  return { ...format, captionReserve: bandReserve(format.width, format.height) };
+}
 function sizeFlags(cmd) {
   return cmd.option("--width <px>", `canvas width in pixels (${MIN_EDGE}\u2013${MAX_EDGE})`).option("--height <px>", `canvas height in pixels (${MIN_EDGE}\u2013${MAX_EDGE})`);
 }
@@ -13531,52 +13677,11 @@ function withMinWeight(format, raw2) {
     throw new Error(`--min-weight takes a number from 0 to 1, not "${raw2}".`);
   return { ...format, minWeight };
 }
-async function copyAssets(sourceDir, out, figures) {
-  const from = join17(sourceDir, "assets");
-  if (!await stat2(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 mkdir10(join17(out, "assets"), { recursive: true });
-  let copied = 0;
-  for (const name of wanted) {
-    const src = resolve6(join17(from, name));
-    if (!src.startsWith(`${resolve6(from)}/`)) continue;
-    if (!await stat2(src).catch(() => null)) continue;
-    await mkdir10(dirname5(join17(out, "assets", name)), { recursive: true });
-    await cp(src, join17(out, "assets", name));
-    copied++;
-  }
-  const fonts = join17(from, "fonts");
-  if (await stat2(fonts).catch(() => null)) {
-    await cp(fonts, join17(out, "assets", "fonts"), { recursive: true });
-  }
-  step(`build: copied ${copied} referenced figure(s)`);
-}
-async function refreshFont(storyboard, source, out) {
-  try {
-    const bundle = await bundleFont(
-      storyboard.lang,
-      glyphs(source) + glyphs(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;
-  }
-}
 function glyphs(value) {
   return JSON.stringify(value);
 }
 async function readValidated(file, schema, label) {
-  const text2 = await readFile17(resolve6(file), "utf8").catch(() => {
+  const text2 = await readFile18(resolve7(file), "utf8").catch(() => {
     throw new Error(`Cannot read ${label} file ${file}.`);
   });
   let json;
@@ -13594,9 +13699,9 @@ ${issues}`);
   return parsed.data;
 }
 async function writeJson(file, value) {
-  const path2 = resolve6(file);
-  await mkdir10(dirname5(path2), { recursive: true });
-  await writeFile12(path2, `${JSON.stringify(value, null, 2)}
+  const path2 = resolve7(file);
+  await mkdir11(dirname6(path2), { recursive: true });
+  await writeFile13(path2, `${JSON.stringify(value, null, 2)}
 `);
 }
 function size2(bytes) {