@lutrin/core 1.0.0 → 1.1.1

package/README.md

@@ -2,23 +2,32 @@
 
 The engine behind [Lutrin](../../README.md): enriched Markdown (a DSL) →
 PowerPoint `.pptx` or standalone HTML, with the page layout decided by the
-engine. It provides the `lutrin` CLI, and serves as a library for the editor
-hosts (VS Code extension, Obsidian plugin).
+engine. It carries the CLI implementation and serves as a library for the
+editor hosts (VS Code extension, Obsidian plugin). The command itself is
+published separately as [`lutrin`](https://www.npmjs.com/package/lutrin), a
+thin entry point that depends on this package.
 
 Neither output format is privileged: both renderers consume the **same**
 geometric **scene**, in pixels on a 1280 × 720 grid.
 
 ## Installation
 
-The package is not published on npm yet. From a clone of the repository:
+To use the compiler as a library:
 
 ```bash
-npm install                 # at the root of the monorepo
-npx lutrin --help
+npm install @lutrin/core
+```
 
-npm link -w lutrin          # to call "lutrin" from anywhere
+```js
+import { compileHtml } from '@lutrin/core';
+import { parseDeck } from '@lutrin/core/parse';
+import { validateDeck } from '@lutrin/core/validate';
 ```
 
+For the command line, install [`lutrin`](https://www.npmjs.com/package/lutrin)
+instead — or just `npx lutrin`. From a clone of the repository,
+`npm link -w lutrin` puts the command on your PATH.
+
 Node ≥ 22 (`engines.node`). The sources are executed as they are (ESM) — no
 build step.
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@lutrin/core",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Markdown → PowerPoint / HTML presentation compiler, themable: a generic default theme, organization brand kits distributed as .deckkit archives.",
   "type": "module",
   "scripts": {
     "test": "node --import ./test/setup.mjs --test \"test/*.test.mjs\""
   },
-  "files": ["src", "design", "README.md"],
+  "files": ["src", "design", "vendor", "README.md"],
   "publishConfig": {
     "access": "public"
   },
@@ -29,7 +29,8 @@
     "markdown-it": "^14.3.0",
     "markdown-it-container": "^4.0.0",
     "mathjax-full": "^3.2.1",
-    "pptxgenjs": "4.0.1"
+    "pptxgenjs": "4.0.1",
+    "puppeteer-core": "^25.3.0"
   },
   "peerDependencies": {
     "@mermaid-js/mermaid-cli": "^11.16.0"

package/src/cli.mjs

@@ -84,6 +84,7 @@ const COMMANDS = [
   'config',
   'kit',
   'vendor',
+  'setup-mermaid',
 ];
 
 const USAGE = `Usage:
@@ -98,6 +99,7 @@ const USAGE = `Usage:
   lutrin kit remove <name>
   lutrin kit create <directory> [-o <file.deckkit>]
   lutrin capabilities [<input.md>] [--kit <kit|file.json|directory>] [--json]
+  lutrin setup-mermaid [--yes]
   lutrin --version | --help`;
 
 /** Help that was ASKED FOR is an answer (stdout, exit code 0); usage recalled
@@ -163,6 +165,9 @@ const FLAG_SPECS = {
   // real context (installed kit, layouts/ next to the deck) and not just that
   // of the bare engine.
   capabilities: { ...FLAGS_KIT, json: 'boolean' },
+  // `--yes` is what authorizes the ~200 MB download: a browser never arrives
+  // on a machine because someone ran a diagnostic.
+  'setup-mermaid': { yes: 'boolean' },
 };
 
 /**
@@ -456,7 +461,7 @@ async function cmdBuild(argv) {
   if (stats.mermaidTotal && stats.mermaidRendered < stats.mermaidTotal) {
     const missing = stats.mermaidTotal - stats.mermaidRendered;
     console.log(
-      `  ${missing} Mermaid diagram${missing > 1 ? 's' : ''} rendered as a text fallback (install @mermaid-js/mermaid-cli for graphical rendering)`,
+      `  ${missing} Mermaid diagram${missing > 1 ? 's' : ''} rendered as a text fallback — run \`lutrin setup-mermaid\` to diagnose`,
     );
   }
   if (stats.remoteTotal) {
@@ -992,7 +997,7 @@ async function cmdVendor(argv) {
   }
   for (const f of r.frontmatter) console.log(`  frontmatter: ${f}`);
   if (r.mermaid.done < r.mermaid.total)
-    console.log('  → diagrams not rendered: install @mermaid-js/mermaid-cli, then re-run vendor');
+    console.log('  → diagrams not rendered: run `lutrin setup-mermaid`, then re-run vendor');
   if (r.images.done < r.images.total)
     console.log('  → images not downloaded: check the URL or the connection, then re-run vendor');
   // self-containment is announced ONLY if nothing was left aside: until now the
@@ -1004,6 +1009,77 @@ async function cmdVendor(argv) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// setup-mermaid
+// ---------------------------------------------------------------------------
+
+/**
+ * Reports on the Mermaid rendering chain and, if nothing can drive it, offers
+ * to download a browser.
+ *
+ * The command exists because the failure it fixes is invisible: a diagram that
+ * cannot be rendered degrades to a readable code block, which is the right
+ * behaviour and looks, to the author, exactly like a compiler that does not do
+ * diagrams. This says out loud what is installed and what is missing.
+ *
+ * The download stays opt-in — `--yes` or an answered prompt. Nothing here runs
+ * during a build.
+ */
+async function cmdSetupMermaid(argv) {
+  const args = parseArgs(argv, FLAG_SPECS['setup-mermaid']);
+  const { findBrowser, downloadHeadlessShell, browserCacheDir } = await import(
+    './deck/browser.mjs'
+  );
+  const { findMmdc, renderMermaidCached } = await import('./deck/assets.mjs');
+
+  const mmdc = findMmdc();
+  let browser = findBrowser({ refresh: true });
+
+  console.log('Mermaid rendering:');
+  console.log(`  browser: ${browser ? `${browser.path} (${browser.source})` : 'none found'}`);
+  console.log(`  mermaid-cli: ${mmdc ?? 'not installed (optional — the browser is enough)'}`);
+
+  if (!browser) {
+    if (!args.yes) {
+      console.log(
+        [
+          '',
+          'No Chrome, Edge, Brave or Chromium was found, and Mermaid needs a browser',
+          'to measure the text it lays out.',
+          '',
+          'Installing any of those is the lightest fix. Otherwise lutrin can download',
+          `chrome-headless-shell (~200 MB) into ${browserCacheDir()}.`,
+          '',
+          'Re-run with --yes to download it.',
+        ].join('\n'),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`\nDownloading chrome-headless-shell into ${browserCacheDir()} …`);
+    const exe = await downloadHeadlessShell((line) => console.log(line));
+    console.log(`✓ browser installed: ${exe}`);
+    browser = findBrowser({ refresh: true });
+  }
+
+  // A found browser is not a working one — an install can be broken, a
+  // container can lack the shared libraries Chrome links against. Render a
+  // diagram and say so, rather than promising on the strength of a file
+  // existing.
+  process.stdout.write('\nRendering a test diagram … ');
+  const out = renderMermaidCached('flowchart LR\n  A[Lutrin] --> B[Mermaid]', { format: 'svg' });
+  if (out) {
+    console.log('✓');
+    console.log('\nMermaid diagrams will render. Nothing else to install.');
+    return;
+  }
+  const { lastMermaidError } = await import('./deck/assets.mjs');
+  console.log('✖');
+  console.log(`\nThe browser was found but could not render: ${lastMermaidError() ?? 'unknown'}`);
+  console.log('Set LUTRIN_BROWSER to another browser, or re-run with --yes to download one.');
+  process.exitCode = 1;
+}
+
 // ---------------------------------------------------------------------------
 // capabilities
 // ---------------------------------------------------------------------------
@@ -1101,6 +1177,9 @@ try {
     case 'capabilities':
       cmdCapabilities(rest2);
       break;
+    case 'setup-mermaid':
+      await cmdSetupMermaid(rest2);
+      break;
     default:
       usage();
   }

package/src/deck/assets.mjs

@@ -18,7 +18,10 @@
  *     to PNG when needed (`renderIcon`);
  *   - LaTeX equations  → MathJax (tex → SVG, glyphs as paths:
  *     `mathSvg`) then PNG when needed (`renderMath`);
- *   - Mermaid diagrams → mmdc (optional), as PNG (PPTX) or SVG (HTML).
+ *   - Mermaid diagrams → a browser already on the machine driven by
+ *     puppeteer-core (`browser.mjs`) over the Mermaid bundle vendored in
+ *     `vendor/mermaid/`, or `mmdc` when it happens to be installed — as PNG
+ *     (PPTX) or SVG (HTML).
  *
  * Every asset therefore exists in two flavors: SVG (inlined as is by the HTML
  * renderer) and a high-density PNG via @resvg/resvg-js (PowerPoint handles
@@ -41,6 +44,7 @@ import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { COLORS, FONTS, FONT_FILES } from './tokens.mjs';
+import { findBrowser } from './browser.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const require = createRequire(import.meta.url);
@@ -638,11 +642,15 @@ export async function iconSvg(name, { color = 'primary' } = {}) {
   return svg.replace(/currentColor/g, `#${hex}`);
 }
 
+/** Icon raster density (px) — shared with the callers that separate the SVG
+ *  lookup from the rasterization to tell the two failures apart. */
+export const ICON_RASTER_PX = 384;
+
 /**
  * Renders a Lucide icon as a recolored PNG.
  * @returns {{png:Buffer,w:number,h:number}|null}
  */
-export async function renderIcon(name, { color = 'primary', rasterPx = 384 } = {}) {
+export async function renderIcon(name, { color = 'primary', rasterPx = ICON_RASTER_PX } = {}) {
   const svg = await iconSvg(name, { color });
   return svg ? svgToPng(svg, rasterPx) : null;
 }
@@ -709,7 +717,7 @@ export async function renderMath(tex, { scale = 3 } = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// Mermaid (optional): PNG or SVG rendering via mmdc when it is available
+// Mermaid: PNG or SVG rendering, in a browser found on the machine (or mmdc)
 // ---------------------------------------------------------------------------
 
 /** Mermaid theme aligned on the active theme: light surfaces, neutral rules,
@@ -778,7 +786,7 @@ export function renderMermaid(sourceText, tmpDir, idx, mmdc, { format = 'png' }
     fs.writeFileSync(cfg, JSON.stringify(mermaidConfig()));
     fs.writeFileSync(src, sourceText);
     const args = ['-i', src, '-o', out, '-b', 'transparent', '-c', cfg];
-    if (format === 'png') args.push('-s', '3');
+    if (format === 'png') args.push('-s', String(MERMAID_PNG_SCALE));
     execFileSync(mmdc, args, { stdio: 'pipe', timeout: 60_000 });
     return fs.existsSync(out) ? out : null;
   } catch {
@@ -786,10 +794,82 @@ export function renderMermaid(sourceText, tmpDir, idx, mmdc, { format = 'png' }
   }
 }
 
+/** Raster scale of the PNG output (both the browser child and mmdc's `-s`).
+ *  Part of the PNG cache key: a diagram fills a slot of up to ~1180 px, so a
+ *  1× raster — as produced when `svgWidth` misread `width="100%"` — arrives
+ *  blurry, and bumping the scale must orphan those files. */
+export const MERMAID_PNG_SCALE = 3;
+
+/** The Mermaid bundle shipped inside the package (see vendor/mermaid/README).
+ *  Absent only from a broken install — in which case the browser path simply
+ *  does not apply and the caller keeps its fallback. */
+const MERMAID_BUNDLE = path.join(ROOT, 'vendor', 'mermaid', 'mermaid.min.js');
+
+/** This file, spawned as a child process. */
+const MERMAID_CHILD = path.join(ROOT, 'src', 'deck', 'mermaid-render.mjs');
+
+/** Last diagnosis from the browser renderer, for the CLI to surface. A silent
+ *  null told nobody whether the browser was missing, the source invalid, or
+ *  Chrome unable to start — three fixes behind one symptom. */
+let _mermaidError = null;
+export const lastMermaidError = () => _mermaidError;
+
+/**
+ * Renders a Mermaid diagram in a browser found on the machine, and returns the
+ * path of the produced file — or null, the caller keeping its fallback.
+ *
+ * Synchronous, like `renderMermaid()` above and for the same reason: both
+ * callers of `renderMermaidCached()` dispatch blocks in synchronous loops. The
+ * asynchrony lives in the child process (`mermaid-render.mjs`), which the
+ * timeout below bounds.
+ */
+export function renderMermaidBrowser(sourceText, tmpDir, idx, { format = 'png' } = {}) {
+  const browser = findBrowser();
+  if (!browser) {
+    _mermaidError = 'no browser found — run `lutrin setup-mermaid`';
+    return null;
+  }
+  if (!fs.existsSync(MERMAID_BUNDLE)) {
+    _mermaidError = `the vendored Mermaid bundle is missing (${MERMAID_BUNDLE})`;
+    return null;
+  }
+  try {
+    const out = path.join(tmpDir, `diagram-${idx}.${format}`);
+    const request = path.join(tmpDir, `request-${idx}.json`);
+    fs.writeFileSync(
+      request,
+      JSON.stringify({
+        source: sourceText,
+        config: mermaidConfig(),
+        out,
+        browser: browser.path,
+        mermaidBundle: MERMAID_BUNDLE,
+        format,
+        scale: MERMAID_PNG_SCALE,
+        fontFiles: [FONT_FILES.regular, FONT_FILES.bold, FONT_FILES.italic].filter(Boolean),
+        defaultFontFamily: FONTS.body,
+      }),
+    );
+    // 60 s, as for mmdc: a cold browser launch costs a few seconds, and a
+    // diagram that has not rendered by then never will.
+    execFileSync(process.execPath, [MERMAID_CHILD, request], { stdio: 'pipe', timeout: 60_000 });
+    if (fs.existsSync(out)) {
+      _mermaidError = null;
+      return out;
+    }
+    _mermaidError = 'the renderer produced no file';
+    return null;
+  } catch (err) {
+    _mermaidError = (err?.stderr?.toString() || err?.message || String(err)).trim().split('\n')[0];
+    return null;
+  }
+}
+
 /**
  * Renders a Mermaid diagram through a persistent cache and returns the path of
- * the rendered file — indispensable to the live preview: mmdc costs several
- * seconds per diagram, and it is never run again for a source already seen.
+ * the rendered file — indispensable to the live preview: rendering costs
+ * several seconds per diagram, and it is never run again for a source already
+ * seen.
  *
  *   - disk cache `~/.cache/lutrin/mermaid/` (key: sha1 source+format+config),
  *     shared between the CLI, watch and the VS Code extension, persistent
@@ -827,10 +907,10 @@ function mermaidCacheDir() {
  *
  *  Consulted BEFORE the user cache: that is what allows a self-contained
  *  directory to display on a machine where mmdc is not installed. Since the key
- *  is a hash of (source + format + theme config), a file found there is by
- *  construction the exact rendering asked for — consulting this directory
- *  therefore adds no semantics, only one more source for content that is
- *  already determined. */
+ *  is a hash of (source + format + theme config, plus the raster scale for
+ *  PNGs), a file found there is by construction the exact rendering asked
+ *  for — consulting this directory therefore adds no semantics, only one more
+ *  source for content that is already determined. */
 export const mermaidVendorDir = (baseDir) => path.join(baseDir, 'assets', 'mermaid');
 
 /**
@@ -852,9 +932,18 @@ function svgUsableInHtml(file) {
 }
 
 export function renderMermaidCached(sourceText, { format = 'png', baseDir = null } = {}) {
+  // the raster scale keys the PNGs only: SVGs are scale-free, and including it
+  // there would orphan every diagram already vendored next to existing decks
   const key = `${crypto
     .createHash('sha1')
-    .update(JSON.stringify({ s: sourceText, f: format, c: mermaidConfig() }))
+    .update(
+      JSON.stringify({
+        s: sourceText,
+        f: format,
+        c: mermaidConfig(),
+        ...(format === 'png' ? { px: MERMAID_PNG_SCALE } : {}),
+      }),
+    )
     .digest('hex')}.${format}`;
   // The FILE NAME depends only on the content (source + format + config) —
   // that is what makes a vendored directory readable by any Lutrin. The
@@ -879,13 +968,32 @@ export function renderMermaidCached(sourceText, { format = 'png', baseDir = null
     }
   }
 
+  // Two renderers, tried in order. mmdc first when it is there: someone who
+  // installed it asked for it, and it is the reference implementation. The
+  // browser is what makes a fresh machine work without installing anything —
+  // it needs no download, only a Chrome/Edge/Brave/Chromium already present.
   const mmdc = findMmdc();
-  if (!mmdc) return null;
+  const browser = findBrowser();
+  // No renderer at all → null WITHOUT memoizing it: installing a browser (or
+  // mmdc) must take effect without restarting the preview worker. A negative
+  // entry is only ever recorded for a source a working renderer refused.
+  if (!mmdc && !browser) {
+    _mermaidError = 'no browser found — run `lutrin setup-mermaid`';
+    return null;
+  }
+  const renderers = [
+    mmdc ? (dir) => renderMermaid(sourceText, dir, 0, mmdc, { format }) : null,
+    browser ? (dir) => renderMermaidBrowser(sourceText, dir, 0, { format }) : null,
+  ].filter(Boolean);
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lutrin-mmd-'));
   let result = null;
   try {
-    const out = renderMermaid(sourceText, tmpDir, 0, mmdc, { format });
+    let out = null;
+    for (const render of renderers) {
+      out = render(tmpDir);
+      if (out) break;
+    }
     if (out && (format !== 'svg' || svgUsableInHtml(out))) {
       // always written into the user cache, never into a vendored directory:
       // `lutrin vendor` alone decides what enters the project

package/src/deck/browser.mjs

@@ -0,0 +1,269 @@
+/**
+ * Finding a browser — the layout engine Mermaid needs.
+ *
+ * Mermaid measures the text it lays out (that is how it sizes nodes and routes
+ * edges), so it cannot render without a real layout engine. The historical way
+ * to give it one was `@mermaid-js/mermaid-cli`, which pulls Puppeteer and
+ * downloads a Chrome: 405 MB of `node_modules` plus ~540 MB of browser, on
+ * every install. That price is exactly why it stayed an optional peer
+ * dependency nobody installed — and therefore why diagrams degraded to a text
+ * fallback on every fresh machine, silently.
+ *
+ * The observation this module rests on: a machine that compiles a presentation
+ * almost always already HAS a browser. Driving that one costs `puppeteer-core`
+ * (28 MB, and, unlike `puppeteer`, it never downloads anything) instead of
+ * three quarters of a gigabyte.
+ *
+ * Order of preference, most explicit first:
+ *
+ *   1. `LUTRIN_BROWSER` — the escape hatch: an unusual install, a sandbox, a
+ *      pinned build. Never second-guessed, and a wrong path is reported rather
+ *      than silently skipped, otherwise setting the variable at all would be
+ *      indistinguishable from not setting it;
+ *   2. `PUPPETEER_EXECUTABLE_PATH` — the same intent, spelled the way the
+ *      surrounding ecosystem already spells it (containers, CI images);
+ *   3. `~/.cache/lutrin/browser/` — what `lutrin setup-mermaid` downloads when
+ *      the machine really has no browser. Preferred over a system install
+ *      because it is the one WE provisioned, at a version we know renders;
+ *   4. the system browsers, in the order below.
+ *
+ * Chrome, Edge, Brave and Chromium are all Chromium: any of them drives the
+ * CDP endpoint puppeteer-core speaks. Firefox and Safari are deliberately
+ * absent — Safari has no CDP at all, and Firefox's support does not cover what
+ * mermaid's rendering needs.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/** Root of the user cache — same resolution as assets.mjs (LUTRIN_CACHE,
+ *  MTL_DECK_CACHE for the tool's former name, XDG, then ~/.cache/lutrin).
+ *  Duplicated rather than imported: assets.mjs imports THIS module, and the
+ *  cycle would be paid on every load for six lines. */
+function userCacheRoot() {
+  return (
+    process.env.LUTRIN_CACHE ||
+    process.env.MTL_DECK_CACHE ||
+    (process.env.XDG_CACHE_HOME
+      ? path.join(process.env.XDG_CACHE_HOME, 'lutrin')
+      : path.join(os.homedir(), '.cache', 'lutrin'))
+  );
+}
+
+/** Where `lutrin setup-mermaid` puts the browser it downloads. */
+export const browserCacheDir = () => path.join(userCacheRoot(), 'browser');
+
+/** Candidate system paths, per platform, in order of preference. */
+function systemCandidates() {
+  const {
+    HOME = '',
+    LOCALAPPDATA = '',
+    PROGRAMFILES = '',
+    'PROGRAMFILES(X86)': PF86 = '',
+  } = process.env;
+
+  if (process.platform === 'darwin')
+    return [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      `${HOME}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ];
+
+  if (process.platform === 'win32')
+    return [
+      `${PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${PF86}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${PROGRAMFILES}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      `${PF86}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      `${PROGRAMFILES}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
+    ];
+
+  // Linux and the other unices: absolute paths first (a container often has the
+  // binary without a populated PATH), then the names, resolved below.
+  return [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/microsoft-edge',
+    '/usr/bin/brave-browser',
+    '/snap/bin/chromium',
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'microsoft-edge',
+    'brave-browser',
+  ];
+}
+
+/** Resolves a bare command name through PATH. `which`/`where` rather than a
+ *  hand-rolled PATH walk, so that shims and symlinks resolve the way the shell
+ *  would. */
+function onPath(name) {
+  try {
+    const out = execFileSync(process.platform === 'win32' ? 'where' : 'which', [name], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    // `where` can return several lines; the first is the one that would run
+    const first = out.split(/\r?\n/)[0].trim();
+    return first && fs.existsSync(first) ? first : null;
+  } catch {
+    return null;
+  }
+}
+
+const EXE_NAMES = new Set([
+  'chrome-headless-shell',
+  'chrome-headless-shell.exe',
+  'chrome',
+  'chrome.exe',
+]);
+
+/**
+ * The browser previously downloaded into the user cache, or null.
+ *
+ * A bounded depth-first walk rather than a hard-coded path: `@puppeteer/browsers`
+ * nests its installs as `<cache>/chrome-headless-shell/<platform>-<build>/…`,
+ * and on macOS the executable sits inside a further `.app` bundle. Spelling
+ * that shape out here would make the lookup a hostage to a layout the
+ * downloader is free to change; four levels of `readdir` over a directory that
+ * holds at most a couple of browsers costs nothing.
+ *
+ * Directory entries are visited newest-name-last-first so that a cache holding
+ * two versions yields the recent one — the one the last `setup-mermaid` asked
+ * for.
+ */
+function cachedBrowser(dir = browserCacheDir(), depth = 0) {
+  if (depth > 4) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null; // no cache directory yet
+  }
+  const sorted = entries.sort((a, b) => b.name.localeCompare(a.name));
+  for (const entry of sorted)
+    if (!entry.isDirectory() && EXE_NAMES.has(entry.name)) return path.join(dir, entry.name);
+  for (const entry of sorted) {
+    if (!entry.isDirectory()) continue;
+    const found = cachedBrowser(path.join(dir, entry.name), depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+let _browser; // memoized: the lookup stats a dozen paths, once per process
+
+/**
+ * Path of a usable browser, or null — in which case the caller keeps its text
+ * fallback and the CLI points at `lutrin setup-mermaid`.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.refresh] recompute instead of returning the memo —
+ *   `setup-mermaid` needs it after downloading a browser into the cache.
+ * @returns {{path:string,source:string}|null} `source` names where it came
+ *   from, so the CLI can say WHICH browser it is about to drive.
+ */
+export function findBrowser({ refresh = false } = {}) {
+  if (!refresh && _browser !== undefined) return _browser;
+
+  for (const [envVar, label] of [
+    ['LUTRIN_BROWSER', 'LUTRIN_BROWSER'],
+    ['PUPPETEER_EXECUTABLE_PATH', 'PUPPETEER_EXECUTABLE_PATH'],
+  ]) {
+    const value = process.env[envVar];
+    if (!value) continue;
+    // An explicit setting that does not resolve is a configuration error, not
+    // an absence: fall through to autodetection, but say so — a silent skip
+    // here is a support ticket that starts with "but I set the variable".
+    if (fs.existsSync(value)) return (_browser = { path: value, source: label });
+    console.warn(`lutrin: ${label}="${value}" does not exist — looking for a browser elsewhere`);
+  }
+
+  const cached = cachedBrowser();
+  if (cached) return (_browser = { path: cached, source: 'downloaded by lutrin setup-mermaid' });
+
+  for (const candidate of systemCandidates()) {
+    const resolved = path.isAbsolute(candidate)
+      ? fs.existsSync(candidate)
+        ? candidate
+        : null
+      : onPath(candidate);
+    if (resolved) return (_browser = { path: resolved, source: 'installed on the system' });
+  }
+
+  return (_browser = null);
+}
+
+/** Test seam: forget the memoized lookup. */
+export function resetBrowserCache() {
+  _browser = undefined;
+}
+
+/** The build `setup-mermaid` downloads when the machine has no browser at all.
+ *  chrome-headless-shell rather than a full Chrome: ~200 MB against ~350 MB,
+ *  measured, and it is the only mode we ever drive. Pinned, so that two
+ *  machines provisioned months apart render the same diagram identically. */
+export const HEADLESS_SHELL_VERSION = '150.0.7871.24';
+
+/**
+ * Downloads chrome-headless-shell into `~/.cache/lutrin/browser/` and returns
+ * its path.
+ *
+ * Only ever called by `lutrin setup-mermaid`, and only after the user has said
+ * yes: a compile never downloads a browser behind anyone's back — that silent
+ * ~1 GB is the whole reason mermaid rendering was broken by default in the
+ * first place.
+ *
+ * `@puppeteer/browsers` ships with puppeteer-core, so the downloader costs no
+ * extra dependency.
+ *
+ * @param {(text:string)=>void} [onProgress]
+ * @returns {Promise<string>} path of the executable
+ */
+export async function downloadHeadlessShell(onProgress = () => {}) {
+  const { install, resolveBuildId, detectBrowserPlatform, Browser } = await import(
+    '@puppeteer/browsers'
+  );
+  const cacheDir = browserCacheDir();
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const platform = detectBrowserPlatform();
+  if (!platform) throw new Error(`unsupported platform: ${process.platform}/${process.arch}`);
+
+  // The pin is a starting point, not a contract with the CDN: a build that has
+  // been rotated out resolves to the current one for that channel rather than
+  // failing the setup outright.
+  let buildId = HEADLESS_SHELL_VERSION;
+  try {
+    buildId = await resolveBuildId(Browser.CHROMEHEADLESSSHELL, platform, buildId);
+  } catch {
+    buildId = await resolveBuildId(Browser.CHROMEHEADLESSSHELL, platform, 'stable');
+  }
+
+  let lastPercent = -1;
+  const installed = await install({
+    browser: Browser.CHROMEHEADLESSSHELL,
+    buildId,
+    cacheDir,
+    downloadProgressCallback: (downloaded, total) => {
+      if (!total) return;
+      const percent = Math.floor((downloaded / total) * 100);
+      // every 5 %: enough to show life, few enough not to flood a CI log
+      if (percent >= lastPercent + 5) {
+        lastPercent = percent;
+        onProgress(`  downloading chrome-headless-shell ${buildId} — ${percent}%`);
+      }
+    },
+  });
+
+  resetBrowserCache();
+  return installed.executablePath;
+}