npm - @jokerized/decksmith - Versions diffs - 0.4.0 → 0.5.0 - Mend

@jokerized/decksmith 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +13 -3
package/dist/cli.js +529 -388
package/dist/deck-runtime.js +5 -2
package/dist/index.js +490 -316
package/dist/mcp.js +409 -307
package/dist/types/build/files.d.ts +102 -0
package/dist/types/deck/runtime.d.ts +4 -2
package/dist/types/emit/kit.d.ts +32 -0
package/dist/types/index.d.ts +10 -6
package/dist/types/render/capture.d.ts +27 -1
package/dist/types/render/render.d.ts +40 -12
package/dist/types/render/timing.d.ts +11 -0
package/dist/types/types.d.ts +64 -0
package/dist/types/verify/fidelity.d.ts +55 -0
package/dist/types/verify/index.d.ts +8 -3
package/package.json +2 -2

package/dist/cli.js CHANGED Viewed

@@ -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,45 +9056,65 @@ 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 chromePath(need = "open the deck with") {
-  const explicit = process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
-  if (explicit) return explicit;
+async function resolveChrome(need = "open the deck with") {
+  const env = process.env.HYPERFRAMES_BROWSER_PATH || process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
+  if (env) return { path: env, source: "env" };
   const { getInstalledBrowsers } = await import("@puppeteer/browsers");
-  const cacheDir = process.env.PUPPETEER_CACHE_DIR || join8(homedir2(), ".cache", "puppeteer");
-  const installed2 = await getInstalledBrowsers({ cacheDir }).catch(() => []);
-  const found = installed2.find((b) => b.browser === "chrome-headless-shell") ?? installed2.find((b) => b.browser === "chrome");
-  if (found) return found.executablePath;
+  const pick = async (cacheDir) => {
+    const installed2 = await getInstalledBrowsers({ cacheDir }).catch(() => []);
+    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(join9(homedir2(), ".cache", "hyperframes", "chrome"));
+  if (hf) return { path: hf.executablePath, source: "hyperframes" };
+  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.`
   );
 }
+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);
   if (!width || !height) throw new Error("index.html declares no canvas size");
   const timeout = opts.timeoutMs ?? 6e4;
   const { default: puppeteer } = await import("puppeteer-core");
+  const chrome2 = await resolveChrome();
   const browser = await puppeteer.launch({
-    executablePath: await chromePath(),
+    executablePath: chrome2.path,
     headless: true,
-    // A retina host would otherwise hand back a 2x frame, whose clip is not the
-    // renderer's.
-    args: ["--force-device-scale-factor=1", "--hide-scrollbars"]
+    args: [
+      // A retina host would otherwise hand back a 2x frame, whose clip is not the
+      // renderer's.
+      "--force-device-scale-factor=1",
+      "--hide-scrollbars",
+      // WITHOUT THESE A WebGL CANVAS GETS NO CONTEXT AND SCREENSHOTS EMPTY. The
+      // renderer passes its own GL arguments; this path passed none, so it drew
+      // a blank rectangle and reported success. SwiftShader rather than the host
+      // GPU on purpose: it is the one backend available on every machine, and a
+      // gate that quietly follows the host's hardware is measuring the host.
+      "--use-gl=angle",
+      "--use-angle=swiftshader",
+      "--enable-unsafe-swiftshader"
+    ]
   });
   try {
     const page = await browser.newPage();
@@ -8971,6 +9130,18 @@ async function openDeck(dir, opts = {}) {
       { timeout }
     );
     await page.evaluate(() => document.fonts.ready);
+    const canvas = await page.evaluate(() => {
+      const el = document.querySelector("canvas");
+      if (!el) return { present: false, gl: true };
+      const probe2 = document.createElement("canvas");
+      const gl = !!(probe2.getContext("webgl2") ?? probe2.getContext("webgl"));
+      return { present: true, gl };
+    });
+    if (canvas.present && !canvas.gl) {
+      throw new Error(
+        `this deck draws on a <canvas> and ${chrome2.path} cannot create a WebGL context, so the capture would be of an empty rectangle. Chrome came from ${chrome2.source}; the renderer uses hyperframes' own shell. Set HYPERFRAMES_BROWSER_PATH to the binary \`hyperframes render\` uses so the gate and the render are the same browser.`
+      );
+    }
     const cdp = await page.createCDPSession();
     return {
       width,
@@ -9000,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 = [];
@@ -9008,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;
@@ -9020,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
@@ -9224,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
   };
@@ -9412,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),
@@ -9436,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 }
@@ -9492,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(
@@ -9500,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(
@@ -9627,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)
   };
 }
@@ -9643,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(
@@ -9657,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`
@@ -9676,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",
@@ -9717,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.`
     );
@@ -9757,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",
@@ -9792,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];
@@ -9813,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);
   }
@@ -9829,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";
@@ -10131,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;
@@ -10194,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,
@@ -10226,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(
@@ -10262,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,
@@ -10324,7 +10508,11 @@ async function readInBrowser(html, timeoutMs) {
       "--disable-background-networking",
       "--disable-extensions",
       "--no-default-browser-check",
-      "--no-first-run"
+      "--no-first-run",
+      // The floor under interception — see the note above. Not a hardening
+      // nicety: without it the open-proxy property holds only as fast as CDP
+      // happens to be that run.
+      "--host-resolver-rules=MAP * ~NOTFOUND"
     ]
   });
   try {
@@ -10641,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) {
@@ -10654,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, {
@@ -10696,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)}`);
@@ -10786,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
   );
@@ -10994,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;
@@ -11026,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) {
@@ -11295,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) {
@@ -11342,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) {
@@ -11450,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;
@@ -11481,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 };
   }
@@ -11629,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;
@@ -11886,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");
@@ -12052,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;
@@ -12076,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 });
@@ -12109,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)) {
@@ -12120,6 +12342,7 @@ async function fidelity(dir, opts = {}) {
       stops: measured,
       findings: [
         ...gradeFidelity(measured, floor),
+        ...gradeReserve(measured),
         ...gradeOverprint(collided),
         ...gradeApparent(apparent)
       ],
@@ -12136,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;
@@ -12177,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 };
@@ -12234,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) {
@@ -12349,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) {
@@ -12386,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",
@@ -12465,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));
@@ -12502,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>/;
@@ -12543,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);
@@ -12553,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 = {
@@ -12811,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",
@@ -12978,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 {
@@ -13005,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}`);
@@ -13066,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 }));
@@ -13080,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) {
@@ -13105,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) {
@@ -13145,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 } : {},
@@ -13162,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,
@@ -13179,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) => {
@@ -13218,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(
@@ -13233,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 } : {},
@@ -13260,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,
@@ -13289,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.");
@@ -13304,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(),
@@ -13319,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(", ")}`);
@@ -13333,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}`);
@@ -13355,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) => {
@@ -13376,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) {
@@ -13393,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;
     }
@@ -13410,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);
@@ -13453,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(
@@ -13464,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
   }));
 }
@@ -13485,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})`);
 }
@@ -13495,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;
@@ -13558,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) {