@casomoltd/tooling 0.28.0 → 0.29.0

package/README.md

@@ -28,6 +28,10 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `readability` | Measure reading difficulty of page content |
 | `screenshot` | Capture a dev server page via Playwright — an agent's visual feedback loop |
 | `build-report` | Compile a Typst client report to PDF with the house template |
+| `render-figures` | Pre-render a design spec's mermaid figures to static SVG |
+| `spec-check` | Check a design spec's anchors, contents, figures and numbering |
+| `check-private-refs` | In a public repo, refuse a private tracker link or a name listed in `check-private-refs.config.mjs` |
+| `check-personal-data` | Refuse an email, National Insurance number, UK mobile number, date of birth or locally denylisted name; per-repo allowances in `check-personal-data.config.mjs` |
 
 ## Install
 
@@ -39,7 +43,7 @@ npm i -D @casomoltd/tooling
 ```
 
 ```json
-"@casomoltd/tooling": "^0.20.0"
+"@casomoltd/tooling": "^0.28.0"
 ```
 
 The package is public, so installs need no token or `.npmrc`. The `files`
@@ -52,10 +56,10 @@ declared here — see [External prerequisites](#external-prerequisites).
 
 ## External prerequisites
 
-Two bins need something npm cannot sensibly deliver: `screenshot` needs
-a Chromium build, `build-report` needs the `typst` CLI and the IBM Plex
-fonts. **Neither is declared — not as a dependency, and not as an
-optional peer.** Both load their prerequisite lazily and fail with an
+Three bins need something npm cannot sensibly deliver: `screenshot` and
+`render-figures` need a Chromium build through Playwright, and
+`build-report` needs the `typst` CLI and the IBM Plex fonts. **None is
+declared — not as a dependency, and not as an optional peer.** Each loads its prerequisite lazily and fails with an
 install instruction when it is missing, so a consumer that never runs
 those bins carries nothing for them.
 
@@ -98,6 +102,44 @@ repo needs (lint, typecheck, spell, etc.).
 hooks (e.g. `./bin/check-version.sh`) because it can't resolve
 its own bin commands via `node_modules/.bin`.
 
+### A repo whose toolchain is not npm
+
+A Python, Go or C++ repo still gets the commit rules. It carries a **dev-only
+npm layer** that exists to host the hook and nothing else:
+
+```json
+{
+  "name": "<repo>-hooks",
+  "private": true,
+  "description": "Dev-only npm layer: wires the shared commit-msg gate into this repo. Not the project toolchain.",
+  "scripts": { "prepare": "husky" },
+  "devDependencies": {
+    "@casomoltd/tooling": "^0.28.0",
+    "@commitlint/cli": "^20.0.0",
+    "husky": "^9.1.7"
+  }
+}
+```
+
+Plus `commitlint.config.cjs` re-exporting the rules, and `.husky/commit-msg`.
+No `version`, because the repo versions itself with its own tool. Live
+examples: `kallim`, `paperpi`.
+
+**Do not wire `pre-commit` or `pre-push` from this package in such a repo.**
+Both run `npm run check`, and `check-gates` reads `package.json` and requires
+eight named npm scripts — a gate a non-npm repo cannot satisfy and should not
+fake. Write a `.husky/pre-push` that calls the real toolchain instead:
+
+```sh
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run pytest
+```
+
+**Why this is documented here.** Undocumented, each non-npm repo solves it
+alone and writes its own shell or Python copy of `no-ai-attribution`, and the
+copies drift — the length limits are what they lose first. One rule, one home.
+If a house gate will not run in your repo, wire the shared one or fix this
+package. Do not write a local equivalent.
+
 ## Markdown / skills lint
 
 `bin/skills-lint.config.mjs` is a stock remark config (`remark-frontmatter` +
@@ -168,6 +210,21 @@ Add these scripts to your `package.json`:
 Screenshots are saved to `.claude/screenshots/`. Set
 `SCREENSHOT_URL` to override the default `http://localhost:3000`.
 
