@jokerized/decksmith 0.3.2 → 0.4.1

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { cp, mkdir as mkdir10, readdir as readdir4, readFile as readFile17, stat as stat2, writeFile as writeFile12 } from "node:fs/promises";
-import { createRequire as createRequire3 } from "node:module";
-import { dirname as dirname4, join as join16, resolve as resolve5 } from "node:path";
+import { createRequire as createRequire4 } from "node:module";
+import { dirname as dirname5, join as join17, resolve as resolve6 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/pack/media.ts
@@ -414,15 +414,53 @@ var dataTableParamsSchema = z.object({
   path: ["highlight"],
   message: "every highlight must name a row that params.rows draws"
 });
+var chartPointSchema = z.object({ x: z.string(), y: z.number() });
 var lineChartParamsSchema = z.object({
   eyebrow: z.string().optional(),
   headline: z.string(),
   xLabel: z.string(),
   yLabel: z.string(),
-  points: z.array(z.object({ x: z.string(), y: z.number() })).min(2),
+  points: z.array(chartPointSchema).min(2),
   /** Inter-point annotations, e.g. per-step deltas. One fewer than `points`. */
   deltas: z.array(z.string()).optional(),
-  readout: z.string().optional()
+  readout: z.string().optional(),
+  /**
+   * THE SAME MEASUREMENT UNDER A SECOND CONDITION — a baseline the main series
+   * is to be read against, where the point is the change in the SHAPE of the
+   * curve rather than two numbers.
+   *
+   * Drawn first and alone; then the curve lifts off it and reshapes into
+   * `points`, leaving this one behind as a ghost. `label` names the ghost and
+   * is drawn wherever the chart has room for it.
+   *
+   * KEEP IT SHORT — two or three words. A label wider than the plot is refused
+   * outright, and that refusal reaches `onBeatError` and costs the whole beat.
+   * One that fits but cannot be placed clear of the axis names, the tick and
+   * category labels, the values, the deltas and both curves is DROPPED
+   * instead, silently: an unnamed ghost is still legibly the fainter, earlier
+   * curve, where a name printed through a number is a defect in both of them.
+   * Nothing warns about that one — see the placement note in
+   * `src/emit/archetypes/line-chart.ts`.
+   */
+  compare: z.object({ label: z.string(), points: z.array(chartPointSchema).min(2) }).optional()
+}).superRefine((p, ctx) => {
+  if (!p.compare) return;
+  if (p.compare.points.length !== p.points.length) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["compare", "points"],
+      message: `compare has ${p.compare.points.length} points against ${p.points.length}; a comparison is over the same x values`
+    });
+    return;
+  }
+  const off = p.compare.points.findIndex((c, i) => c.x !== p.points[i]?.x);
+  if (off >= 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["compare", "points", off, "x"],
+      message: `compare point ${off} is "${p.compare.points[off]?.x}" where points has "${p.points[off]?.x}"`
+    });
+  }
 });
 var calloutParamsSchema = z.object({
   eyebrow: z.string().optional(),
@@ -1205,8 +1243,8 @@ async function bundleFont(lang, glyphs, dir) {
 ${text2}`).digest("hex").slice(0, 16)} */`;
   await mkdir(dir, { recursive: true });
   const cssPath = join(dir, "fonts.css");
-  const cached = await readFile2(cssPath, "utf8").catch(() => "");
-  if (cached.startsWith(stamp)) return { family, css: cached, files: localNames(cached) };
+  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 } }
@@ -1419,6 +1457,21 @@ function nv(v) {
 }
 var DRAW_FROM = { drawSVG: "0%" };
 var DRAW_TO = { drawSVG: "100%" };
+var SHAPE_INDEX = 0;
+function reshape(target, to, at, seconds, first) {
+  if (!(seconds > 0)) throw new Error(`reshape ${target}: ${seconds}s is no time to reshape in`);
+  return fromTo(
+    target,
+    { morphSVG: { shape: target, shapeIndex: SHAPE_INDEX } },
+    {
+      morphSVG: { shape: to, shapeIndex: SHAPE_INDEX },
+      duration: sec(seconds),
+      ease: "power2.inOut",
+      ...first ? {} : { immediateRender: false }
+    },
+    sec(at)
+  );
+}
 function travel(target, route, at, seconds) {
   if (!(seconds > 0)) throw new Error(`travel ${target}: ${seconds}s is no time to travel in`);
   const legs = [];
@@ -4100,6 +4153,12 @@ var CHART_GAP = 60;
 var READOUT_W = 460;
 var READOUT_LH = 1.35;
 var TALL_ASPECT = 1.15;
+var RESHAPE_SECONDS = 1.2;
+var GHOST_OPACITY = 0.28;
+var DRAW_SECONDS = 1.8;
+var DRAW_FLOOR = 1;
+var SEPARATE = 0.5;
+var STEP_FLOOR = 0.15;
 function chartScale(values) {
   const lo = Math.min(...values);
   const hi = Math.max(...values);
@@ -4130,7 +4189,8 @@ var lineChart = (beat, ctx) => {
   const { sid, theme } = ctx;
   const p = beat.params;
   const face = faceOf(theme.fontStack);
-  const scale = chartScale(p.points.map((pt) => pt.y));
+  const cmp = p.compare;
+  const scale = chartScale([...p.points, ...cmp?.points ?? []].map((pt) => pt.y));
   const box = contentW(ctx.format);
   const tall = isPortrait(ctx.format);
   const width = tall ? box : box - (p.readout ? CHART_GAP + READOUT_W : 0);
@@ -4173,11 +4233,15 @@ var lineChart = (beat, ctx) => {
   const LABEL_SIZE3 = 40;
   const runW = (s) => textWidth(s, LABEL_SIZE3, 400, 0, false, face);
   const catW = (s) => textWidth(s, LABEL_SIZE3, 400, 0, false, face);
+  const nameW = (s) => textWidth(s, LABEL_SIZE3, 500, 0, false, face);
+  const ghostW = (s) => textWidth(s, LABEL_SIZE3, 600, 0, false, face);
   const shownX = fitIndices((i) => catW(p.points[i]?.x ?? ""), false);
   const xLabels = p.points.map(
     (pt, i) => shownX.has(i) ? `<text x="${n2(x(i))}" y="${H - PAD2.b + 56}">${esc(pt.x)}</text>` : ""
   ).join("");
-  const path2 = p.points.map((pt, i) => `${i === 0 ? "M" : "L"}${n2(x(i))},${n2(y(pt.y))}`).join(" ");
+  const pathOf = (pts) => pts.map((pt, i) => `${i === 0 ? "M" : "L"}${n2(x(i))},${n2(y(pt.y))}`).join(" ");
+  const path2 = pathOf(p.points);
+  const basePath = cmp ? pathOf(cmp.points) : "";
   const dots = p.points.map(
     (pt, i) => `<circle class="dot" cx="${n2(x(i))}" cy="${n2(y(pt.y))}" r="${i === p.points.length - 1 ? 11 : 9}" fill="${i === p.points.length - 1 ? theme.tones.b : theme.accent}" />`
   ).join("");
@@ -4213,6 +4277,75 @@ var lineChart = (beat, ctx) => {
   }).join("");
   const first = { x: x(0), y: y(p.points[0]?.y ?? 0) };
   const ring = p.points.length > 1 ? `<circle id="${sid}-ring" cx="${n2(first.x)}" cy="${n2(first.y)}" r="20" fill="none" stroke="${theme.tones.b}" stroke-width="5" opacity="0" />` : "";
+  const lineTag = (part, d, extra = "") => `<path class="chartline" id="${sid}-${part}" d="${d}" fill="none" stroke="${theme.accent}"${extra} />`;
+  const chartlines = cmp ? [
+    lineTag("base", basePath),
+    lineTag("line", basePath, ' opacity="0"'),
+    `<path id="${sid}-target" d="${path2}" fill="none" stroke="none" />`
+  ].join("\n    ") : lineTag("line", path2);
+  const curveBand = (pts, x0, x1) => {
+    const ys = [];
+    const py = (i) => y(pts[i]?.y ?? 0);
+    for (let i = 0; i < pts.length; i++) {
+      if (x(i) >= x0 && x(i) <= x1) ys.push(py(i));
+    }
+    for (let i = 0; i + 1 < pts.length; i++) {
+      const [ax, bx] = [x(i), x(i + 1)];
+      for (const edge of [x0, x1]) {
+        if (edge > Math.min(ax, bx) && edge < Math.max(ax, bx)) {
+          ys.push(py(i) + (py(i + 1) - py(i)) * (edge - ax) / (bx - ax));
+        }
+      }
+    }
+    return ys.length > 0 ? [Math.min(...ys), Math.max(...ys)] : [Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  };
+  const fixedBoxes = [
+    // `.axname` is the one run here set at weight 500 rather than 400, and
+    // under-charging a width is the unrecoverable direction (see `padR`).
+    // No `text-anchor` on the y half, so it runs rightwards from x=0.
+    { x: 0, y: 42 - LABEL_SIZE3, w: nameW(p.yLabel), h: LABEL_SIZE3 },
+    {
+      x: PAD2.l + plotW / 2 - nameW(p.xLabel) / 2,
+      y: H - 16 - LABEL_SIZE3,
+      w: nameW(p.xLabel),
+      h: LABEL_SIZE3
+    },
+    ...ticks.map((v) => {
+      const w = runW(v.toFixed(scale.decimals));
+      return { x: PAD2.l - 22 - w, y: y(v) + 13 - LABEL_SIZE3, w, h: LABEL_SIZE3 };
+    }),
+    ...p.points.map((pt, i) => ({ pt, i })).filter(({ i }) => shownX.has(i)).map(({ pt, i }) => labelBox(x(i), H - PAD2.b + 56, pt.x))
+  ];
+  const lastI = p.points.length - 1;
+  const ghost = (() => {
+    if (!cmp) return void 0;
+    const w = ghostW(cmp.label);
+    if (w > plotW) {
+      throw new Error(
+        `line-chart ${beat.id}: the compare label "${cmp.label}" is ${Math.ceil(w)}px against the ${Math.floor(plotW)}px of plot it is set in. Shorten it.`
+      );
+    }
+    const atEnd = (i, start) => {
+      const cy = y(cmp.points[i]?.y ?? 0);
+      const away = Math.max(44, cy - 26);
+      const toward = Math.min(cy + 52, H - PAD2.b + 4);
+      const sides = cy < y(p.points[i]?.y ?? 0) ? [away, toward] : [toward, away];
+      return sides.map((by) => ({ i, start, by }));
+    };
+    const drawnDeltas = deltasFit ? deltaBoxes : [];
+    return [...atEnd(lastI, false), ...atEnd(0, true)].find((c) => {
+      const box2 = { x: c.start ? x(c.i) : x(c.i) - w, y: c.by - LABEL_SIZE3, w, h: LABEL_SIZE3 };
+      if (fixedBoxes.some((f) => overlaps(box2, f))) return false;
+      if (valueBoxes.some((v) => overlaps(box2, v))) return false;
+      if (drawnDeltas.some((d) => d !== null && overlaps(box2, d))) return false;
+      return ![p.points, cmp.points].some((series) => {
+        const [top, bottom] = curveBand(series, box2.x, box2.x + box2.w);
+        return Math.min(box2.y + box2.h, bottom) - Math.max(box2.y, top) > 8;
+      });
+    });
+  })();
+  const ghostLabel = cmp && ghost ? `
+    <text class="ghostlab" id="${sid}-ghostlab" text-anchor="${ghost.start ? "start" : "end"}" x="${n2(x(ghost.i))}" y="${n2(ghost.by)}">${esc(cmp.label)}</text>` : "";
   const readout = p.readout ? `
   <div class="readout" id="${sid}-read">${esc(p.readout)}</div>` : "";
   const html = `${chrome(sid, p.eyebrow, p.headline, box, face)}
@@ -4225,7 +4358,7 @@ var lineChart = (beat, ctx) => {
          the svg and the layout gate reports container_overflow. -->
     <text class="axname" x="0" y="42">${esc(p.yLabel)}</text>
     <text class="axname" x="${n2(PAD2.l + plotW / 2)}" y="${H - 16}" text-anchor="middle">${esc(p.xLabel)}</text>
-    <path class="chartline" id="${sid}-line" d="${path2}" fill="none" stroke="${theme.accent}" />
+    ${chartlines}${ghostLabel}
     <g>${dots}</g>
     ${ring}
     <g class="ptlab" text-anchor="middle">${values}</g>
@@ -4233,10 +4366,52 @@ var lineChart = (beat, ctx) => {
   </svg>${readout}
 </div>`;
   const draw2 = 0.8;
-  const step = Math.min(0.45, 1.8 / p.points.length);
+  const count = p.points.length;
+  const idealStep = Math.min(0.45, DRAW_SECONDS / count);
+  const spine = draw2 + SEPARATE + RESHAPE_SECONDS + (p.readout ? 0.8 : 0) + 0.15;
+  const shownDeltas = deltas ? Math.min((p.deltas ?? []).length, count - 1) : 0;
+  const tailAfter = (s) => Math.max(
+    s * count + 0.4,
+    // the ring: its walk, then the 0.4s it takes to leave
+    0.3 + s * (count - 1),
+    // the dots
+    0.5 + s * (count - 1),
+    ...shownDeltas > 0 ? [0.95 + s * (shownDeltas - 1)] : []
+  );
+  const room = beat.seconds - spine;
+  let drawCents = Math.round(DRAW_SECONDS * 100);
+  let stepCents = Math.floor(idealStep * 100);
+  if (cmp) {
+    while (drawCents / 100 + tailAfter(stepCents / 100) > room) {
+      if (drawCents > Math.round(DRAW_FLOOR * 100)) drawCents--;
+      else if (stepCents > Math.round(STEP_FLOOR * 100)) stepCents--;
+      else break;
+    }
+  }
+  const drawFor = cmp ? drawCents / 100 : DRAW_SECONDS;
+  const step = cmp ? stepCents / 100 : idealStep;
+  const lift2 = sec(draw2 + drawFor);
+  const settled = cmp ? sec(lift2 + SEPARATE + RESHAPE_SECONDS) : draw2;
   const tl = [
     ...chromeIn(sid, p.eyebrow !== void 0),
-    tween(`#${sid}-line`, DRAW_FROM, { ...DRAW_TO, duration: 1.8, ease: "none" }, draw2),
+    tween(
+      `#${sid}-${cmp ? "base" : "line"}`,
+      DRAW_FROM,
+      { ...DRAW_TO, duration: drawFor, ease: "none" },
+      draw2
+    )
+  ];
+  if (cmp) {
+    tl.push(
+      ...ghost ? [tween(`#${sid}-ghostlab`, { opacity: 0 }, { opacity: 1, duration: 0.5 }, draw2 + 0.4)] : [],
+      // The copy lifts off — same geometry, so the half-second reads as one line
+      // separating from itself rather than as a second line arriving.
+      tween(`#${sid}-line`, { opacity: 0 }, { opacity: 1, duration: SEPARATE }, lift2),
+      tween(`#${sid}-base`, { opacity: 1 }, { opacity: GHOST_OPACITY, duration: SEPARATE }, lift2),
+      reshape(`#${sid}-line`, `#${sid}-target`, lift2 + SEPARATE, RESHAPE_SECONDS, true)
+    );
+  }
+  tl.push(
     tween(
       `#${sid} .dot`,
       // Origin in both halves, or GSAP's smoothOrigin compensates the change with
@@ -4244,37 +4419,43 @@ var lineChart = (beat, ctx) => {
       // polyline they mark, inside the frame and so invisible to every gate.
       { opacity: 0, scale: 0, transformOrigin: "center" },
       { opacity: 1, scale: 1, transformOrigin: "center", duration: 0.3, stagger: step },
-      draw2
+      settled
     ),
-    tween(`#${sid} .pv`, { opacity: 0 }, { opacity: 1, duration: 0.3, stagger: step }, draw2 + 0.2)
-  ];
+    tween(
+      `#${sid} .pv`,
+      { opacity: 0 },
+      { opacity: 1, duration: 0.3, stagger: step },
+      settled + 0.2
+    )
+  );
   if (deltas) {
     tl.push(
       tween(
         `#${sid} .dv`,
         { opacity: 0, y: -10 },
         { opacity: 1, y: 0, duration: 0.35, stagger: step },
-        draw2 + 0.6
+        settled + 0.6
       )
     );
   }
-  if (p.points.length > 1) {
+  const walk = cmp ? sec(step * count) : DRAW_SECONDS;
+  if (count > 1) {
     const route = p.points.map((pt, i) => ({ x: nv(x(i) - first.x), y: nv(y(pt.y) - first.y) }));
     tl.push(
-      tween(`#${sid}-ring`, { opacity: 0 }, { opacity: 1, duration: 0.25 }, draw2),
-      ...travel(`#${sid}-ring`, route, draw2, 1.8),
+      tween(`#${sid}-ring`, { opacity: 0 }, { opacity: 1, duration: 0.25 }, settled),
+      ...travel(`#${sid}-ring`, route, settled, walk),
       // And it leaves once the curve is whole: a marker parked on the last
       // point for the rest of the beat reads as a defect, not as emphasis.
       tween(
         `#${sid}-ring`,
         { opacity: 1 },
         { opacity: 0, duration: 0.4, immediateRender: false },
-        draw2 + 1.8
+        settled + walk
       )
     );
   }
-  const drawn = draw2 + step * p.points.length + 0.4;
-  const holds = [drawn];
+  const drawn = settled + (cmp ? tailAfter(step) : step * count + 0.4);
+  const holds = cmp ? [lift2, drawn] : [drawn];
   if (p.readout) {
     tl.push(
       // It enters from wherever it sits: from the right when it is beside the
@@ -4283,9 +4464,22 @@ var lineChart = (beat, ctx) => {
     );
     holds.push(drawn + 0.8);
   }
+  const end = holds[holds.length - 1] ?? 0;
+  const need = sec(end + 0.15);
+  if (cmp && need > beat.seconds + 1e-9) {
+    return {
+      ...lineChart({ ...beat, params: { ...p, compare: void 0 } }, ctx),
+      warnings: [
+        `line-chart ${beat.id}: a comparison against "${cmp.label}" over ${count} points needs ${need}s and the beat is ${beat.seconds}s, so the chart was drawn without it. Lengthen the beat to keep the comparison.`
+      ]
+    };
+  }
   return {
     html,
     tl,
+    // Named only when a beat actually reshapes, which is what keeps MorphSVG's
+    // 21,195 bytes off every deck that does not. See `PLUGINS` in composition.ts.
+    ...cmp ? { plugins: ["morphSVG"] } : {},
     holds: holdsWithin(holds, beat.seconds),
     css: [
       chromeCss(theme),
@@ -4310,6 +4504,14 @@ var lineChart = (beat, ctx) => {
       `.axname{font-size:40px;fill:${theme.muted};font-weight:500}`,
       `.ptlab{font-size:40px;fill:${theme.fg};font-weight:600}`,
       `.delta{font-size:40px;fill:${theme.tones.b};font-weight:600}`,
+      // Only when a ghost was actually named — not merely when there is a ghost,
+      // since the label is dropped where neither side of the baseline is clear.
+      // An unconditional rule would move the stylesheet bytes of every line chart
+      // ever built for a part they do not draw, which is the whole thing
+      // `Scene.plugins` is careful about one level up. `muted`, not `dim`: it
+      // names a series, so it is read, and the curve it names is the thing that
+      // has been faded, not its label.
+      ...ghost ? [`.ghostlab{font-size:40px;fill:${theme.muted};font-weight:600}`] : [],
       // 1.7 set the two lines of a wrapped readout 68px apart, which reads as two
       // unrelated fragments rather than one sentence. 1.35 keeps it a paragraph.
       `.readout{font-size:${BODY_SIZE}px;line-height:${READOUT_LH};color:${theme.muted};max-width:${READOUT_W}px}`,
@@ -5555,7 +5757,10 @@ function round4(n3) {
 // src/emit/composition.ts
 var GSAP_SRC = "./vendor/gsap.min.js";
 var DRAWSVG_SRC = "./vendor/DrawSVGPlugin.min.js";
-var MORPH_SRC = "./vendor/ds-morph.js";
+var PLUGINS = {
+  dsMorph: { src: "./vendor/ds-morph.js", global: "DSMorphPlugin" },
+  morphSVG: { src: "./vendor/MorphSVGPlugin.min.js", global: "MorphSVGPlugin" }
+};
 var KATEX_JS = "./vendor/katex.min.js";
 var KATEX_CSS = "./katex/katex.min.css";
 function emitDeck(storyboard, source, format, runtimeJs, opts = {}) {
@@ -5663,7 +5868,15 @@ function layout(storyboard, source, format, opts = {}) {
     }
     if (scene.css) archetypeCss.add(scene.css.trim());
     if (scene.measure?.length) builds = true;
-    for (const p of scene.plugins ?? []) plugins.add(p);
+    for (const w of cut2.scene.warnings ?? []) opts.onBeatWarning?.(beat.id, w);
+    for (const p of scene.plugins ?? []) {
+      if (!Object.hasOwn(PLUGINS, p)) {
+        throw new Error(
+          `${beat.archetype} ${beat.id}: no vendored plugin named "${p}" \u2014 Scene.plugins takes ${Object.keys(PLUGINS).join(" or ")}`
+        );
+      }
+      plugins.add(p);
+    }
     scenes.push(
       sceneHtml(
         sid,
@@ -5783,9 +5996,11 @@ function renderComposition(storyboard, format, laid) {
     <link rel="stylesheet" href="${FONT_BUNDLE_HREF}" />` : "";
   const island = format.navigable ? `
 ${emitIsland(slides)}` : "";
-  const morph = laid.plugins.has("dsMorph") ? `
-    <script src="${MORPH_SRC}"></script>
-    <script>gsap.registerPlugin(DSMorphPlugin);</script>` : "";
+  const plugins = Object.entries(PLUGINS).filter(([name]) => laid.plugins.has(name)).map(
+    ([, p]) => `
+    <script src="${p.src}"></script>
+    <script>gsap.registerPlugin(${p.global});</script>`
+  ).join("");
   return `<!doctype html>
 <html lang="${esc(storyboard.lang)}" data-resolution="${orientation}">
   <head>
@@ -5794,7 +6009,7 @@ ${emitIsland(slides)}` : "";
     <meta name="viewport" content="width=${format.width}, height=${format.height}" />
     <script src="${GSAP_SRC}"></script>
     <script src="${DRAWSVG_SRC}"></script>
-    <script>gsap.registerPlugin(DrawSVGPlugin);</script>${morph}
+    <script>gsap.registerPlugin(DrawSVGPlugin);</script>${plugins}
     <link rel="stylesheet" href="${KATEX_CSS}" />
     <script src="${KATEX_JS}"></script>${fontLink}${fontFace}
     <style>
@@ -6669,8 +6884,8 @@ async function send(url, target, headers, signal, opts) {
     ...secure && isIP(host) === 0 ? { servername: host } : {}
   };
   try {
-    return await new Promise((resolve6, reject) => {
-      const req = (secure ? httpsRequest : httpRequest)(options, resolve6);
+    return await new Promise((resolve7, reject) => {
+      const req = (secure ? httpsRequest : httpRequest)(options, resolve7);
       req.on("error", reject);
       req.end();
     });
@@ -6758,18 +6973,26 @@ import { createRequire as createRequire2 } from "node:module";
 import { homedir } from "node:os";
 import { join as join2 } 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 || join2(homedir(), ".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(join2(homedir(), ".cache", "hyperframes", "chrome"));
+  if (hf) return { path: hf.executablePath, source: "hyperframes" };
+  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join2(homedir(), ".cache", "puppeteer"));
+  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");
 }
@@ -6786,12 +7009,24 @@ async function openDeck(dir, opts = {}) {
   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();
@@ -6807,6 +7042,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,
@@ -6839,7 +7086,7 @@ import { z as z2 } from "zod";
 async function fetchFigures(source, dir, warnings) {
   const drops = warnings ?? [];
   await mkdir3(dir, { recursive: true });
-  const cached = await readdir(dir).catch(() => []);
+  const cached2 = await readdir(dir).catch(() => []);
   const figures = [];
   for (const figure of source.figures) {
     if (figure.kind === "clip") {
@@ -6847,7 +7094,7 @@ async function fetchFigures(source, dir, warnings) {
       continue;
     }
     try {
-      figures.push(figureSchema.parse(await localize(figure, dir, cached)));
+      figures.push(figureSchema.parse(await localize(figure, dir, cached2)));
     } catch (err) {
       drops.push(`figure ${figure.id} was left out: ${reason(err)}`);
     }
@@ -6861,15 +7108,15 @@ async function fetchFigures(source, dir, warnings) {
   }
   return parsed.data;
 }
-async function localize(figure, dir, cached) {
+async function localize(figure, dir, cached2) {
   const stem = assetStem(figure.id, figure.src);
-  const hit = cached.find((name) => name.startsWith(`${stem}.`));
+  const hit = cached2.find((name) => name.startsWith(`${stem}.`));
   const bytes = hit ? await readFile4(join3(dir, hit)) : await load(figure.src);
   const size2 = imageSize(bytes);
   if (hit) return { ...figure, src: hit, ...size2 };
   const src = `${stem}${assetExt(bytes, figure.src)}`;
   await writeFile3(join3(dir, src), bytes);
-  cached.push(src);
+  cached2.push(src);
   return { ...figure, src, ...size2 };
 }
 function assetStem(id2, src) {
@@ -7455,7 +7702,7 @@ ${tail3}`);
   }
 }
 function runLive(file, args) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const child = spawn(file, args, { stdio: ["ignore", "inherit", "inherit"] });
     child.on("error", (err) => {
       reject(
@@ -7463,7 +7710,7 @@ function runLive(file, args) {
       );
     });
     child.on("close", (code, signal) => {
-      if (code === 0) resolve6();
+      if (code === 0) resolve7();
       else if (signal) {
         reject(
           new Error(
@@ -7790,7 +8037,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 {
@@ -8842,7 +9093,10 @@ var REVEALS = {
   "equation-walk": "one per term",
   "equation-morph": "2",
   "data-table": "one per highlighted row, plus 1",
-  "line-chart": "1",
+  // "long enough" is not a hedge: below the emitter's own floor the comparison
+  // is dropped and the chart stops twice becoming a chart that stops once. See
+  // the line-chart entry under THE THIRTEEN ARCHETYPES for what that costs.
+  "line-chart": "1, or 2 when compare is given and the beat is long enough for it",
   callout: "one per panel",
   pipeline: "one per stage",
   "annotated-figure": "one per note, plus 1",
@@ -8965,6 +9219,29 @@ DRAWING ARCHETYPES \u2014 reach here first
                  scale, over training. Points come from the source's numbers;
                  deltas, if given, are the steps between consecutive points, so
                  there is always one fewer.
+                 \`compare\` adds a SECOND CONDITION over the same axis \u2014 the tell
+                 there is THE SAME QUANTITY MEASURED TWO WAYS, a baseline and the
+                 result, where what the source is claiming is the change in the
+                 SHAPE of the curve and not two numbers. Its \`label\` names the
+                 baseline ("without pretraining", "FP32") and is drawn on the
+                 slide where the chart has room for it. Keep it SHORT \u2014 two or
+                 three words. A label wider than the plot is refused and the
+                 whole slide goes with it, and one that cannot be placed clear of
+                 the axis names, the values and both curves is dropped without a
+                 word, leaving the baseline unnamed. A \`readout\` takes the plot
+                 down to about two thirds of its width, so a beat that has one
+                 has room for a shorter label still.
+                 \`compare.points\` must carry the SAME x values, in the
+                 same order, as \`points\`; the baseline is drawn first, then the
+                 curve reshapes into \`points\` and leaves the baseline behind. Do
+                 not use it for two unrelated series that happen to share an
+                 axis \u2014 nothing reshapes into something it is not a version of.
+                 A compare beat also costs TIME \u2014 the baseline draws, is held,
+                 then reshapes \u2014 so give it \`seconds\` of 7, or 8 with a
+                 \`readout\`. Give it too few and the emitter draws the chart
+                 without the comparison rather than stopping on a half-drawn one:
+                 the slide is still there, but the point about the baseline is
+                 gone.
 
 DESCRIBING ARCHETYPES \u2014 the fallbacks
 
@@ -9749,7 +10026,7 @@ function codexCommand(args) {
 }
 function runCodex(args) {
   const { argv, env } = codexCommand(args);
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const child = spawn2("codex", argv, {
       stdio: ["pipe", "ignore", "pipe"],
       ...env === void 0 ? {} : { env }
@@ -9772,7 +10049,7 @@ function runCodex(args) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (code === 0) return resolve6();
+      if (code === 0) return resolve7();
       reject(
         new Error(`codex exec exited ${code}.
 ${stderr.trim().split("\n").slice(-8).join("\n")}`)
@@ -10243,7 +10520,7 @@ async function find2(can) {
   throw new Error(MISSING);
 }
 function runArgv(cmd, args) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const child = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
@@ -10253,8 +10530,8 @@ function runArgv(cmd, args) {
     child.stderr.on("data", (b) => {
       stderr += b.toString();
     });
-    child.on("error", (e) => resolve6({ code: -1, stderr: String(e), stdout }));
-    child.on("close", (code) => resolve6({ code: code ?? -1, stderr, stdout }));
+    child.on("error", (e) => resolve7({ code: -1, stderr: String(e), stdout }));
+    child.on("close", (code) => resolve7({ code: code ?? -1, stderr, stdout }));
   });
 }
 var edgeTts = {
@@ -10353,8 +10630,8 @@ async function synthesize(text2, opts) {
   const file = `${key}.mp3`;
   const audio = join8(opts.dir, file);
   const sidecar = join8(opts.dir, `${key}.json`);
-  const cached = await readSidecar(sidecar);
-  if (cached) return { audio, file, seconds: cached.seconds, cues: cached.cues };
+  const cached2 = await readSidecar(sidecar);
+  if (cached2) return { audio, file, seconds: cached2.seconds, cues: cached2.cues };
   await mkdir6(opts.dir, { recursive: true });
   const spoken = await provider.speak({ text: text2, voice: opts.voice, rate, pitch, audio });
   const { cues, seconds } = spoken;
@@ -12489,13 +12766,61 @@ ${issues}`);
   return parsed.data;
 }
 
+// src/tmpdir.ts
+import { realpathSync } from "node:fs";
+import { createRequire as createRequire3 } from "node:module";
+import { tmpdir as tmpdir4 } from "node:os";
+import { basename as basename4, dirname as dirname4, join as join16, resolve as resolve5, sep as sep2 } from "node:path";
+var cached;
+function real(dir) {
+  let at = resolve5(dir);
+  const tail3 = [];
+  for (; ; ) {
+    try {
+      return join16(realpathSync(at), ...tail3);
+    } catch {
+      const up = dirname4(at);
+      if (up === at) return resolve5(dir);
+      tail3.unshift(basename4(at));
+      at = up;
+    }
+  }
+}
+function packageRoot() {
+  cached ??= real(dirname4(createRequire3(import.meta.url).resolve("../package.json")));
+  return cached;
+}
+function insideRoot(dir) {
+  const root = packageRoot();
+  const at = real(dir);
+  return at === root || at.startsWith(root + sep2);
+}
+function guardTmpdir() {
+  const before = tmpdir4();
+  if (!insideRoot(before)) return;
+  delete process.env.TMPDIR;
+  const after = tmpdir4();
+  if (insideRoot(after)) {
+    throw new Error(
+      `tmpdir: ${after} is still inside ${packageRoot()}. Set TMPDIR to a real temp directory.`
+    );
+  }
+  const worker = process.env.VITEST_WORKER_ID;
+  if (worker === void 0 || worker === "1") {
+    process.stderr.write(
+      `tmpdir: TMPDIR pointed at ${before}, inside the source tree, so every mkdtemp would land in the repo. Using ${after}. Fix the environment \u2014 this only stops the mess.
+`
+    );
+  }
+}
+
 // src/index.ts
 async function buildDeck(storyboard, source, outDir, opts = {}) {
   const format = opts.format ?? FORMATS["deck-16x9"];
   if (!format) throw new Error("no deck-16x9 format");
   const step = opts.onStep ?? (() => {
   });
-  const out = resolve5(outDir);
+  const out = resolve6(outDir);
   await mkdir10(out, { recursive: true });
   const speed = opts.speed ?? 1;
   const fontCss = await refreshFont(storyboard, source, out, step);
@@ -12504,12 +12829,13 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
     ...opts.theme ? { theme: opts.theme } : {},
     ...opts.narration ? { narration: opts.narration } : {},
     ...opts.onBeatError ? { onBeatError: opts.onBeatError } : {},
+    ...opts.onBeatWarning ? { onBeatWarning: opts.onBeatWarning } : {},
     ...fontCss ? { fontCss } : {}
   });
   const files = [];
   const write = async (name, text2) => {
-    await writeFile12(join16(out, name), text2);
-    files.push(join16(out, name));
+    await writeFile12(join17(out, name), text2);
+    files.push(join17(out, name));
   };
   await write("index.html", deck.composition);
   await write("hyperframes.json", HYPERFRAMES_JSON);
@@ -12538,8 +12864,8 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   }
   if (deck.page) {
     await write(DECK_PAGE, deck.page);
-    await cp(playerBundle(), join16(out, PLAYER_FILE));
-    files.push(join16(out, PLAYER_FILE));
+    await cp(playerBundle(), join17(out, PLAYER_FILE));
+    files.push(join17(out, PLAYER_FILE));
   }
   files.push(...await vendorKatex(out));
   if (opts.assetsFrom) files.push(...await copyAssets(opts.assetsFrom, out));
@@ -12548,7 +12874,7 @@ async function buildDeck(storyboard, source, outDir, opts = {}) {
   }
   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 ${join16(out, "index.html")}`
+    `build: ${deck.cut.kept.length}${of} beats at ${format.width}\xD7${format.height} \u2192 ${join17(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}`);
@@ -12572,40 +12898,40 @@ async function deckRuntime() {
   }
 }
 function playerBundle() {
-  const require2 = createRequire3(import.meta.url);
+  const require2 = createRequire4(import.meta.url);
   try {
-    return join16(dirname4(require2.resolve("hyperframes/package.json")), "dist", PLAYER_FILE);
+    return join17(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 = join16(dirname4(require2.resolve("katex/package.json")), "dist");
-  const css = await readFile17(join16(dist, "katex.min.css"), "utf8");
+  const require2 = createRequire4(import.meta.url);
+  const dist = join17(dirname5(require2.resolve("katex/package.json")), "dist");
+  const css = await readFile17(join17(dist, "katex.min.css"), "utf8");
   const written = [];
-  await mkdir10(join16(out, "katex/fonts"), { recursive: true });
-  for (const file of await readdir4(join16(dist, "fonts"))) {
+  await mkdir10(join17(out, "katex/fonts"), { recursive: true });
+  for (const file of await readdir4(join17(dist, "fonts"))) {
     if (!file.endsWith(".woff2")) continue;
-    await cp(join16(dist, "fonts", file), join16(out, "katex/fonts", file));
-    written.push(join16(out, "katex/fonts", file));
+    await cp(join17(dist, "fonts", file), join17(out, "katex/fonts", file));
+    written.push(join17(out, "katex/fonts", file));
   }
   const woff2Only = css.replace(/src:([^;}]*)/g, (whole, list) => {
     const kept = list.split(",").filter((part) => part.includes(".woff2")).join(",");
     return kept ? `src:${kept}` : whole;
   });
-  await writeFile12(join16(out, "katex/katex.min.css"), woff2Only);
-  written.push(join16(out, "katex/katex.min.css"));
+  await writeFile12(join17(out, "katex/katex.min.css"), woff2Only);
+  written.push(join17(out, "katex/katex.min.css"));
   return written;
 }
 async function copyAssets(sourceDir, out) {
-  const from = join16(resolve5(sourceDir), "assets");
+  const from = join17(resolve6(sourceDir), "assets");
   if (!await stat2(from).catch(() => null)) return [];
-  await cp(from, join16(out, "assets"), { recursive: true });
-  return [join16(out, "assets")];
+  await cp(from, join17(out, "assets"), { recursive: true });
+  return [join17(out, "assets")];
 }
 async function copyAudio(from, narration, out) {
-  const dir = join16(out, narration.dir);
+  const dir = join17(out, narration.dir);
   await mkdir10(dir, { recursive: true });
   const names = [
     ...new Set(
@@ -12613,18 +12939,18 @@ async function copyAudio(from, narration, out) {
     )
   ].sort();
   for (const name of names) {
-    await cp(join16(resolve5(from), name), join16(dir, name)).catch(() => {
+    await cp(join17(resolve6(from), name), join17(dir, name)).catch(() => {
       throw new Error(`Narration names ${name}, but it is not in ${from}. Re-run \`narrate\`.`);
     });
   }
-  return names.map((n3) => join16(dir, n3));
+  return names.map((n3) => join17(dir, n3));
 }
 async function refreshFont(storyboard, source, out, step) {
   try {
     const bundle = await bundleFont(
       storyboard.lang,
       JSON.stringify(source) + JSON.stringify(storyboard),
-      join16(out, "assets", "fonts")
+      join17(out, "assets", "fonts")
     );
     if (bundle) step(`build: font bundle covers ${bundle.family}`);
     return bundle?.css;
@@ -12694,6 +13020,7 @@ export {
   framePlan,
   gradeOverprint,
   gridParamsSchema,
+  guardTmpdir,
   harvest,
   hasIllustrations,
   illustrate,