@jokerized/decksmith 0.4.1 → 0.5.0

package/dist/mcp.js

@@ -61,21 +61,185 @@ var VERSION = createRequire2(import.meta.url)("../package.json").version;
 
 // src/mcp/tools.ts
 import { randomBytes } from "node:crypto";
-import { mkdir as mkdir11, mkdtemp as mkdtemp3, readFile as readFile13, rm as rm8 } from "node:fs/promises";
+import { mkdir as mkdir12, mkdtemp as mkdtemp3, readFile as readFile14, rm as rm8 } from "node:fs/promises";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename as basename5, isAbsolute as isAbsolute2, join as join14, resolve as resolve7, sep as sep3 } from "node:path";
+import { basename as basename5, isAbsolute as isAbsolute2, join as join15, resolve as resolve8, sep as sep3 } from "node:path";
 import { zipSync as zipSync2 } from "fflate";
 import { z as z5 } from "zod";
 
 // src/index.ts
-import { cp, mkdir as mkdir9, readdir as readdir2, readFile as readFile11, stat as stat2, writeFile as writeFile11 } from "node:fs/promises";
+import { cp as cp2, mkdir as mkdir10, readFile as readFile12, writeFile as writeFile12 } from "node:fs/promises";
+import { createRequire as createRequire4 } from "node:module";
+import { dirname as dirname5, join as join13, resolve as resolve6 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/build/files.ts
+import { cp, mkdir as mkdir2, readdir, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
 import { createRequire as createRequire3 } from "node:module";
-import { dirname as dirname4, join as join12, resolve as resolve5 } from "node:path";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// src/pack/media.ts
+// src/source/fonts.ts
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function familyFor(lang) {
+  const tag = lang.toLowerCase();
+  if (tag.startsWith("ko")) return "Noto Sans KR";
+  if (tag.startsWith("ja")) return "Noto Sans JP";
+  if (tag.startsWith("zh")) return /hant|-tw|-hk|-mo/.test(tag) ? "Noto Sans TC" : "Noto Sans SC";
+  return null;
+}
+var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36";
+async function bundleFont(lang, glyphs, dir) {
+  const family = familyFor(lang);
+  if (!family) return null;
+  const text2 = [...new Set(glyphs)].filter((c) => c > " ").sort().join("");
+  const stamp = `/* decksmith ${createHash("sha256").update(`${family}
+${text2}`).digest("hex").slice(0, 16)} */`;
+  await mkdir(dir, { recursive: true });
+  const cssPath = join2(dir, "fonts.css");
+  const cached2 = await readFile(cssPath, "utf8").catch(() => "");
+  if (cached2.startsWith(stamp)) return { family, css: cached2, files: localNames(cached2) };
+  const res = await fetch(
+    `https://fonts.googleapis.com/css2?family=${family.replaceAll(" ", "+")}:wght@400;500;700&text=${encodeURIComponent(text2)}&display=block`,
+    { headers: { "User-Agent": UA } }
+  );
+  if (!res.ok) throw new Error(`google fonts: HTTP ${res.status}`);
+  let css = await res.text();
+  const remote = [...new Set([...css.matchAll(/url\((https:[^)]+)\)/g)].map((m) => m[1] ?? ""))];
+  const slug = family.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const files = [];
+  for (const [i, url] of remote.entries()) {
+    const font = await fetch(url);
+    if (!font.ok) throw new Error(`${url}: HTTP ${font.status}`);
+    const name = `${slug}-${i}.woff2`;
+    await writeFile(join2(dir, name), Buffer.from(await font.arrayBuffer()));
+    css = css.replaceAll(url, name);
+    files.push(name);
+  }
+  css = `${stamp}
+${css}`;
+  await writeFile(cssPath, css);
+  return { family, css, files };
+}
+function localNames(css) {
+  return [...css.matchAll(/url\(([^)]+)\)/g)].map((m) => m[1] ?? "");
+}
+
+// src/build/files.ts
+function audioNames(narration) {
+  return [
+    ...new Set(
+      Object.values(narration.beats).flat().map((s) => s.audio)
+    )
+  ].sort();
+}
+async function vendorKatex(out) {
+  const require2 = createRequire3(import.meta.url);
+  const dist = join3(dirname2(require2.resolve("katex/package.json")), "dist");
+  const css = await readFile2(join3(dist, "katex.min.css"), "utf8");
+  const written = [];
+  await mkdir2(join3(out, "katex/fonts"), { recursive: true });
+  for (const file of await readdir(join3(dist, "fonts"))) {
+    if (!file.endsWith(".woff2")) continue;
+    await cp(join3(dist, "fonts", file), join3(out, "katex/fonts", file));
+    written.push(join3(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(join3(out, "katex/katex.min.css"), woff2Only);
+  written.push(join3(out, "katex/katex.min.css"));
+  return written;
+}
+async function vendorScripts(out, composition) {
+  const require2 = createRequire3(import.meta.url);
+  await mkdir2(join3(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 = join3(dirname2(require2.resolve(pkg)), rel);
+    await cp(from, join3(out, "vendor", name));
+    written.push(join3(out, "vendor", name));
+  }
+  if (wanted("ds-morph.js")) {
+    await cp(
+      fileURLToPath(new URL("./ds-morph.js", import.meta.url)),
+      join3(out, "vendor", "ds-morph.js")
+    );
+    written.push(join3(out, "vendor", "ds-morph.js"));
+  }
+  return written;
+}
+async function copyAssets(sourceDir, out, figures, step) {
+  const from = join3(resolve2(sourceDir), "assets");
+  if (!await stat(from).catch(() => null)) {
+    step(`build: no assets/ beside source.json, skipping`);
+    return [];
+  }
+  const wanted = new Set(
+    figures.flatMap((f) => [f.src, f.poster]).filter((n3) => n3 !== void 0).map((n3) => n3.replace(/^\.?\//, ""))
+  );
+  await mkdir2(join3(out, "assets"), { recursive: true });
+  const written = [];
+  let copied = 0;
+  for (const name of wanted) {
+    const src = resolve2(join3(from, name));
+    if (!src.startsWith(`${from}/`)) continue;
+    if (!await stat(src).catch(() => null)) continue;
+    await mkdir2(dirname2(join3(out, "assets", name)), { recursive: true });
+    await cp(src, join3(out, "assets", name));
+    written.push(join3(out, "assets", name));
+    copied++;
+  }
+  const fonts = join3(from, "fonts");
+  if (await stat(fonts).catch(() => null)) {
+    await cp(fonts, join3(out, "assets", "fonts"), { recursive: true });
+    written.push(join3(out, "assets", "fonts"));
+  }
+  step(`build: copied ${copied} referenced figure(s)`);
+  return written;
+}
+async function copyAudio(from, narration, out, step) {
+  const dir = join3(out, narration.dir);
+  await mkdir2(dir, { recursive: true });
+  const names = audioNames(narration);
+  for (const name of names) {
+    await cp(join3(resolve2(from), name), join3(dir, name)).catch(() => {
+      throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
+    });
+  }
+  step(`narration: ${names.length} audio file(s) \u2192 ${dir}`);
+  return names.map((n3) => join3(dir, n3));
+}
+async function refreshFont(storyboard, source, out, step) {
+  try {
+    const bundle = await bundleFont(
+      storyboard.lang,
+      JSON.stringify(source) + JSON.stringify(storyboard),
+      join3(out, "assets", "fonts")
+    );
+    if (bundle) step(`build: font bundle covers ${bundle.family}`);
+    return bundle?.css;
+  } catch (err) {
+    step(
+      `build: could not refresh the font bundle (${err instanceof Error ? err.message : err}); keeping the one from ingest`
+    );
+    return void 0;
+  }
+}
+
+// src/pack/media.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFile as readFile3 } from "node:fs/promises";
 import { extname } from "node:path";
 var PLAYERS = [
   "youtube.com",
@@ -240,7 +404,7 @@ async function planMedia(assets, fetcher = fetchAsset) {
 }
 function bakedName(id2, url, mime) {
   const slug = id2.toLowerCase().replace(/[^a-z0-9_-]+/g, "-") || "asset";
-  const hash = createHash("sha256").update(url).digest("hex").slice(0, 8);
+  const hash = createHash2("sha256").update(url).digest("hex").slice(0, 8);
   return `${slug}-${hash}${extOf(url) || extFor(mime)}`;
 }
 function extOf(url) {
@@ -284,7 +448,7 @@ async function fetchAsset(url) {
       mime: res.headers.get("content-type") ?? void 0
     };
   }
-  return { bytes: new Uint8Array(await readFile(url)) };
+  return { bytes: new Uint8Array(await readFile3(url)) };
 }
 
 // src/types.ts
@@ -941,6 +1105,12 @@ 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;
+function captionFontSize(width) {
+  return Math.round(width * CAPTION_FONT_RATIO);
+}
 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.
@@ -1254,54 +1424,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 as join2 } from "node:path";
-function familyFor(lang) {
-  const tag = lang.toLowerCase();
-  if (tag.startsWith("ko")) return "Noto Sans KR";
-  if (tag.startsWith("ja")) return "Noto Sans JP";
-  if (tag.startsWith("zh")) return /hant|-tw|-hk|-mo/.test(tag) ? "Noto Sans TC" : "Noto Sans SC";
-  return null;
-}
-var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36";
-async function bundleFont(lang, glyphs, dir) {
-  const family = familyFor(lang);
-  if (!family) return null;
-  const text2 = [...new Set(glyphs)].filter((c) => c > " ").sort().join("");
-  const stamp = `/* decksmith ${createHash2("sha256").update(`${family}
-${text2}`).digest("hex").slice(0, 16)} */`;
-  await mkdir(dir, { recursive: true });
-  const cssPath = join2(dir, "fonts.css");
-  const cached2 = await readFile2(cssPath, "utf8").catch(() => "");
-  if (cached2.startsWith(stamp)) return { family, css: cached2, files: localNames(cached2) };
-  const res = await fetch(
-    `https://fonts.googleapis.com/css2?family=${family.replaceAll(" ", "+")}:wght@400;500;700&text=${encodeURIComponent(text2)}&display=block`,
-    { headers: { "User-Agent": UA } }
-  );
-  if (!res.ok) throw new Error(`google fonts: HTTP ${res.status}`);
-  let css = await res.text();
-  const remote = [...new Set([...css.matchAll(/url\((https:[^)]+)\)/g)].map((m) => m[1] ?? ""))];
-  const slug = family.toLowerCase().replace(/[^a-z0-9]/g, "");
-  const files = [];
-  for (const [i, url] of remote.entries()) {
-    const font = await fetch(url);
-    if (!font.ok) throw new Error(`${url}: HTTP ${font.status}`);
-    const name = `${slug}-${i}.woff2`;
-    await writeFile(join2(dir, name), Buffer.from(await font.arrayBuffer()));
-    css = css.replaceAll(url, name);
-    files.push(name);
-  }
-  css = `${stamp}
-${css}`;
-  await writeFile(cssPath, css);
-  return { family, css, files };
-}
-function localNames(css) {
-  return [...css.matchAll(/url\(([^)]+)\)/g)].map((m) => m[1] ?? "");
-}
-
 // src/emit/kit.ts
 var PAD_X = 110;
 var PAD_Y = 84;
@@ -1320,7 +1442,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 };
@@ -1819,8 +1946,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) {
@@ -2081,11 +2208,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 "";
@@ -6413,6 +6545,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
   };
@@ -6705,8 +6841,8 @@ function textOf(node) {
 
 // src/source/harvest.ts
 import { createHash as createHash5 } from "node:crypto";
-import { copyFile, mkdir as mkdir3, rm as rm2, stat, writeFile as writeFile3 } from "node:fs/promises";
-import { basename as basename3, join as join5, resolve as resolve2 } from "node:path";
+import { copyFile, mkdir as mkdir4, rm as rm2, stat as stat2, writeFile as writeFile4 } from "node:fs/promises";
+import { basename as basename3, join as join6, resolve as resolve3 } from "node:path";
 
 // src/net/fetch.ts
 import { lookup as resolveHost } from "node:dns/promises";
@@ -6906,8 +7042,8 @@ async function send(url, target, headers, signal, opts) {
     ...secure && isIP(host2) === 0 ? { servername: host2 } : {}
   };
   try {
-    return await new Promise((resolve8, reject) => {
-      const req = (secure ? httpsRequest : httpRequest)(options, resolve8);
+    return await new Promise((resolve9, reject) => {
+      const req = (secure ? httpsRequest : httpRequest)(options, resolve9);
       req.on("error", reject);
       req.end();
     });
@@ -6991,7 +7127,7 @@ function message(err) {
 
 // src/render/capture.ts
 import { homedir } from "node:os";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 async function resolveChrome(need = "open the deck with") {
   const env2 = process.env.HYPERFRAMES_BROWSER_PATH || process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
   if (env2) return { path: env2, source: "env" };
@@ -7001,9 +7137,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(join3(homedir(), ".cache", "hyperframes", "chrome"));
+  const hf = await pick(join4(homedir(), ".cache", "hyperframes", "chrome"));
   if (hf) return { path: hf.executablePath, source: "hyperframes" };
-  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join3(homedir(), ".cache", "puppeteer"));
+  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join4(homedir(), ".cache", "puppeteer"));
   if (pup) return { path: pup.executablePath, source: "puppeteer" };
   throw new Error(
     `no Chrome to ${need} \u2014 run \`npx puppeteer browsers install chrome\`, or set DECKSMITH_CHROME to a Chrome binary.`
@@ -7015,13 +7151,13 @@ async function chromePath(need = "open the deck with") {
 
 // src/source/assets.ts
 import { createHash as createHash4 } from "node:crypto";
-import { mkdir as mkdir2, readdir, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { extname as extname2, join as join4 } 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 join5 } from "node:path";
 import { z as z2 } from "zod";
 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") {
@@ -7046,11 +7182,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(join4(dir, hit)) : await load(figure.src);
+  const bytes = hit ? await readFile4(join5(dir, hit)) : await load(figure.src);
   const size = imageSize(bytes);
   if (hit) return { ...figure, src: hit, ...size };
   const src = `${stem}${assetExt(bytes, figure.src)}`;
-  await writeFile2(join4(dir, src), bytes);
+  await writeFile3(join5(dir, src), bytes);
   cached2.push(src);
   return { ...figure, src, ...size };
 }
@@ -7075,7 +7211,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
@@ -7611,7 +7747,7 @@ function readContentRegion() {
 }
 
 // src/source/transcode.ts
-import { readFile as readFile4, rm } from "node:fs/promises";
+import { readFile as readFile5, rm } from "node:fs/promises";
 import { basename as basename2 } from "node:path";
 
 // src/render/ffmpeg.ts
@@ -7637,7 +7773,7 @@ ${tail}`);
   }
 }
 function runLive(file, args) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const child = spawn(file, args, { stdio: ["ignore", "inherit", "inherit"] });
     child.on("error", (err) => {
       reject(
@@ -7645,7 +7781,7 @@ function runLive(file, args) {
       );
     });
     child.on("close", (code, signal) => {
-      if (code === 0) resolve8();
+      if (code === 0) resolve9();
       else if (signal) {
         reject(
           new Error(
@@ -7772,11 +7908,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)
   };
 }
 
@@ -7842,7 +7983,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 readFile4(input));
+  const source = videoSize(await readFile5(input));
   const box = fitBox(source.width, source.height, opts.maxEdgePx ?? CLIP_EDGE_PX);
   const kept = (why2) => ({
     path: input,
@@ -7874,7 +8015,7 @@ async function transcode(input, out, opts = {}) {
   }
   let measured;
   try {
-    measured = videoSize(await readFile4(out));
+    measured = videoSize(await readFile5(out));
   } catch (err) {
     await rm(out, { force: true });
     return kept(
@@ -7910,8 +8051,8 @@ var HTML_TYPES = /^text\/html$|^application\/xhtml\+xml$/;
 async function harvest(url, dir, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS2;
   const warnings = [];
-  const assets = resolve2(dir);
-  await mkdir3(assets, { recursive: true });
+  const assets = resolve3(dir);
+  await mkdir4(assets, { recursive: true });
   const page = await fetchGuarded(url, {
     maxBytes: opts.maxBytes ?? HTML_MAX_BYTES,
     timeoutMs,
@@ -8293,8 +8434,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
           `it is ${size.width}x${size.height}, under ${MIN_FIGURE_PX}px \u2014 spacers, icons and tracking pixels look like this, and a slide cannot use one`
         );
       }
-      const path2 = join5(dir, assetName(url, extFor2(sniffFormat(bytes))));
-      await writeFile3(path2, bytes);
+      const path2 = join6(dir, assetName(url, extFor2(sniffFormat(bytes))));
+      await writeFile4(path2, bytes);
       assets.push(path2);
       got = { path: path2, width: size.width, height: size.height };
     } catch (err) {
@@ -8306,7 +8447,7 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
   };
   const shrink = async (url, path2, measured, what) => {
     if (opts.transcode === false) return { path: path2, ...measured };
-    const out2 = join5(dir, assetName(url, ".vp9.webm"));
+    const out2 = join6(dir, assetName(url, ".vp9.webm"));
     let small;
     try {
       small = await transcode(path2, out2, {
@@ -8348,8 +8489,8 @@ async function localise(seen, base, dir, opts, timeoutMs, warnings) {
     try {
       const bytes = await bytesOf(url);
       const measured = videoSize(bytes);
-      const path2 = join5(dir, assetName(url, `.${measured.container}`));
-      await writeFile3(path2, bytes);
+      const path2 = join6(dir, assetName(url, `.${measured.container}`));
+      await writeFile4(path2, bytes);
       return await shrink(url, path2, measured, what);
     } catch (err) {
       warnings.push(`${what} was not downloaded: ${url} \u2014 ${why(err)}`);
@@ -8438,7 +8579,7 @@ function unheld(policy) {
   return "the file could not be held";
 }
 async function sizeOf(path2) {
-  return await stat(path2).then(
+  return await stat2(path2).then(
     (s) => s.size,
     () => 0
   );
@@ -8712,9 +8853,9 @@ ${fence}`;
 
 // src/plan/codex.ts
 import { spawn as spawn2 } from "node:child_process";
-import { mkdtemp, readFile as readFile5, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdtemp, readFile as readFile6, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { z as z3 } from "zod";
 
 // src/plan/arc.ts
@@ -9732,11 +9873,11 @@ function schemaFor(prefs) {
 var SCHEMA = schemaFor({ genre: "general" });
 async function codexPlanner(source, opts = {}) {
   const prefs = opts.prefs ?? prefsSchema.parse({});
-  const dir = await mkdtemp(join6(tmpdir2(), "decksmith-plan-"));
+  const dir = await mkdtemp(join7(tmpdir2(), "decksmith-plan-"));
   try {
-    const schemaPath = join6(dir, "storyboard.schema.json");
-    const outPath = join6(dir, "storyboard.json");
-    await writeFile4(schemaPath, JSON.stringify(schemaFor(prefs)));
+    const schemaPath = join7(dir, "storyboard.schema.json");
+    const outPath = join7(dir, "storyboard.json");
+    await writeFile5(schemaPath, JSON.stringify(schemaFor(prefs)));
     await (opts.run ?? runCodex)({
       prompt: buildPrompt(source, prefs),
       schemaPath,
@@ -9744,7 +9885,7 @@ async function codexPlanner(source, opts = {}) {
       ...opts.model === void 0 ? {} : { model: opts.model },
       timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2
     });
-    const raw2 = await readFile5(outPath, "utf8").catch(() => "");
+    const raw2 = await readFile6(outPath, "utf8").catch(() => "");
     if (raw2.trim() === "") {
       throw new Error("Codex produced no final message. Re-run, or try a shorter source.");
     }
@@ -9817,7 +9958,7 @@ function codexCommand(args) {
 }
 function runCodex(args) {
   const { argv, env: env2 } = codexCommand(args);
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const child = spawn2("codex", argv, {
       stdio: ["pipe", "ignore", "pipe"],
       ...env2 === void 0 ? {} : { env: env2 }
@@ -9840,7 +9981,7 @@ function runCodex(args) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (code === 0) return resolve8();
+      if (code === 0) return resolve9();
       reject(
         new Error(`codex exec exited ${code}.
 ${stderr.trim().split("\n").slice(-8).join("\n")}`)
@@ -9852,14 +9993,14 @@ ${stderr.trim().split("\n").slice(-8).join("\n")}`)
 
 // src/images/illustrate.ts
 import { createHash as createHash7 } from "node:crypto";
-import { mkdir as mkdir4, readFile as readFile7, rename, rm as rm5, writeFile as writeFile6 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { mkdir as mkdir5, readFile as readFile8, rename, rm as rm5, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join9 } from "node:path";
 
 // src/images/providers.ts
 import { createHash as createHash6 } from "node:crypto";
-import { mkdtemp as mkdtemp2, readFile as readFile6, rm as rm4, writeFile as writeFile5 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, readFile as readFile7, rm as rm4, writeFile as writeFile6 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join7, resolve as resolve3 } from "node:path";
+import { join as join8, resolve as resolve4 } from "node:path";
 import { z as z4 } from "zod";
 var SIZE = {
   landscape: { width: 1536, height: 1024 },
@@ -9991,11 +10132,11 @@ function codexImages(opts = {}) {
     async check() {
     },
     async generate(req) {
-      const dir = await mkdtemp2(join7(tmpdir3(), "decksmith-image-"));
+      const dir = await mkdtemp2(join8(tmpdir3(), "decksmith-image-"));
       try {
-        const schemaPath = join7(dir, "answer.schema.json");
-        const outPath = join7(dir, "answer.json");
-        await writeFile5(schemaPath, JSON.stringify(ANSWER_SCHEMA));
+        const schemaPath = join8(dir, "answer.schema.json");
+        const outPath = join8(dir, "answer.json");
+        await writeFile6(schemaPath, JSON.stringify(ANSWER_SCHEMA));
         await run5({
           prompt: codexPrompt(req),
           schemaPath,
@@ -10004,7 +10145,7 @@ function codexImages(opts = {}) {
           cwd: dir,
           sandbox: "workspace-write"
         });
-        const raw2 = await readFile6(outPath, "utf8").catch(() => "");
+        const raw2 = await readFile7(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) {
@@ -10012,10 +10153,10 @@ function codexImages(opts = {}) {
             `codex could not generate a picture: ${answer.data.reason ?? "no reason given"}`
           );
         }
-        const candidates2 = [join7(dir, "picture.png")];
-        if (answer.data.file) candidates2.push(resolve3(dir, answer.data.file));
+        const candidates2 = [join8(dir, "picture.png")];
+        if (answer.data.file) candidates2.push(resolve4(dir, answer.data.file));
         for (const path2 of candidates2) {
-          const bytes = await readFile6(path2).catch(() => null);
+          const bytes = await readFile7(path2).catch(() => null);
           if (bytes) return raster(bytes, "codex");
         }
         throw new Error("codex said ok but wrote no picture.png");
@@ -10147,7 +10288,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 mkdir4(opts.assetsDir, { recursive: true });
+  if (pending.length > 0) await mkdir5(opts.assetsDir, { recursive: true });
   for (const [i, slot] of pending.entries()) {
     let rungs = chain;
     if (i >= images.max) {
@@ -10244,16 +10385,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 readFile7(join8(dir, src2)).catch(() => null);
+    const bytes = await readFile8(join9(dir, src2)).catch(() => null);
     if (bytes) return { src: src2, ...sizeOf2(bytes, ext), cached: true };
   }
   await provider.check();
   const img = await provider.generate(req);
   const src = `${name}${EXT2[img.mime]}`;
-  const tmp = join8(dir, `.${name}.tmp`);
+  const tmp = join9(dir, `.${name}.tmp`);
   try {
-    await writeFile6(tmp, img.bytes);
-    await rename(tmp, join8(dir, src));
+    await writeFile7(tmp, img.bytes);
+    await rename(tmp, join9(dir, src));
   } finally {
     await rm5(tmp, { force: true });
   }
@@ -10266,9 +10407,9 @@ function sizeOf2(bytes, ext) {
 // src/narrate/tts.ts
 import { spawn as spawn3 } from "node:child_process";
 import { createHash as createHash8 } from "node:crypto";
-import { mkdir as mkdir5, readFile as readFile8, rm as rm6, writeFile as writeFile7 } from "node:fs/promises";
+import { mkdir as mkdir6, readFile as readFile9, rm as rm6, writeFile as writeFile8 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 var MISSING = [
   "edge-tts is not installed, so narration cannot be synthesised.",
   "",
@@ -10285,8 +10426,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.
-    [join9(home, "Library", "Python", "3.9", "bin", "edge-tts")],
-    [join9(home, ".local", "bin", "edge-tts")],
+    [join10(home, "Library", "Python", "3.9", "bin", "edge-tts")],
+    [join10(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"]
@@ -10311,7 +10452,7 @@ async function find2(can) {
   throw new Error(MISSING);
 }
 function runArgv(cmd, args) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const child = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
@@ -10321,8 +10462,8 @@ function runArgv(cmd, args) {
     child.stderr.on("data", (b) => {
       stderr += b.toString();
     });
-    child.on("error", (e) => resolve8({ code: -1, stderr: String(e), stdout }));
-    child.on("close", (code) => resolve8({ code: code ?? -1, stderr, stdout }));
+    child.on("error", (e) => resolve9({ code: -1, stderr: String(e), stdout }));
+    child.on("close", (code) => resolve9({ code: code ?? -1, stderr, stdout }));
   });
 }
 var edgeTts = {
@@ -10389,7 +10530,7 @@ function edgeProvider(runner = edgeTts) {
     async speak(req) {
       const subs = `${req.audio.replace(/\.mp3$/, "")}.srt`;
       await runner.speak({ ...req, subs });
-      const raw2 = await readFile8(subs, "utf8").catch(() => "");
+      const raw2 = await readFile9(subs, "utf8").catch(() => "");
       await rm6(subs, { force: true });
       const cues = parseCues(raw2);
       const measured = await runner.measure(req.audio);
@@ -10407,11 +10548,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 = join9(opts.dir, file);
-  const sidecar = join9(opts.dir, `${key}.json`);
+  const audio = join10(opts.dir, file);
+  const sidecar = join10(opts.dir, `${key}.json`);
   const cached2 = await readSidecar(sidecar);
   if (cached2) return { audio, file, seconds: cached2.seconds, cues: cached2.cues };
-  await mkdir5(opts.dir, { recursive: true });
+  await mkdir6(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) => ({
@@ -10420,13 +10561,13 @@ async function synthesize(text2, opts) {
     text: c.text
   }));
   const body = { seconds, cues: clamped, text: text2, voice: opts.voice };
-  await writeFile7(sidecar, `${JSON.stringify(body, null, 2)}
+  await writeFile8(sidecar, `${JSON.stringify(body, null, 2)}
 `);
   return { audio, file, seconds, cues: clamped };
 }
 async function readSidecar(path2) {
   try {
-    const parsed = JSON.parse(await readFile8(path2, "utf8"));
+    const parsed = JSON.parse(await readFile9(path2, "utf8"));
     const s = parsed;
     return typeof s?.seconds === "number" && s.seconds > 0 && Array.isArray(s.cues) ? s : null;
   } catch {
@@ -10573,12 +10714,12 @@ function scanBeatCount(storyboard, prefs) {
 }
 
 // src/render/render.ts
-import { mkdir as mkdir7, readFile as readFile9, rename as rename2, rm as rm7, writeFile as writeFile9 } from "node:fs/promises";
-import { basename as basename4, dirname as dirname2, join as join11, resolve as resolve4 } from "node:path";
+import { mkdir as mkdir8, readFile as readFile10, rename as rename2, rm as rm7, writeFile as writeFile10 } from "node:fs/promises";
+import { basename as basename4, dirname as dirname3, join as join12, resolve as resolve5 } from "node:path";
 
 // src/render/captions.ts
-import { mkdir as mkdir6, writeFile as writeFile8 } from "node:fs/promises";
-import { join as join10 } from "node:path";
+import { mkdir as mkdir7, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join11 } from "node:path";
 import { pathToFileURL } from "node:url";
 var DECK_FONT_CSS = "assets/fonts/fonts.css";
 function cssString(value) {
@@ -10669,11 +10810,11 @@ async function captionBlocker() {
 }
 async function renderCaptions(cues, style, deck, work2) {
   if (cues.length === 0) throw new Error("renderCaptions was given no cues.");
-  const fontCss = join10(deck, DECK_FONT_CSS);
+  const fontCss = join11(deck, DECK_FONT_CSS);
   const href = await import("node:fs/promises").then((fs) => fs.stat(fontCss).catch(() => null)) ? pathToFileURL(fontCss).href : null;
-  const page = join10(work2, "captions.html");
-  await mkdir6(work2, { recursive: true });
-  await writeFile8(page, captionPage(cues, style, href));
+  const page = join11(work2, "captions.html");
+  await mkdir7(work2, { recursive: true });
+  await writeFile9(page, captionPage(cues, style, href));
   const { default: puppeteer } = await import("puppeteer-core");
   const browser = await puppeteer.launch({
     executablePath: await chromePath(CAPTION_NEED),
@@ -10693,7 +10834,7 @@ async function renderCaptions(cues, style, deck, work2) {
       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: join10(work2, name),
+        path: join11(work2, name),
         type: "png",
         omitBackground: true,
         clip: { x: box.x, y: box.y, width: box.width, height: box.height }
@@ -10734,9 +10875,9 @@ function subtitlePlan(mode) {
 async function render(opts) {
   const log = opts.log ?? (() => {
   });
-  const deck = resolve4(opts.deck);
-  const out = resolve4(opts.out);
-  const work2 = join11(dirname2(out), `.${basename4(out)}.parts`);
+  const deck = resolve5(opts.deck);
+  const out = resolve5(opts.out);
+  const work2 = join12(dirname3(out), `.${basename4(out)}.parts`);
   const timing = await readTiming(deck);
   if (opts.targetSeconds && !opts.allowFastPlayback) {
     const refusal = playbackRefusal(
@@ -10748,13 +10889,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 mkdir7(work2, { recursive: true });
+  await mkdir8(work2, { recursive: true });
   try {
-    const raw2 = opts.video ? resolve4(opts.video) : await capture(deck, join11(work2, "raw.mp4"), opts, log);
+    const raw2 = opts.video ? resolve5(opts.video) : await capture(deck, join12(work2, "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`
@@ -10767,18 +10912,18 @@ async function render(opts) {
       );
     }
     const retimed = await retime(raw2, plan, work2, log);
-    const srtPath = join11(dirname2(out), SRT_NAME(out));
+    const srtPath = join12(dirname3(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 writeFile9(srtPath, srt);
+    if (srt) await writeFile10(srtPath, srt);
     const burn = burnable && srt.length > 0;
     await mux(retimed, timing, plan, deck, out, work2, 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 = join11(work2, `fast.${basename4(out)}`);
+      const fast = join12(work2, `fast.${basename4(out)}`);
       const muxed = await probe(out);
       await runTool(
         "ffmpeg",
@@ -10808,8 +10953,8 @@ async function render(opts) {
   }
 }
 async function readTiming(deck) {
-  const path2 = join11(deck, TIMING_FILE);
-  const text2 = await readFile9(path2, "utf8").catch(() => {
+  const path2 = join12(deck, TIMING_FILE);
+  const text2 = await readFile10(path2, "utf8").catch(() => {
     throw new Error(
       `${path2} is missing. \`render\` needs the timing manifest \`build\` writes; rebuild the deck.`
     );
@@ -10848,20 +10993,20 @@ async function retime(raw2, plan, work2, log) {
   if (plan.pieces.every((p) => p.freeze === 0)) return raw2;
   const list = [];
   for (const [i, piece] of plan.pieces.entries()) {
-    const file = join11(work2, `p${String(i).padStart(4, "0")}.ts`);
+    const file = join12(work2, `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 = join11(work2, "pieces.txt");
-  await writeFile9(
+  const listFile = join12(work2, "pieces.txt");
+  await writeFile10(
     listFile,
     `${list.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n")}
 `
   );
-  const joined = join11(work2, "retimed.mp4");
+  const joined = join12(work2, "retimed.mp4");
   await runTool("ffmpeg", [
     "-y",
     "-hide_banner",
@@ -10883,7 +11028,7 @@ async function retime(raw2, plan, work2, log) {
 }
 async function mux(video, timing, plan, deck, out, work2, burnCues, fps, log) {
   const inputs = plan.audio.map((a) => ({
-    file: join11(deck, timing.audioDir, a.audio),
+    file: join12(deck, timing.audioDir, a.audio),
     delayMs: a.delayMs
   }));
   const args = ["-y", "-hide_banner", "-loglevel", "error", "-i", video];
@@ -10904,8 +11049,8 @@ async function mux(video, timing, plan, deck, out, work2, burnCues, fps, log) {
     graph.push(audioGraph(inputs, plan.frames / fps, 1 + (band?.files.length ?? 0)));
   }
   if (graph.length > 0) {
-    const script = join11(work2, "mux.filter");
-    await writeFile9(script, `${graph.join(";\n")}
+    const script = join12(work2, "mux.filter");
+    await writeFile10(script, `${graph.join(";\n")}
 `);
     args.push("-filter_complex_script", script);
   }
@@ -10920,13 +11065,13 @@ async function mux(video, timing, plan, deck, out, work2, burnCues, fps, log) {
   log(
     `render: muxing ${inputs.length} segment(s)${burnCues ? " and burning in the captions" : ""} \u2192 ${out}`
   );
-  await mkdir7(dirname2(out), { recursive: true });
+  await mkdir8(dirname3(out), { recursive: true });
   await runTool("ffmpeg", args, { cwd: work2 });
 }
 
 // src/pack/pack.ts
-import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile10 } from "node:fs/promises";
-import { dirname as dirname3, extname as extname3 } from "node:path";
+import { mkdir as mkdir9, readFile as readFile11, writeFile as writeFile11 } from "node:fs/promises";
+import { dirname as dirname4, extname as extname3 } from "node:path";
 import { unzipSync, zipSync } from "fflate";
 var MTIME = Date.UTC(1980, 0, 2, 12);
 var STORED = /* @__PURE__ */ new Set([
@@ -10965,8 +11110,8 @@ async function writePack(pack3, files, out) {
     entries[path2] = STORED.has(extname3(path2).toLowerCase()) ? [bytes, { level: 0 }] : bytes;
   }
   const zip = zipSync(entries, { mtime: MTIME });
-  await mkdir8(dirname3(out), { recursive: true });
-  await writeFile10(out, zip);
+  await mkdir9(dirname4(out), { recursive: true });
+  await writeFile11(out, zip);
   return zip.length;
 }
 function check2(label, path2 = label) {
@@ -10985,8 +11130,8 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   if (!format) throw new Error("no deck-16x9 format");
   const step = opts.onStep ?? (() => {
   });
-  const out = resolve5(outDir);
-  await mkdir9(out, { recursive: true });
+  const out = resolve6(outDir);
+  await mkdir10(out, { recursive: true });
   const speed = opts.speed ?? 1;
   const fontCss = await refreshFont(storyboard, source, out, step);
   const deck = emitDeck(storyboard, source, format, await deckRuntime(), {
@@ -10999,47 +11144,48 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   });
   const files = [];
   const write = async (name, text2) => {
-    await writeFile11(join12(out, name), text2);
-    files.push(join12(out, name));
+    await writeFile12(join13(out, name), text2);
+    files.push(join13(out, name));
   };
   await write("index.html", deck.composition);
   await write("hyperframes.json", HYPERFRAMES_JSON);
-  if (opts.narration) {
-    try {
-      const timing = planTiming({
-        storyboard,
-        source,
-        format,
-        composition: deck.composition,
-        // What was drawn, not what the threshold would have kept: a budgeted
-        // format cuts to its own length as well, and the two lists differ.
-        beats: deck.cut.kept,
-        narration: opts.narration,
-        speed,
-        ...opts.theme ? { theme: opts.theme } : {}
-      });
-      await write(TIMING_FILE, `${JSON.stringify(timing, null, 2)}
+  try {
+    const timing = planTiming({
+      storyboard,
+      source,
+      format,
+      composition: deck.composition,
+      // What was drawn, not what the threshold would have kept: a budgeted
+      // format cuts to its own length as well, and the two lists differ.
+      beats: deck.cut.kept,
+      speed,
+      ...opts.narration ? { narration: opts.narration } : {},
+      ...opts.theme ? { theme: opts.theme } : {}
+    });
+    await write(TIMING_FILE, `${JSON.stringify(timing, null, 2)}
 `);
-      step(`build: timing for ${timing.segments.length} narration segment(s)`);
-    } catch (err) {
-      step(
-        `build: cannot place narration on this deck, so no ${TIMING_FILE} was written and \`render\` will refuse. ${err instanceof Error ? err.message : err}`
-      );
-    }
+    step(`build: timing for ${timing.segments.length} narration segment(s)`);
+  } catch (err) {
+    step(
+      `build: cannot place narration on this deck, so no ${TIMING_FILE} was written and \`render\` will refuse. ${err instanceof Error ? err.message : err}`
+    );
   }
   if (deck.page) {
     await write(DECK_PAGE, deck.page);
-    await cp(playerBundle(), join12(out, PLAYER_FILE));
-    files.push(join12(out, PLAYER_FILE));
+    await cp2(playerBundle(), join13(out, PLAYER_FILE));
+    files.push(join13(out, PLAYER_FILE));
   }
   files.push(...await vendorKatex(out));
-  if (opts.assetsFrom) files.push(...await copyAssets(opts.assetsFrom, out));
+  files.push(...await vendorScripts(out, deck.composition));
+  if (opts.assetsFrom) {
+    files.push(...await copyAssets(opts.assetsFrom, out, source.figures, step));
+  }
   if (opts.narration && opts.audioFrom) {
-    files.push(...await copyAudio(opts.audioFrom, opts.narration, out));
+    files.push(...await copyAudio(opts.audioFrom, opts.narration, out, step));
   }
   const of = deck.cut.kept.length === storyboard.beats.length ? "" : ` of ${storyboard.beats.length}`;
   step(
-    `build: ${deck.cut.kept.length}${of} beats at ${format.width}\xD7${format.height} \u2192 ${join12(out, "index.html")}`
+    `build: ${deck.cut.kept.length}${of} beats at ${format.width}\xD7${format.height} \u2192 ${join13(out, "index.html")}`
   );
   for (const d of deck.cut.dropped) step(`build:   cut ${d.beat.id} \u2014 ${d.reason}`);
   for (const d of deck.cut.dangling) step(`build:   check the wording \u2014 ${d.reason}`);
@@ -11055,77 +11201,21 @@ var HYPERFRAMES_JSON = `${JSON.stringify(
 )}
 `;
 async function deckRuntime() {
-  const path2 = fileURLToPath(new URL(`./${"deck-runtime.js"}`, import.meta.url));
+  const path2 = fileURLToPath2(new URL(`./${"deck-runtime.js"}`, import.meta.url));
   try {
-    return await readFile11(path2, "utf8");
+    return await readFile12(path2, "utf8");
   } catch {
     throw new Error(`Deck runtime missing at ${path2}. Run "npm run build" first.`);
   }
 }
 function playerBundle() {
-  const require2 = createRequire3(import.meta.url);
+  const require2 = createRequire4(import.meta.url);
   try {
-    return join12(dirname4(require2.resolve("hyperframes/package.json")), "dist", PLAYER_FILE);
+    return join13(dirname5(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 = createRequire3(import.meta.url);
-  const dist = join12(dirname4(require2.resolve("katex/package.json")), "dist");
-  const css = await readFile11(join12(dist, "katex.min.css"), "utf8");
-  const written = [];
-  await mkdir9(join12(out, "katex/fonts"), { recursive: true });
-  for (const file of await readdir2(join12(dist, "fonts"))) {
-    if (!file.endsWith(".woff2")) continue;
-    await cp(join12(dist, "fonts", file), join12(out, "katex/fonts", file));
-    written.push(join12(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 writeFile11(join12(out, "katex/katex.min.css"), woff2Only);
-  written.push(join12(out, "katex/katex.min.css"));
-  return written;
-}
-async function copyAssets(sourceDir, out) {
-  const from = join12(resolve5(sourceDir), "assets");
-  if (!await stat2(from).catch(() => null)) return [];
-  await cp(from, join12(out, "assets"), { recursive: true });
-  return [join12(out, "assets")];
-}
-async function copyAudio(from, narration, out) {
-  const dir = join12(out, narration.dir);
-  await mkdir9(dir, { recursive: true });
-  const names = [
-    ...new Set(
-      Object.values(narration.beats).flat().map((s) => s.audio)
-    )
-  ].sort();
-  for (const name of names) {
-    await cp(join12(resolve5(from), name), join12(dir, name)).catch(() => {
-      throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
-    });
-  }
-  return names.map((n3) => join12(dir, n3));
-}
-async function refreshFont(storyboard, source, out, step) {
-  try {
-    const bundle = await bundleFont(
-      storyboard.lang,
-      JSON.stringify(source) + JSON.stringify(storyboard),
-      join12(out, "assets", "fonts")
-    );
-    if (bundle) step(`build: font bundle covers ${bundle.family}`);
-    return bundle?.css;
-  } catch (err) {
-    step(
-      `build: could not refresh the font bundle (${err instanceof Error ? err.message : err}); keeping the one from ingest`
-    );
-    return void 0;
-  }
-}
 
 // src/server/upload.ts
 import { posix, sep as sep2 } from "node:path";
@@ -11470,8 +11560,8 @@ function int(name, raw2) {
 }
 
 // src/server/pipeline.ts
-import { mkdir as mkdir10, readFile as readFile12, stat as stat3, writeFile as writeFile12 } from "node:fs/promises";
-import { dirname as dirname5, isAbsolute, join as join13, relative, resolve as resolve6 } from "node:path";
+import { mkdir as mkdir11, readFile as readFile13, stat as stat3, writeFile as writeFile13 } from "node:fs/promises";
+import { dirname as dirname6, isAbsolute, join as join14, relative, resolve as resolve7 } from "node:path";
 var AUDIO_DIR = "audio";
 var NARRATION_FILE = "narration.json";
 var MAX_REMOTE_FIGURES = 40;
@@ -11494,10 +11584,10 @@ function stagesFor(options) {
 async function runPipeline(job, input) {
   const { options } = input;
   const dirs = {
-    upload: join13(job.dir, "upload"),
-    src: join13(job.dir, "src"),
-    audio: join13(job.dir, AUDIO_DIR),
-    deck: join13(job.dir, "deck")
+    upload: join14(job.dir, "upload"),
+    src: join14(job.dir, "src"),
+    audio: join14(job.dir, AUDIO_DIR),
+    deck: join14(job.dir, "deck")
   };
   const warnings = [...options.warnings];
   const url = (rel) => `/d/${job.id}/${rel}`;
@@ -11521,21 +11611,21 @@ async function runPipeline(job, input) {
     theme: options.stated.theme ? prefs.theme : planned.theme
   };
   assertRefsResolve(storyboard, source, { pending: options.images ? "allow" : "refuse" });
-  await writeJson(join13(job.dir, "storyboard.json"), storyboard);
+  await writeJson(join14(job.dir, "storyboard.json"), storyboard);
   job.done("plan", `${storyboard.beats.length} beats`);
   for (const f of scanBeatCount(storyboard, prefs)) warnings.push(f.message);
   if (options.images) {
     job.begin("illustrate");
     const drawn = await illustrate(storyboard, source, {
       prefs,
-      assetsDir: join13(dirs.src, "assets"),
+      assetsDir: join14(dirs.src, "assets"),
       ...input.imageChain ? { chain: input.imageChain } : {},
       onStep: (line2) => job.log(line2)
     });
     storyboard = drawn.storyboard;
     source = drawn.source;
-    await writeJson(join13(dirs.src, "source.json"), source);
-    await writeJson(join13(job.dir, "storyboard.json"), storyboard);
+    await writeJson(join14(dirs.src, "source.json"), source);
+    await writeJson(join14(job.dir, "storyboard.json"), storyboard);
     for (const p of drawn.illustrated) {
       job.log(
         `illustrate: ${p.beatId} \u2192 assets/${p.src} via ${p.provider}${p.cached ? " (cached)" : ""}`
@@ -11557,12 +11647,12 @@ async function runPipeline(job, input) {
       warnings.push("the plan had nothing to say aloud, so the deck is silent");
     } else {
       job.log(`narrate: ${speaking} of ${storyboard.beats.length} beats speak`);
-      await mkdir10(dirs.audio, { recursive: true });
+      await mkdir11(dirs.audio, { recursive: true });
       const spoken = await narrate(storyboard, source, prefs, {
         dir: dirs.audio,
         format: options.format
       });
-      await writeJson(join13(dirs.audio, NARRATION_FILE), spoken);
+      await writeJson(join14(dirs.audio, NARRATION_FILE), spoken);
       narration = { voice: spoken.voice, dir: AUDIO_DIR, beats: spoken.beats };
       const segments2 = Object.values(spoken.beats).flat();
       const seconds = segments2.reduce((sum, s) => sum + s.seconds, 0);
@@ -11616,7 +11706,7 @@ async function runPipeline(job, input) {
       job.log("render: capturing frames \u2014 two minutes for a four-minute video");
       const out = await render({
         deck: dirs.deck,
-        out: join13(dirs.deck, "video.mp4"),
+        out: join14(dirs.deck, "video.mp4"),
         subtitles: "sidecar",
         log: (line2) => job.log(line2),
         // The last of the three length levers, and the only one that acts on a
@@ -11665,8 +11755,8 @@ async function runPipeline(job, input) {
   };
 }
 async function ingest(job, input, dirs, warnings) {
-  await mkdir10(dirs.upload, { recursive: true });
-  const root2 = resolve6(dirs.upload);
+  await mkdir11(dirs.upload, { recursive: true });
+  const root2 = resolve7(dirs.upload);
   let docPath;
   const upload = input.upload;
   const bothOrNeither = new UploadError(
@@ -11676,13 +11766,13 @@ async function ingest(job, input, dirs, warnings) {
   );
   if (input.url !== void 0) {
     if (upload !== void 0) throw bothOrNeither;
-    const harvested = await harvestBounded(input.url, join13(root2, "assets"), {
+    const harvested = await harvestBounded(input.url, join14(root2, "assets"), {
       ...HARVEST_LIMITS,
       ...input.harvest
     });
     warnings.push(...harvested.warnings);
-    docPath = join13(root2, "document.md");
-    await writeFile12(docPath, harvested.markdown);
+    docPath = join14(root2, "document.md");
+    await writeFile13(docPath, harvested.markdown);
     job.log(
       `ingest: harvested ${input.url} \u2014 "${harvested.title}", ${harvested.assets.length} asset(s)`
     );
@@ -11698,13 +11788,13 @@ async function ingest(job, input, dirs, warnings) {
     const { files, warnings: zipWarnings } = readZip(upload.bytes);
     warnings.push(...zipWarnings);
     for (const [rel, bytes] of Object.entries(files)) {
-      const to = resolve6(join13(root2, rel));
+      const to = resolve7(join14(root2, rel));
       if (!insideRoot2(root2, to))
         throw new UploadError(`Refusing to write ${rel}.`, "Re-zip from inside the folder.");
-      await mkdir10(dirname5(to), { recursive: true });
-      await writeFile12(to, bytes);
+      await mkdir11(dirname6(to), { recursive: true });
+      await writeFile13(to, bytes);
     }
-    docPath = join13(root2, pickMarkdown(files));
+    docPath = join14(root2, pickMarkdown(files));
     job.log(
       `ingest: unpacked ${Object.keys(files).length} file(s), reading ${pickMarkdown(files)}`
     );
@@ -11716,10 +11806,10 @@ async function ingest(job, input, dirs, warnings) {
         `DeckSmith reads ${MARKDOWN_EXTS.join(", ")} or a .zip containing one. Export the document to markdown first.`
       );
     }
-    docPath = join13(root2, "document.md");
-    await writeFile12(docPath, upload.bytes);
+    docPath = join14(root2, "document.md");
+    await writeFile13(docPath, upload.bytes);
   }
-  const text2 = await readFile12(docPath, "utf8");
+  const text2 = await readFile13(docPath, "utf8");
   const parsed = parseMarkdown(text2, {
     lang: input.options.stated.lang ? input.options.prefs.lang : void 0
   });
@@ -11739,8 +11829,8 @@ async function ingest(job, input, dirs, warnings) {
     `ingest: ${parsed.sections.length} sections, ${parsed.figures.length} figures, ${parsed.equations.length} equations, ${parsed.tables.length} tables`
   );
   const guarded = await guardFigures(parsed, root2, input.fetchRemoteFigures, warnings);
-  const source = await fetchFigures(guarded, join13(resolve6(dirs.src), "assets"), warnings);
-  await writeJson(join13(dirs.src, "source.json"), source);
+  const source = await fetchFigures(guarded, join14(resolve7(dirs.src), "assets"), warnings);
+  await writeJson(join14(dirs.src, "source.json"), source);
   return source;
 }
 async function harvestBounded(url, dir, opts) {
@@ -11816,7 +11906,7 @@ async function guardFigures(source, root2, allowRemote, warnings) {
       warnings.push(`figure ${figure.id} was left out: "${scheme}:" figures are not read`);
       continue;
     }
-    const abs = isAbsolute(src) ? resolve6(src) : resolve6(join13(root2, src.replace(/^\.?\//, "")));
+    const abs = isAbsolute(src) ? resolve7(src) : resolve7(join14(root2, src.replace(/^\.?\//, "")));
     if (!insideRoot2(root2, abs)) {
       warnings.push(`figure ${figure.id} was left out: "${src}" points outside the upload`);
       continue;
@@ -11831,19 +11921,19 @@ async function guardFigures(source, root2, allowRemote, warnings) {
 }
 async function pack2(job, ctx) {
   try {
-    const assets = join13(resolve6(ctx.dirs.src), "assets");
+    const assets = join14(resolve7(ctx.dirs.src), "assets");
     const requests = ctx.source.figures.map((f) => ({
       id: f.id,
-      url: join13(assets, f.src),
+      url: join14(assets, f.src),
       prefer: "bake"
     }));
     const plan = await planMedia(requests, async (url) => ({
-      bytes: new Uint8Array(await readFile12(url))
+      bytes: new Uint8Array(await readFile13(url))
     }));
     const files = { ...plan.files };
     if (ctx.narration) {
-      for (const name of audioNames(ctx.narration)) {
-        files[`${AUDIO_DIR}/${name}`] = new Uint8Array(await readFile12(join13(ctx.dirs.audio, name)));
+      for (const name of audioNames2(ctx.narration)) {
+        files[`${AUDIO_DIR}/${name}`] = new Uint8Array(await readFile13(join14(ctx.dirs.audio, name)));
       }
     }
     const container = {
@@ -11860,10 +11950,10 @@ async function pack2(job, ctx) {
       },
       source: ctx.source,
       storyboard: ctx.storyboard,
-      ...ctx.narration ? { narration: await readJson(join13(ctx.dirs.audio, NARRATION_FILE)) } : {},
+      ...ctx.narration ? { narration: await readJson(join14(ctx.dirs.audio, NARRATION_FILE)) } : {},
       media: plan.media
     };
-    const bytes = await writePack(container, files, join13(ctx.dirs.deck, "deck.deck"));
+    const bytes = await writePack(container, files, join14(ctx.dirs.deck, "deck.deck"));
     job.log(`pack: ${Math.round(bytes / 1024)} KB \u2192 deck.deck`);
     return ctx.url("deck.deck");
   } catch (err) {
@@ -11871,7 +11961,7 @@ async function pack2(job, ctx) {
     return void 0;
   }
 }
-function audioNames(narration) {
+function audioNames2(narration) {
   return [
     ...new Set(
       Object.values(narration.beats).flat().map((s) => s.audio)
@@ -11886,12 +11976,12 @@ function host(src) {
   }
 }
 async function writeJson(path2, value) {
-  await mkdir10(dirname5(path2), { recursive: true });
-  await writeFile12(path2, `${JSON.stringify(value, null, 2)}
+  await mkdir11(dirname6(path2), { recursive: true });
+  await writeFile13(path2, `${JSON.stringify(value, null, 2)}
 `);
 }
 async function readJson(path2) {
-  return JSON.parse(await readFile12(path2, "utf8"));
+  return JSON.parse(await readFile13(path2, "utf8"));
 }
 
 // src/server/errors.ts
@@ -12297,14 +12387,14 @@ var PAGE_BUDGET = {
   refs: "relative"
 };
 async function readPage(url, work2) {
-  await mkdir11(work2, { recursive: true });
-  const dir = await mkdtemp3(join14(work2, "harvest-"));
+  await mkdir12(work2, { recursive: true });
+  const dir = await mkdtemp3(join15(work2, "harvest-"));
   try {
     const page = await harvest(url, dir, PAGE_BUDGET);
     const files = {
       "document.md": new TextEncoder().encode(page.markdown)
     };
-    for (const asset of page.assets) files[basename5(asset)] = await readFile13(asset);
+    for (const asset of page.assets) files[basename5(asset)] = await readFile14(asset);
     const warnings = [...page.warnings];
     if (page.clips.length > 0) {
       warnings.push(
@@ -12338,7 +12428,7 @@ var statusSchema = z5.object({
 var DEFAULT_WAIT = 45;
 function deckTools(opts) {
   const queue = new Queue({ maxQueued: 8 });
-  const root2 = resolve7(opts.root);
+  const root2 = resolve8(opts.root);
   let cached2;
   const found = async () => {
     cached2 ??= await (opts.probe ?? prereqs)();
@@ -12346,7 +12436,7 @@ function deckTools(opts) {
   };
   const insideRoot3 = (p) => {
     if (!isAbsolute2(p)) throw new Error(`document_path must be absolute; got "${p}".`);
-    const full = resolve7(p);
+    const full = resolve8(p);
     if (full !== root2 && !full.startsWith(root2 + sep3)) {
       throw new Error(
         `document_path is outside the server's root. It may only read files under ${root2}.`
@@ -12425,15 +12515,15 @@ function deckTools(opts) {
       }
       const page = input.document_url === void 0 ? void 0 : await readPage(input.document_url, opts.work);
       const filename = page ? "page.zip" : input.document_path ? input.document_path.split(sep3).pop() : "document.md";
-      const bytes = page ? page.zip : file ? await readFile13(file) : new TextEncoder().encode(input.document_text);
+      const bytes = page ? page.zip : file ? await readFile14(file) : new TextEncoder().encode(input.document_text);
       if (bytes.byteLength > MAX_UPLOAD_BYTES) {
         throw new Error(
           `Document is ${(bytes.byteLength / 1e6).toFixed(1)} MB, over the ${(MAX_UPLOAD_BYTES / 1e6).toFixed(0)} MB cap.` + (page ? " Harvest fewer figures with a smaller maxAssets, or save the page and edit it." : "")
         );
       }
       const id2 = randomBytes(16).toString("base64url");
-      const dir = join14(opts.work, id2);
-      await mkdir11(dir, { recursive: true });
+      const dir = join15(opts.work, id2);
+      await mkdir12(dir, { recursive: true });
       queue.submit({
         id: id2,
         dir,
@@ -12460,7 +12550,7 @@ function deckTools(opts) {
   };
 }
 function dirOf(work2, id2) {
-  return join14(work2, id2);
+  return join15(work2, id2);
 }
 function waitFor(queue, id2, seconds) {
   const now = queue.view(id2);
@@ -12492,9 +12582,9 @@ function report(view, dir) {
     // (src/server/pipeline.ts). This said `src/storyboard.json` for one run, which
     // is the shape of the CLI's output directory and not the server's, and an
     // agent told to read it would have found nothing there.
-    storyboard_path: join14(dir, "storyboard.json"),
+    storyboard_path: join15(dir, "storyboard.json"),
     ...done && view.result ? {
-      deck_path: join14(dir, "deck"),
+      deck_path: join15(dir, "deck"),
       slides: view.result.slides,
       duration_seconds: view.result.duration,
       warnings: view.result.warnings
@@ -12503,7 +12593,7 @@ function report(view, dir) {
   };
 }
 function defaultWork() {
-  return join14(tmpdir4(), "decksmith-mcp");
+  return join15(tmpdir4(), "decksmith-mcp");
 }
 
 // src/mcp/main.ts