+## Design specs
+
+`spec-check` reads one HTML design spec and reports its mechanical
+faults: an anchor resolving to nothing, a contents entry disagreeing
+with its heading, a figure without a number, an anchor or a caption, a
+figure wider than the card it sits in, a section number typed where the
+stylesheet generates one, and markup the artifact host refuses.
+
+`render-figures` rewrites a spec's mermaid figures as static SVG, so the
+page carries no runtime. Each figure keeps its source in an HTML comment
+above it, and a run reads those back, renders them and freezes the
+computed paint inline. It resolves Playwright from the working directory;
+set `RENDER_FIGURES_RESOLVE_FROM` to a project that has it when running
+from somewhere else.
+
 ## Client reports (Typst)
 
 `report/` ships the Casomo house style for client-facing PDF reports —
@@ -182,13 +239,13 @@ npx build-report report.typ --watch                # recompile on save
 npx build-report report.typ --open                 # open the PDF when done
 ```
 
-The compiled PDF is a build artefact, so it defaults to the same scratch
-resolution as the agent reports (see *Report output & `SCRATCH_DIR`*
-under Agents): `$SCRATCH_DIR/reports/<name>.pdf`, or
-`<repo-root>/scratch/reports/` when `SCRATCH_DIR` is unset — add
-`scratch/` to the consumer repo's `.gitignore` (this repo does). Pass
-`--out` only when the PDF is a deliverable the repo actually keeps
-(e.g. a site's `public/`).
+The compiled PDF is a build artefact and goes to
+`$SCRATCH_DIR/reports/<name>.pdf`, or `<repo-root>/scratch/reports/` when
+**`SCRATCH_DIR`** is unset — add `scratch/` to the consumer repo's
+`.gitignore` (this repo does). A PDF is a file to open rather than a page
+to publish, so it keeps a scratch location where the x-ray reports need
+none. Pass `--out` only when the PDF is a deliverable the repo actually
+keeps (e.g. a site's `public/`).
 
 A report imports the template and applies it as a show rule; everything
 after is the body. From a consumer repo the import goes through
@@ -323,7 +380,7 @@ decision table) that keeps these units composing without overlap.
 | `/casomoltd:typescript` | TypeScript data modelling and type design |
 | `/casomoltd:screenshot` | Capture and analyse a dev server page |
 | `/casomoltd:design-pass` | Map → review → refactor a package (drives `design-xray` + `code-review`) |
-| `/casomoltd:draft-design-spec` | Author a browser-reviewable HTML design spec from a brief and iterate on it before writing code (drives `design-xray`) |
+| `/casomoltd:draft-design-spec` | Author a reviewable HTML design spec from a brief, publish it as an Artifact, and iterate on it there before writing code (drives `design-xray`) |
 | `/casomoltd:page-design` | Structure a content/explainer page for trust — above-the-fold answer, disclosure, palette-only colour (rubric a page-design reviewer preloads) |
 | `/casomoltd:generate-report` | Scaffold a Typst client report from the house template, compile via `build-report`, verify the PDF |
 
@@ -409,14 +466,16 @@ where a justification would and otherwise survives an ordinary read-through. The
 `agents/*.md` changes to it. Not link validity (a markdown link linter), not the
 corpus reference graph (`docs-xray`), not prose voice (a content reviewer).
 
-**Report output & `SCRATCH_DIR`.** `design-xray` and `docs-xray` persist their
-report — the `.md` plus an `.html` rendered by `bin/render-report.mjs` — so it
-outlives the run and opens in a browser. Each writes to a gitignored
-`<repo-root>/scratch/<agent>/` by default. Set the optional **`SCRATCH_DIR`** env
-var to pool every report under one shared location instead (`$SCRATCH_DIR/<agent>/`)
-— e.g. a multi-repo workspace collecting reports in one place rather than scattering
-them per-repo. Publishing a report to a hosted claude.ai artifact is orchestrator-
-only and on explicit request; the agents never do it.
+**Report output.** `design-xray` and `docs-xray` write their report — the `.md`
+plus an `.html` rendered by `bin/render-report.mjs` — into a working directory
+and return both paths, and the caller publishes the `.html`. Each agent's
+*Persist the report* section is the spec for that hand-off.
+
+The rendered `.html` is built for that destination: `render-report.mjs` converts
+the markdown in node and ships **no mermaid runtime**, because the artifact host
+renders every `pre.mermaid` itself and a second runtime races it into black
+boxes. A page that builds its own body at load time has no diagram blocks in it
+when the host looks.
 
 ## Package distribution
 

package/bin/check-hooks.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# Is the house commit gate actually active in this repo?
+#
+# Answers one question, and answers it by *behaviour* rather than by presence.
+# A repo can have a commit-msg hook that enforces some of the rules, or an
+# older copy of them, and look wired while letting real violations through —
+# that is exactly what happened: three repos each grew a hand-written copy of
+# `no-ai-attribution`, two of them missing the length limits, and nothing
+# noticed for months because every one of them *had* a hook.
+#
+# So this feeds the hook messages that must fail and checks that they do.
+#
+#   check-hooks            # this repo
+#   check-hooks ~/dev/*    # every repo under a directory
+#
+# Exit 0 if every repo checked is gated, 1 otherwise. Language-neutral: sh and
+# git only, like check-linear and check-tags.
+set -e
+
+status=0
+
+check_one() {
+  repo=$1
+  name=$(basename "$repo")
+
+  if [ ! -d "$repo/.git" ]; then
+    return 0  # not a repo; silently skip so globs can be sloppy
+  fi
+
+  hooks=$(git -C "$repo" config --get core.hooksPath || echo ".git/hooks")
+  case "$hooks" in
+    /*) hook="$hooks/commit-msg" ;;
+    *)  hook="$repo/$hooks/commit-msg" ;;
+  esac
+
+  if [ ! -f "$hook" ]; then
+    printf '%-24s NOT GATED  (no commit-msg hook)\n' "$name"
+    status=1
+    return 0
+  fi
+
+  msg=$(mktemp)
+  failures=""
+
+  # Each probe is a message the house rules must reject. Keep the bodies
+  # single-line so a copy that only checks the header still fails the first.
+  probe() {
+    printf '%s' "$2" > "$msg"
+    if git -C "$repo" hook run --ignore-missing commit-msg -- "$msg" \
+        >/dev/null 2>&1; then
+      failures="$failures $1"
+    fi
+  }
+
+  probe attribution "Add a thing
+
+Co-authored-by: Claude <noreply@anthropic.com>
+"
+  probe header-length "Add a thing with a subject line that runs past the fifty character limit
+"
+  probe body-length "Add a thing
+
+This body line is deliberately longer than the seventy-two character limit.
+"
+
+  rm -f "$msg"
+
+  if [ -n "$failures" ]; then
+    printf '%-24s PARTIAL    (accepts:%s)\n' "$name" "$failures"
+    status=1
+  else
+    printf '%-24s gated\n' "$name"
+  fi
+}
+
+if [ $# -eq 0 ]; then
+  check_one "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+else
+  for arg in "$@"; do
+    check_one "$arg"
+  done
+fi
+
+exit $status

package/bin/check-personal-data.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Refuse to let a person's details reach a commit.
+ *
+ * A repo that works from real people's records keeps them in a working
+ * directory outside it, and they reach it the moment someone pastes a
+ * statement into a fixture or reuses a real figure as a "specimen". This
+ * finds what has a shape:
+ *
+ * - **Emails, National Insurance numbers, UK mobile numbers and dates of
+ *   birth** are detectable by shape, and these rules find them.
+ * - **Names are not.** No pattern separates a person from a cited author, so
+ *   names come from a local denylist that is itself never committed: a file
+ *   listing the people would be the leak it exists to prevent. Without the
+ *   file the other rules still run, and the summary says name checking is off.
+ *
+ * Deliberately configurable, because this file ships in a public package and
+ * cannot name anybody's domains or reference formats. A consuming repo adds
+ * its own in `check-personal-data.config.mjs`:
+ *
+ *   export default {
+ *     allowEmail: [/@example-org\.com$/i],   // addresses that are not people
+ *     rules: [                               // repo-specific identifiers
+ *       {name: "case reference", re: /\bCASE-\d{4,}\b/g,
+ *        allow: (m) => m === "CASE-0000"},
+ *     ],
+ *     denylist: ".personal-data-denylist",   // the default; gitignore it
+ *     allow: [/\.test\.mjs$/],               // paths exempted, with care
+ *   };
+ *
+ * Usage:
+ *   check-personal-data            # tracked and untracked-but-not-ignored
+ *   check-personal-data --staged   # staged only
+ */
+import {execFileSync} from "node:child_process";
+import {existsSync, readFileSync, realpathSync, statSync} from "node:fs";
+import {pathToFileURL} from "node:url";
+import {loadConfig} from "./utils.mjs";
+
+/** Addresses in every repo's own tooling that name no person. */
+const ALLOWED_EMAIL = [
+  /@example\.(com|org|net)$/i,
+  /@users\.noreply\.github\.com$/i,
+];
+
+/* Files whose content looks like data but never describes a person:
+ * lockfiles, generated bundles, fonts, images. */
+const SKIP_DIRS = new Set(["node_modules", ".next", "dist", "coverage", "out"]);
+const SKIP_EXTS = new Set([
+  "lock", "woff", "woff2", "ttf", "otf", "png", "jpg", "jpeg", "gif", "webp",
+  "ico", "pdf", "zip", "map",
+]);
+
+function skip(file) {
+  if (file.split("/").some((part) => SKIP_DIRS.has(part))) return true;
+  if (file.endsWith("package-lock.json")) return true;
+  const ext = file.slice(file.lastIndexOf(".") + 1).toLowerCase();
+  return SKIP_EXTS.has(ext);
+}
+
+/** The field names a data shape puts between a label and its value. */
+const FIELD_SUFFIX = /(?:value|val|text|node|display|content)$/;
+
+/** A key that names a birth. */
+const BIRTH_KEY = /(?:dob|dateofbirth|birthdate|born)$/;
+
+/** The constructor a source file writes a date with. `new Date(1983, 6, 14)`
+ *  matches neither the printed nor the ISO rule, and the words before it end
+ *  `newdate` rather than a field name, so both halves would be blind at once
+ *  without this. */
+const DATE_CALL = /(?:new\s*)?date\($/;
+
+/**
+ * Whether the words before a date name a birth.
+ *
+ * A rendered page puts label and value side by side, so the key is last. A
+ * data file nests: `{label: "Date of birth", value: {value: "..."}}` gives a
+ * lead-in ending `dateofbirthvaluevalue`. The suffixes come off one at a time
+ * rather than as a starred alternation, which backtracks super-linearly
+ * because `val` is a prefix of `value`; a bounded loop is linear.
+ */
+function namesABirth(lead) {
+  let rest = lead;
+  for (let depth = 0; depth < 4; depth += 1) {
+    if (BIRTH_KEY.test(rest)) return true;
+    const trimmed = rest.replace(FIELD_SUFFIX, "");
+    if (trimmed === rest) return false;
+    rest = trimmed;
+  }
+  return BIRTH_KEY.test(rest);
+}
+
+const NON_WORD = /[^a-z0-9]/gi;
+
+/** What precedes a date, as a reader sees it: tags dropped, a generous
+ *  window, because a label and its value are separated by a cell boundary
+ *  and whatever styling that cell carries. */
+const leadIn = (before) =>
+  before.replace(/<[^<>]*>/g, " ").slice(-120).replace(NON_WORD, "")
+    .toLowerCase();
+
+/** A real address ends in a letters-only top-level domain; without this a
+ *  package spec such as `postcss@8.4.31` reads as one. */
+const TLD = /\.[A-Za-z]{2,}$/;
+
+/** The identity rules every repo gets. */
+export function identityRules(allowEmail = []) {
+  const allowed = [...ALLOWED_EMAIL, ...allowEmail];
+  return [
+    {
+      name: "email address",
+      // Labels joined by dots, not one class containing the dot: letting `.`
+      // sit in the class too makes the parts overlap and backtrack.
+      re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+\b/g,
+      allow: (m) => allowed.some((a) => a.test(m)) || !TLD.test(m),
+    },
+    {
+      name: "National Insurance number",
+      re: /\b[A-CEGHJ-PR-TW-Z]{2}\s?\d{2}\s?\d{2}\s?\d{2}\s?[A-D]\b/g,
+    },
+    {
+      name: "UK mobile number",
+      re: /\b(?:\+44\s?7\d{3}|\(?07\d{3}\)?)\s?\d{3}\s?\d{3}\b/g,
+    },
+    {
+      name: "date of birth",
+      // Every ISO date, then the words before it decide: a bare date is a
+      // rule's date far more often than a person's.
+      re: /\b\d{4}[-/]\d{1,2}[-/]\d{1,2}\b/g,
+      // 1 January is the placeholder a redacted fixture writes; flagging it
+      // trains everyone to ignore the check.
+      allow: (m) => /[-/]0?1[-/]0?1$/.test(m),
+      context: (before) => namesABirth(leadIn(before)),
+    },
+    {
+      name: "date of birth",
+      // The printed form, "DD Month YYYY", which the ISO rule cannot see.
+      re: /\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+(?:19|20)\d{2}\b/g,
+      allow: (m) => /^0?1\s+January\s/.test(m),
+      context: (before) => namesABirth(leadIn(before)),
+    },
+    {
+      name: "date of birth",
+      // The constructed form. Month is zero-based, so the placeholder is
+      // month 0, day 1. The key is whatever the constant is called.
+      re: /\bnew\s+Date\(\s*(?:19|20)\d{2}\s*,\s*\d{1,2}\s*,\s*\d{1,2}\s*\)/g,
+      allow: (m) => /,\s*0\s*,\s*0?1\s*\)$/.test(m),
+      context: (before) => namesABirth(leadIn(before))
+        || BIRTH_KEY.test(leadIn(before).replace(DATE_CALL, "")),
+    },
+  ];
+}
+
+/** Every finding in one file's text, against the rules and the names. */
+export function findPersonalData(text, rules, names = []) {
+  const hits = [];
+  const lines = text.split("\n");
+  for (const rule of rules) {
+    for (const [i, line] of lines.entries()) {
+      for (const m of line.matchAll(rule.re)) {
+        if (rule.allow?.(m[0])) continue;
+        if (rule.context && !rule.context(line.slice(0, m.index))) continue;
+        hits.push({line: i + 1, rule: rule.name, text: m[0]});
+      }
+    }
+  }
+  for (const name of names) {
+    // No `g`: `.test()` on a global regex advances `lastIndex`, and a name
+    // on consecutive lines would be reported on every other one.
+    const re = new RegExp(
+      `\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+    for (const [i, line] of lines.entries()) {
+      if (re.test(line)) {
+        hits.push({line: i + 1, rule: "name on the local denylist", text: name});
+      }
+    }
+  }
+  return hits;
+}
+
+/* Tracked AND untracked-but-not-ignored: the moment this exists for is the
+ * first commit of a new directory, and a tracked-only listing is blind to
+ * exactly that. Ignored files are left out on purpose; they are the working
+ * directory, where a person's data is supposed to live. */
+function files(stagedOnly) {
+  const args = stagedOnly
+    ? ["diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+    : ["ls-files", "--cached", "--others", "--exclude-standard"];
+  return execFileSync("git", args, {encoding: "utf8"})
+    .split("\n").filter((f) => f && !skip(f) && existsSync(f)
+      && statSync(f).isFile());
+}
+
+function denied(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n")
+    .map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+}
+
+/** Every finding across the files, and every file that could not be read,
+ *  with the reason. `read` is the reader, so an unreadable file can be
+ *  tested without making one. */
+export function scan(fileList, read, rules, names) {
+  const hits = [];
+  const unread = [];
+  for (const file of fileList) {
+    let text;
+    try {
+      text = read(file);
+    } catch (error) {
+      unread.push({file, code: error?.code ?? String(error)});
+      continue;
+    }
+    for (const h of findPersonalData(text, rules, names)) hits.push({file, ...h});
+  }
+  return {hits, unread};
+}
+
+async function main() {
+  const mod = await loadConfig("check-personal-data.config.mjs");
+  // `loadConfig` returns the module, so the config is its default export.
+  const config = mod?.default ?? {};
+  const denylist = config.denylist ?? ".personal-data-denylist";
+  const rules = [...identityRules(config.allowEmail), ...(config.rules ?? [])];
+  const names = denied(denylist);
+  const allow = (config.allow ?? []).map((a) =>
+    a instanceof RegExp ? a : new RegExp(a));
+
+  const {hits, unread} = scan(
+    files(process.argv.includes("--staged"))
+      .filter((file) => !allow.some((a) => a.test(file))),
+    (file) => readFileSync(file, "utf8"), rules, names);
+
+  // A file this could not read is a file it did not check, so the run is
+  // incomplete rather than clean, whatever else it found.
+  for (const u of unread) console.error(`  ${u.file}: could not be read (${u.code})`);
+  if (unread.length && !hits.length) {
+    console.error(`\ncheck-personal-data: INCOMPLETE — ${unread.length} file(s) `
+      + "were not checked.\n");
+    process.exit(1);
+  }
+
+  if (hits.length) {
+    console.error("\nPersonal data must not be committed.\n");
+    for (const h of hits) console.error(`  ${h.file}:${h.line}  ${h.rule}: ${h.text}`);
+    console.error(
+      `\n${hits.length} finding(s). Move the data to a working directory `
+      + "outside every repository, or replace it with values that could not "
+      + "be anyone's.\n");
+    process.exit(1);
+  }
+
+  console.log(
+    "check-personal-data: clean"
+    + (names.length ? ` (${names.length} name(s) on the local denylist)`
+      : ` (no ${denylist}; name checking off)`)
+  );
+}
+
+/** True only when this file is the entry point. npm installs a bin as a
+ *  symlink, so compare the resolved path, or `main` never runs in a consumer. */
+const isEntryPoint = () => {
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+};
+
+if (isEntryPoint()) main();

package/bin/render-figures.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Re-render a spec's mermaid figures to static inline SVG.
+ *
+ * The spec embeds rendered SVG rather than a mermaid runtime, because the
+ * artifact viewer ships its own runtime that claims every `pre.mermaid` and
+ * renames the svg it produces. Mermaid scopes a diagram's fills to the svg's
+ * own id, so a rename leaves those rules matching nothing and every shape
+ * falls back to the default fill, which is black. Embedding removes both the
+ * race and the id dependency.
+ *
+ * Each figure keeps its source in an HTML comment directly above it. This
+ * reads those back, renders them, freezes the computed paint inline, and
+ * writes the file in place.
+ *
+ *   node bin/render-figures.mjs <spec.html>
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { FIGURE_WIDTH_BUDGET } from './utils.mjs';
+
+/** Playwright is a heavy prerequisite this package deliberately does not
+ *  declare, because a declared optional peer resolves into every consumer's
+ *  lockfile. So it is resolved from the calling project rather than from
+ *  here, and RENDER_FIGURES_RESOLVE_FROM names that project when the working
+ *  directory is not it. */
+const from = resolve(process.env.RENDER_FIGURES_RESOLVE_FROM || process.cwd());
+let chromium;
+try {
+  ({ chromium } = createRequire(`${from}/`)('playwright'));
+} catch {
+  throw new Error('playwright is not installed — add it as a devDependency'
+    + ' (npm i -D playwright && npx playwright install chromium) in the project'
+    + ` you are rendering from, or point RENDER_FIGURES_RESOLVE_FROM at one`
+    + ` that has it. Looked in ${from}.`);
+}
+
+/** The marker above each figure, as one producer: it is both searched for
+ *  and written back, so the two must be the same string. */
+const MARKER = '  <!-- figure source, regenerate with bin/render-figures.mjs:';
+const SOURCE = new RegExp(`${MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`
+  + '\n([\\s\\S]*?)\n  -->\n  <div class="figure-card">[\\s\\S]*?<\\/div>\n', 'g');
+
+/** Written even when they compute to `none`: an arrowhead that silently gains
+ *  a fill is the same defect as a box that silently loses one. */
+const PAINT = ['fill', 'stroke', 'stroke-width', 'stroke-dasharray', 'color'];
+
+const file = process.argv[2];
+if (!file) throw new Error('usage: render-figures.mjs <spec.html>');
+
+const html = readFileSync(file, 'utf8');
+// An HTML comment ends at the first `-->`, so a mermaid arrow written whole
+// would close the comment and truncate the source. The spec writes `- ->`
+// and this puts it back.
+const sources = [...html.matchAll(SOURCE)].map((m) => m[1].replaceAll('- -', '--'));
+// Counted against the figures rather than against zero: one malformed marker
+// leaves that figure holding a stale SVG while the run still reports success.
+const figures = [...html.matchAll(/<div\b[^>]*\bid="fig-\d+"/g)].length;
+if (sources.length !== figures) {
+  throw new Error(`${figures} figure(s) in ${file} but ${sources.length} source`
+    + ' comment(s); a figure marker is malformed or missing');
+}
+
+/** A multi-line node label is what overflows a box: mermaid sizes a
+ *  foreignObject from the first line and the rest spills below it. The rubric
+ *  already says keep labels short and put the detail in the legend (M10); this
+ *  is that rule where it can actually be measured. */
+for (const [i, src] of sources.entries()) {
+  const multi = [...src.matchAll(/\[".*?<br\s*\/?>.*?"\]/g)].length;
+  if (multi) {
+    console.warn(`figure ${i + 1}: ${multi} node label(s) span more than one`
+      + ' line and will overflow their box — shorten them, per diagram-rubric M10');
+  }
+}
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1400, height: 1200 } });
+// The font must be LOADED, not just named: mermaid measures every label to
+// size its box, so rendering against a fallback and publishing against IBM
+// Plex Sans puts wider text into boxes cut for narrower text. Every figure
+// overflows slightly, and it looks like a mermaid bug rather than a missing
+// stylesheet.
+const FONT = 'https://fonts.googleapis.com/css2?family=IBM+Plex+Sans'
+  + ':ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap';
+const MERMAID = 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js';
+const STACK = '"IBM Plex Sans", ui-sans-serif, system-ui, sans-serif';
+await page.setContent(`<!doctype html><html><head>
+  <link rel="stylesheet" href="${FONT}">
+  <style>body { font-family: ${STACK}; }</style>
+  <script src="${MERMAID}"><\/script>
+  </head><body>${sources.map((s) => {
+    const escaped = s.replaceAll('&', '&amp;').replaceAll('<', '&lt;');
+    return `<pre class="m">${escaped}</pre>`;
+  }).join('')}</body></html>`);
+await page.waitForFunction(() => typeof window.mermaid !== 'undefined');
+await page.evaluate(() => document.fonts.load('600 15px "IBM Plex Sans"')
+  .then(() => document.fonts.ready));
+
+const rendered = await page.evaluate(async (paint) => {
+  window.mermaid.initialize({
+    startOnLoad: false, theme: 'neutral', securityLevel: 'loose',
+    themeVariables: {
+      fontSize: '15px',
+      fontFamily: '"IBM Plex Sans", ui-sans-serif, system-ui, sans-serif',
+      textColor: '#1f2530', primaryTextColor: '#1f2530', nodeTextColor: '#1f2530',
+      titleColor: '#1f2530', clusterBkg: '#f7f8fa', clusterBorder: '#b9c0cb',
+      lineColor: '#5b6472',
+    },
+    flowchart: { htmlLabels: true, useMaxWidth: false },
+    class: { useMaxWidth: false },
+  });
+  const out = [];
+  const nodes = [...document.querySelectorAll('pre.m')];
+  for (const [i, el] of nodes.entries()) {
+    const { svg } = await window.mermaid.render(`fig-svg-${i}`, el.textContent);
+    const holder = document.createElement('div');
+    holder.innerHTML = svg;
+    document.body.appendChild(holder);
+    const node = holder.querySelector('svg');
+    node.querySelectorAll('*').forEach((child) => {
+      const cs = getComputedStyle(child);
+      paint.forEach((prop) => {
+        const v = cs.getPropertyValue(prop);
+        if (v) child.style.setProperty(prop, v);
+      });
+    });
+    // Mermaid emits only the deprecated xlink:href on a click-through link.
+    // Every current browser still honours it, but SVG2 names the attribute
+    // `href`, so write both and let the newer one win.
+    node.querySelectorAll('a[*|href]').forEach((a) => {
+      const x = a.getAttributeNS('http://www.w3.org/1999/xlink', 'href');
+      if (x && !a.getAttribute('href')) a.setAttribute('href', x);
+    });
+    node.setAttribute('style', 'max-width:100%;height:auto');
+    out.push({ svg: node.outerHTML, viewBox: node.getAttribute('viewBox') });
+  }
+  return out;
+}, PAINT);
+await browser.close();
+
+let n = 0;
+const next = html.replace(SOURCE, (whole, src) => {
+  const { svg } = rendered[n++];
+  return `${MARKER}\n${src}\n  -->\n  <div class="figure-card">${svg}</div>\n`;
+});
+writeFileSync(file, next);
+
+// Producing a measurable figure is this script's job, so one it cannot
+// measure is a failure rather than a figure reported as zero pixels wide.
+rendered.forEach(({ viewBox }, i) => {
+  const parsed = /^[-\d.]+\s+[-\d.]+\s+([\d.]+)/.exec(viewBox || '');
+  if (!parsed) throw new Error(`figure ${i + 1} rendered without a usable viewBox`);
+  const w = Math.round(Number(parsed[1]));
+  const over = w > FIGURE_WIDTH_BUDGET
+    ? `  ** OVER the ${FIGURE_WIDTH_BUDGET}px budget **` : '';
+  console.log(`figure ${i + 1}: ${w}px${over}`);
+});
+console.log(`wrote ${n} figures to ${file}`);