@jokerized/decksmith 0.4.0 → 0.4.1

package/dist/cli.js

@@ -8922,18 +8922,26 @@ import { createRequire as createRequire2 } from "node:module";
 import { homedir as homedir2 } from "node:os";
 import { join as join8 } from "node:path";
 import { pathToFileURL } from "node:url";
-async function chromePath(need = "open the deck with") {
-  const explicit = process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
-  if (explicit) return explicit;
+async function resolveChrome(need = "open the deck with") {
+  const env = process.env.HYPERFRAMES_BROWSER_PATH || process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
+  if (env) return { path: env, source: "env" };
   const { getInstalledBrowsers } = await import("@puppeteer/browsers");
-  const cacheDir = process.env.PUPPETEER_CACHE_DIR || join8(homedir2(), ".cache", "puppeteer");
-  const installed2 = await getInstalledBrowsers({ cacheDir }).catch(() => []);
-  const found = installed2.find((b) => b.browser === "chrome-headless-shell") ?? installed2.find((b) => b.browser === "chrome");
-  if (found) return found.executablePath;
+  const pick = async (cacheDir) => {
+    const installed2 = await getInstalledBrowsers({ cacheDir }).catch(() => []);
+    const ordered = [...installed2].sort((a, b) => b.buildId.localeCompare(a.buildId, "en"));
+    return ordered.find((b) => b.browser === "chrome-headless-shell") ?? ordered.find((b) => b.browser === "chrome");
+  };
+  const hf = await pick(join8(homedir2(), ".cache", "hyperframes", "chrome"));
+  if (hf) return { path: hf.executablePath, source: "hyperframes" };
+  const pup = await pick(process.env.PUPPETEER_CACHE_DIR || join8(homedir2(), ".cache", "puppeteer"));
+  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");
 }
@@ -8950,12 +8958,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();
@@ -8971,6 +8991,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,
@@ -10324,7 +10356,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 {

package/dist/index.js

@@ -6973,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");
 }
@@ -7001,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();
@@ -7022,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,
@@ -8005,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 {

package/dist/mcp.js

@@ -6992,18 +6992,26 @@ function message(err) {
 // src/render/capture.ts
 import { homedir } from "node:os";
 import { join as join3 } from "node:path";
-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 env2 = process.env.HYPERFRAMES_BROWSER_PATH || process.env.DECKSMITH_CHROME || process.env.CHROME_PATH;
+  if (env2) return { path: env2, source: "env" };
   const { getInstalledBrowsers } = await import("@puppeteer/browsers");
-  const cacheDir = process.env.PUPPETEER_CACHE_DIR || join3(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(join3(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"));
+  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;
+}
 
 // src/source/assets.ts
 import { createHash as createHash4 } from "node:crypto";
@@ -7964,7 +7972,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 {

package/dist/types/render/capture.d.ts

@@ -23,7 +23,16 @@
  * the renderer's own clip.
  */
 /**
- * The browser `render` already uses.
+ * The browser `render` already uses — which, until 2026-09-11, this did not find.
+ *
+ * IT PREFERRED PUPPETEER'S CACHE AND SAID THE TWO WERE INTERCHANGEABLE. They are
+ * not. The renderer runs hyperframes' own shell out of `~/.cache/hyperframes`
+ * (152 here); puppeteer's cache holds 145. For a screenshot of a static DOM the
+ * old comment was right and nothing noticed for months. For a WebGL canvas 145
+ * refuses a context and 152 grants one, so `frames` and the `fidelity` gate
+ * returned a clean, plausible, EMPTY frame — the seventh case in this repo of a
+ * green gate over wrong output, and the first found by opening a PNG that had
+ * nothing in it. See `.planning/2026-09-09-webgl-determinism-spike.md`.
  *
  * `@puppeteer/browsers` and `puppeteer-core` are DIRECT dependencies of this
  * package. They arrive with hyperframes too — a hard dependency of any verb that
@@ -39,6 +48,23 @@
  * was two copies until `frames` became the third caller the older of them said
  * to promote it on.
  */
+export interface ResolvedChrome {
+    path: string;
+    /** Where it came from, so a caller can say whether it matches the renderer. */
+    source: "env" | "hyperframes" | "puppeteer";
+}
+/**
+ * Resolve, in the renderer's own order of preference.
+ *
+ * `HYPERFRAMES_BROWSER_PATH` first because that is the variable the renderer
+ * itself honours, so setting it makes the two provably the same binary. Then
+ * hyperframes' cache, which is where the renderer gets its shell when nobody has
+ * set anything. Puppeteer's cache is LAST and is a different browser: it is kept
+ * because a machine that has only that one should still be able to look at a
+ * DOM-only deck, not because the two agree.
+ */
+export declare function resolveChrome(need?: string): Promise<ResolvedChrome>;
+/** The path alone, for the callers that only ever wanted that. */
 export declare function chromePath(need?: string): Promise<string>;
 type Browser = Awaited<ReturnType<typeof import("puppeteer-core").launch>>;
 type Page = Awaited<ReturnType<Browser["newPage"]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",