ultra11y 3.0.0 → 3.1.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "3.0.0";
+const ULTRA11Y_PLUGIN_VERSION = "3.1.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -125,7 +125,7 @@ claude mcp add ultra11y -- npx -y ultra11y mcp
 **As a GitHub Action** — audits the PR diff and, optionally, the served pages:
 
 ```yaml
-- uses: maxgfr/ultra11y@v2
+- uses: maxgfr/ultra11y@v3
   with: { since: auto, standard: rgaa, fail-on: blocking }
 ```
 
@@ -429,7 +429,8 @@ Releases are cut automatically by **semantic-release** on push to `main` (GitHub
 npm publish via OIDC trusted publishing, plus the moving `v2` major tag). The version bump is
 decided by **Conventional Commits**: a commit whose subject carries no `feat:`/`fix:` prefix
 is analysed as *no release*, so a change that must ship needs at least one conventional commit
-in the range — otherwise `@v2` and npm keep serving the previous version while `main` moves on.
+in the range — otherwise the major alias and npm keep serving the previous version while `main`
+moves on.
 
 ## Data & licensing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/build-extension-icons.mjs

@@ -7,15 +7,22 @@
 // script produces — the same reproducibility contract the engine bundle is held to.
 //
 // The mark is an eye (the action's own branding icon), drawn as a filled lens with a pupil on
-// the purple the action already declares. Written with a hand-rolled PNG encoder because the
-// repo has no image dependency and is not about to grow one for four small files.
+// the purple the action already declares. The PNG encoder is the engine's own
+// (`src/pixel.ts`), imported through Node's type-stripping — the repo has no image dependency
+// and is not about to grow one for four small files.
+//
+// That import runs both ways: because these four icons are committed, `--check` re-encodes
+// them and proves `encodePng` still emits the exact bytes it emitted when they were drawn.
+// A decode/encode round-trip could only prove the pair is self-consistent; this proves the
+// encoder is PNG-correct against files a browser accepts. Keep `src/pixel.ts` a leaf (one
+// runtime import, `node:zlib`) or this import stops resolving.
 //
 //   node scripts/build-extension-icons.mjs           # write
 //   node scripts/build-extension-icons.mjs --check   # fail if the committed files differ
-import { deflateSync } from "node:zlib";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { encodePng } from "../src/pixel.ts";
 
 const OUT = join(dirname(fileURLToPath(import.meta.url)), "..", "extension", "icons");
 const SIZES = [16, 32, 48, 128];
@@ -24,45 +31,6 @@ const SIZES = [16, 32, 48, 128];
 const BG = [107, 70, 193]; // #6b46c1
 const FG = [255, 255, 255];
 
-function crc32(buf) {
-  let c = ~0;
-  for (const b of buf) {
-    c ^= b;
-    for (let i = 0; i < 8; i++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
-  }
-  return ~c >>> 0;
-}
-
-function chunk(type, data) {
-  const len = Buffer.alloc(4);
-  len.writeUInt32BE(data.length);
-  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(body));
-  return Buffer.concat([len, body, crc]);
-}
-
-/** An RGBA pixel buffer → a PNG. Colour type 6, 8-bit, one filter byte per row. */
-function png(size, rgba) {
-  const raw = Buffer.alloc(size * (size * 4 + 1));
-  for (let y = 0; y < size; y++) {
-    raw[y * (size * 4 + 1)] = 0; // filter: none — the images are tiny, filtering buys nothing
-    rgba.copy(raw, y * (size * 4 + 1) + 1, y * size * 4, (y + 1) * size * 4);
-  }
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(size, 0);
-  ihdr.writeUInt32BE(size, 4);
-  ihdr[8] = 8; // bit depth
-  ihdr[9] = 6; // RGBA
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    chunk("IHDR", ihdr),
-    // level 9 so the bytes are a function of the pixels alone, not of zlib's default tuning.
-    chunk("IDAT", deflateSync(raw, { level: 9 })),
-    chunk("IEND", Buffer.alloc(0)),
-  ]);
-}
-
 /** The eye mark, supersampled 4× so the curves do not alias at 16px. */
 function draw(size) {
   const S = 4;
@@ -118,7 +86,7 @@ mkdirSync(OUT, { recursive: true });
 let stale = [];
 for (const size of SIZES) {
   const file = join(OUT, `icon-${size}.png`);
-  const bytes = png(size, draw(size));
+  const bytes = encodePng({ width: size, height: size, data: draw(size) });
   if (check) {
     let current = null;
     try {

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "3.0.0";
+var VERSION = "3.1.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -39131,7 +39131,7 @@ var colorsRules = [contrastLiteral];
 import { readFileSync as readFileSync12 } from "fs";
 
 // src/pixel.ts
-import { inflateSync } from "zlib";
+import { deflateSync, inflateSync } from "zlib";
 var SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
 function paeth(a, b, c2) {
   const p = a + b - c2;

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 3.0.0
+  version: 3.1.0
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "3.0.0";
+var VERSION = "3.1.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -39131,7 +39131,7 @@ var colorsRules = [contrastLiteral];
 import { readFileSync as readFileSync12 } from "fs";
 
 // src/pixel.ts
-import { inflateSync } from "zlib";
+import { deflateSync, inflateSync } from "zlib";
 var SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
 function paeth(a, b, c2) {
   const p = a + b - c2;

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 3.0.0
+  version: 3.1.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/ci.md

@@ -15,7 +15,7 @@ permissions:
 steps:
   - uses: actions/checkout@v4
     with: { fetch-depth: 0 }        # the diff gate needs the base ref
-  - uses: maxgfr/ultra11y@v2      # or pin the exact version, as `init --ci` does
+  - uses: maxgfr/ultra11y@v3      # or pin the exact version, as `init --ci` does
     with:
       since: auto                   # the PR's base branch
       standard: rgaa
@@ -27,7 +27,7 @@ steps:
 Page by page, with a real browser, in the same step:
 
 ```yaml
-  - uses: maxgfr/ultra11y@v2
+  - uses: maxgfr/ultra11y@v3
     with:
       standard: rgaa
       start: npm run start
@@ -37,9 +37,11 @@ Page by page, with a real browser, in the same step:
 ```
 
 `ultra11y init --ci` writes a workflow using it, **pinned to the exact engine version that
-generated the file** (`@v<that version>`) so a CI run stays reproducible. `@v2` is a moving major alias
-the release workflow keeps pointing at the latest release, for teams who would rather take
-fixes automatically. Never `@main`: it would change under you without a version to blame.
+generated the file** (`@v<that version>`) so a CI run stays reproducible. `@v<major>` — `@v3`
+today — is a moving alias the release workflow repoints at each release, for teams who would
+rather take fixes automatically. It moves **within** a major only: when a breaking change cuts
+the next one, the old alias freezes where it is, so a pipeline pinned to it keeps working and
+stops receiving features. Never `@main`: it would change under you with no version to blame.
 
 **Order matters, and it is deliberate**: the audit runs first, then SARIF, annotations, the
 summary, the comment and the report — and the **gate runs last**. A failing audit has
@@ -64,7 +66,7 @@ partial by construction. `adjudicate` closes that — opt-in, in two modes.
 env:
   ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # the job's env, never an input
 steps:
-  - uses: maxgfr/ultra11y@v2
+  - uses: maxgfr/ultra11y@v3
     with:
       standard: rgaa
       adjudicate: api          # or `agent`
@@ -233,7 +235,7 @@ The action audits the **code** and, when you point it at a served app, the **pag
 list can come from three places, and none of them has to be written by hand:
 
 ```yaml
-- uses: maxgfr/ultra11y@v2
+- uses: maxgfr/ultra11y@v3
   with:
     standard: rgaa
     start: npm run start
@@ -284,9 +286,9 @@ one job — the code diff, then the served pages — died on a `409 Conflict`, w
 written and never uploaded. Pass `artifact-name` on each invocation:
 
 ```yaml
-- uses: maxgfr/ultra11y@v2
+- uses: maxgfr/ultra11y@v3
   with: { since: auto, artifact-name: a11y-code }
-- uses: maxgfr/ultra11y@v2
+- uses: maxgfr/ultra11y@v3
   with: { crawl: http://localhost:3000, artifact-name: a11y-pages }
 ```
 

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "3.0.0";
+var VERSION = "3.1.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -39131,7 +39131,7 @@ var colorsRules = [contrastLiteral];
 import { readFileSync as readFileSync12 } from "fs";
 
 // src/pixel.ts
-import { inflateSync } from "zlib";
+import { deflateSync, inflateSync } from "zlib";
 var SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
 function paeth(a, b, c2) {
   const p = a + b - c2;

package/src/evidence.ts

@@ -0,0 +1,499 @@
+// EVIDENCE TIER — a non-conformity, shown.
+//
+// A rendered finding cites `.ultra11y/pages/accueil/dom.html:412` (`div.card`), and under the
+// rules that anchor at the document element it cites `dom.html:2` — the same line, for
+// hundreds of findings at once. `selectorHint` is doing all the locating work and it is lossy
+// by construction (src/rules/rule.ts `selectorOf`: first class only, href truncated). For a
+// reviewer who did not write the page, that is not a location. A picture is.
+//
+// Everything this needs is already on disk and already verified:
+//   • `screen.png`  — the page as the browser painted it
+//   • `boxes.json`  — every element's rect, joined to the DOM by document-order ordinal
+//   • `Finding.sourceStart` — the byte offset of the anchoring element in that same dom.html
+// So the join is `sourceStart -> ordinal -> box -> pixels`, with no new capture, no new
+// dependency, and no new field on Finding.
+//
+// WHY DERIVE, NOT STAMP. A box could have been written onto Finding when the rule fired.
+// It is not, deliberately: a pixel rectangle is a property of an IMAGE, not of a finding. A
+// stamped box survives into the audit JSON and goes silently wrong the moment that JSON is
+// re-rendered against a re-captured page — and silently wrong is the one failure mode this
+// engine refuses. Deriving re-runs the same verified join every time, and refuses wholesale
+// when it does not hold, exactly as `align()` already does for styles and boxes.
+//
+// WHAT IT REFUSES. Most findings get no crop, and each reason is recorded and reported rather
+// than left as a gap: a source finding has no pixels, a component capture was rendered by
+// jsdom which paints nothing, a page-scope rule points at `<html>` and would "highlight" the
+// whole screenshot, and — the one that surprises people — an element below the fold is simply
+// not in the image, because every producer captures the VIEWPORT on purpose so the screenshot
+// shares boxes.json's coordinate system (src/integrations/playwright.ts). None of these is a
+// bug to work around; each is a fact to state.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { findingId } from "./baseline.js";
+import { parseHtml } from "./parse/html.js";
+import { cropImage, decodePng, encodePng, fillRect, strokeRect } from "./pixel.js";
+import { PAGES_DIR, alignedBoxes, isSnapshotDom, snapshotDir, validateSnapshotMeta } from "./snapshot.js";
+import type { Image, Raster, Rect } from "./pixel.js";
+import type { SnapshotMeta, SnapshotViewport } from "./snapshot.js";
+import type { AuditResult, BoxDigest, BoxEntry, Finding, Lang } from "./types.js";
+
+/** Why a finding got no picture. Every one of these is REPORTED, never swallowed: a reader
+ *  who sees fewer images than non-conformities must be told which, and why. */
+export type EvidenceSkip =
+  | "no-snapshot" // not raised on a page snapshot's dom.html (source finding, component capture)
+  | "no-screenshot" // the producer captured no image for this page
+  | "unreadable-image" // screen.png is not 8-bit truecolour, or is corrupt
+  | "no-boxes" // no boxes.json, or it did not verify against this dom.html
+  | "truncated" // the collector hit its element cap; this element has no box
+  | "no-offsets" // the finding carries no sourceStart (cannot be joined)
+  | "unjoinable" // sourceStart matches no element in dom.html
+  | "page-scope" // anchored at the document element: the page screenshot IS the illustration
+  | "zero-area" // the element has no painted box (display:contents, empty inline)
+  | "below-the-fold" // outside a viewport-only capture
+  | "unknown-scale" // image-pixels-per-CSS-pixel is indeterminate
+  | "capped"; // de-duplicated away by the caps below
+
+export interface EvidenceGeometry {
+  /** Context kept around the element, in CSS pixels. */
+  pad: number;
+  minWidth: number;
+  minHeight: number;
+  maxWidth: number;
+  maxHeight: number;
+}
+
+// The MINIMUM is the load-bearing number. A `rendered-link-colour-only` box is a 40×18 inline
+// link; cropped tight it is an unreadable smear, and the whole question that rule asks —
+// "is this distinguishable from the running text around it?" — is a question about the
+// surroundings. So the crop is padded out to something a human can judge.
+export const DEFAULT_GEOMETRY: EvidenceGeometry = { pad: 24, minWidth: 320, minHeight: 120, maxWidth: 960, maxHeight: 540 };
+
+/** De-duplication. Issue #16's real audit holds 472 findings of ONE rule across 38 pages for
+ *  7 distinct selectors: one image per occurrence would be 472 pictures of the same defect.
+ *  One per (page, rule, selector), then hard caps — and the report says what it did not draw. */
+export const DEFAULT_CAPS = { perRule: 6, perPage: 12, total: 200 };
+
+export interface PageEvidenceContext {
+  pageId: string;
+  img: Image;
+  /** Image pixels per CSS pixel. Derived, never assumed — see `resolveScale`. */
+  scale: number;
+  viewport: SnapshotViewport;
+  /** `Finding.sourceStart` → document-order ordinal, the key `boxes.json` is joined on. */
+  ordinalOf: Map<number, number>;
+  boxes: Map<number, BoxEntry>;
+  truncated: boolean;
+}
+
+export interface EvidenceCrop {
+  findingId: string;
+  page: string;
+  ruleId: string;
+  criteriaId: string;
+  /** Path relative to the output directory, for a Markdown or HTML `src`. */
+  href: string;
+  /** Absolute path on disk. */
+  path: string;
+  width: number;
+  height: number;
+  box: BoxEntry;
+  scale: number;
+  /** The element ran past the capture edge: what is drawn is part of it, not all of it. */
+  clipped: boolean;
+  alt: Record<Lang, string>;
+}
+
+export interface EvidencePageTally {
+  located: number;
+  imaged: number;
+  skipped: Partial<Record<EvidenceSkip, number>>;
+}
+
+export interface EvidenceManifest {
+  crops: Map<string, EvidenceCrop>;
+  skipped: Map<string, EvidenceSkip>;
+  perPage: Map<string, EvidencePageTally>;
+  totals: EvidencePageTally;
+}
+
+export interface EvidenceOptions {
+  /** Where `assets/<page-id>/` is written. */
+  outDir: string;
+  /** Repository root holding `.ultra11y/pages`. Defaults to the process cwd. */
+  root?: string;
+  caps?: Partial<typeof DEFAULT_CAPS>;
+  geometry?: Partial<EvidenceGeometry>;
+}
+
+// The ring. Red alone would encode the meaning by colour, which is a 1.4.1 failure — and this
+// tool exists to find those. So the mark carries three independent channels: a light halo (so
+// it survives a dark page), a solid ring, and corner brackets whose SHAPE says "here" with no
+// hue at all. A dashed inner line adds texture for a monochrome print.
+const HALO = { r: 255, g: 255, b: 255, a: 0.92 };
+const MARK = { r: 179, g: 38, b: 30, a: 1 }; // #b3261e — the NC colour the reports already use
+const RING = 3;
+
+/** The page id of a snapshot dom.html path, or null when it is not one. */
+export function pageIdOfSnapshot(file: string): string | null {
+  if (!isSnapshotDom(file)) return null;
+  const posix = file.split("\\").join("/");
+  const at = posix.lastIndexOf(`${PAGES_DIR}/`);
+  if (at < 0) return null;
+  const rest = posix.slice(at + PAGES_DIR.length + 1);
+  const id = rest.slice(0, rest.indexOf("/"));
+  return id || null;
+}
+
+function readJson<T>(file: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Image pixels per CSS pixel.
+ *
+ *  Nothing records `devicePixelRatio`, so it is derived from the image against the viewport
+ *  the collector recorded. When that is unusable, the `<html>` box is the fallback — it is by
+ *  definition the full viewport width. When BOTH are unusable the answer is genuinely unknown,
+ *  and the honest result is no crop: a guessed scale of 1 on a 2× capture rings the wrong half
+ *  of the page, which is worse than no picture. */
+function resolveScale(img: Image, viewport: SnapshotViewport | undefined, boxes: Map<number, BoxEntry>): number | null {
+  const candidates = [viewport?.width, boxes.get(0)?.w];
+  for (const w of candidates) {
+    if (!w || w <= 0) continue;
+    const scale = img.width / w;
+    // A capture is 1×, 2× or 3×. Anything outside that band means the image and the boxes do
+    // not describe the same render, and pretending otherwise would misplace every ring.
+    if (scale >= 0.5 && scale <= 4) return scale;
+  }
+  return null;
+}
+
+/** Open a page snapshot's evidence, or say why it has none. Reads meta.json, dom.html,
+ *  boxes.json and screen.png ONLY — styles.json and css.json can be megabytes and answer
+ *  nothing here. */
+export function loadPageEvidence(root: string, pageId: string): PageEvidenceContext | { skip: EvidenceSkip } {
+  const dir = snapshotDir(root, pageId);
+  const domFile = join(dir, "dom.html");
+  const shotFile = join(dir, "screen.png");
+  if (!existsSync(domFile)) return { skip: "no-snapshot" };
+  if (!existsSync(shotFile)) return { skip: "no-screenshot" };
+
+  let dom: string;
+  let shot: Buffer;
+  try {
+    dom = readFileSync(domFile, "utf8");
+    shot = readFileSync(shotFile);
+  } catch {
+    return { skip: "no-snapshot" };
+  }
+
+  const img = decodePng(shot);
+  if (!img) return { skip: "unreadable-image" };
+
+  const digest = readJson<BoxDigest>(join(dir, "boxes.json"));
+  if (!digest) return { skip: "no-boxes" };
+  const doc = parseHtml(dom, domFile);
+  const boxes = alignedBoxes(dom, digest, doc);
+  if (!boxes) return { skip: "no-boxes" };
+
+  const scale = resolveScale(img, metaOf(dir)?.viewport, boxes);
+  if (scale === null) return { skip: "unknown-scale" };
+
+  const ordinalOf = new Map<number, number>();
+  for (let i = 0; i < doc.elements.length; i++) {
+    const start = doc.elements[i]?.start;
+    if (start !== undefined && !ordinalOf.has(start)) ordinalOf.set(start, i);
+  }
+
+  const viewport: SnapshotViewport = metaOf(dir)?.viewport ?? { width: Math.round(img.width / scale), height: Math.round(img.height / scale) };
+  return { pageId, img, scale, viewport, ordinalOf, boxes, truncated: Boolean(digest.truncated) };
+}
+
+function metaOf(dir: string): SnapshotMeta | undefined {
+  const raw = readJson<unknown>(join(dir, "meta.json"));
+  if (raw === undefined) return undefined;
+  const v = validateSnapshotMeta(raw);
+  return v.ok && v.meta ? v.meta : undefined;
+}
+
+/** The crop rect around an element box, in IMAGE pixels: padded for context, grown to the
+ *  legible minimum, capped at the maximum, and slid back inside the image rather than
+ *  hanging off it. */
+function cropRect(box: BoxEntry, g: EvidenceGeometry, scale: number, img: Image): Rect {
+  const bx = box.x * scale;
+  const by = box.y * scale;
+  const bw = box.w * scale;
+  const bh = box.h * scale;
+  const w = Math.min(Math.max(bw + g.pad * 2 * scale, g.minWidth * scale), g.maxWidth * scale, img.width);
+  const h = Math.min(Math.max(bh + g.pad * 2 * scale, g.minHeight * scale), g.maxHeight * scale, img.height);
+  let x = bx + bw / 2 - w / 2;
+  let y = by + bh / 2 - h / 2;
+  x = Math.max(0, Math.min(x, img.width - w));
+  y = Math.max(0, Math.min(y, img.height - h));
+  return { x, y, w, h };
+}
+
+/** Ring the element inside its crop. Three channels, none of them colour alone. */
+function annotate(raster: Raster, target: Rect): void {
+  strokeRect(raster, { x: target.x - RING, y: target.y - RING, w: target.w + RING * 2, h: target.h + RING * 2 }, HALO, RING);
+  strokeRect(raster, target, MARK, RING);
+  strokeRect(raster, { x: target.x + RING, y: target.y + RING, w: target.w - RING * 2, h: target.h - RING * 2 }, HALO, 1, 6);
+
+  // Corner brackets: a shape cue that survives greyscale, a colour-blind reader and a print.
+  const arm = Math.max(6, Math.min(18, Math.round(Math.min(target.w, target.h) / 3)));
+  const t = RING;
+  const x0 = target.x - RING;
+  const y0 = target.y - RING;
+  const x1 = target.x + target.w + RING;
+  const y1 = target.y + target.h + RING;
+  for (const [cx, cy, dx, dy] of [
+    [x0, y0, 1, 1],
+    [x1, y0, -1, 1],
+    [x0, y1, 1, -1],
+    [x1, y1, -1, -1],
+  ] as const) {
+    fillRect(raster, { x: dx > 0 ? cx : cx - arm, y: dy > 0 ? cy - t : cy, w: arm, h: t }, MARK);
+    fillRect(raster, { x: dx > 0 ? cx - t : cx, y: dy > 0 ? cy : cy - arm, w: t, h: arm }, MARK);
+  }
+}
+
+export interface CroppedFinding {
+  png: Buffer;
+  width: number;
+  height: number;
+  box: BoxEntry;
+  scale: number;
+  clipped: boolean;
+}
+
+/** One finding → one annotated PNG, or the reason there is none. */
+export function cropFinding(ctx: PageEvidenceContext, f: Finding, geometry?: Partial<EvidenceGeometry>): CroppedFinding | { skip: EvidenceSkip } {
+  const g = { ...DEFAULT_GEOMETRY, ...geometry };
+  if (f.sourceStart === undefined) return { skip: "no-offsets" };
+  const ordinal = ctx.ordinalOf.get(f.sourceStart);
+  if (ordinal === undefined) return { skip: "unjoinable" };
+  // The document element: its box IS the page, so ringing it would outline the screenshot.
+  // The page's own screenshot already illustrates that, and the sheet already shows it.
+  if (ordinal === 0) return { skip: "page-scope" };
+  const box = ctx.boxes.get(ordinal);
+  if (!box) return { skip: ctx.truncated ? "truncated" : "no-boxes" };
+  if (box.w <= 0 || box.h <= 0) return { skip: "zero-area" };
+  const vpArea = ctx.viewport.width * ctx.viewport.height;
+  if (vpArea > 0 && (box.w * box.h) / vpArea >= 0.7) return { skip: "page-scope" };
+
+  // Viewport-only captures, on every producer, on purpose: the screenshot shares boxes.json's
+  // coordinate system. An element mostly below the fold is not in the image to be drawn.
+  const visibleTop = Math.max(0, box.y * ctx.scale);
+  const visibleBottom = Math.min(ctx.img.height, (box.y + box.h) * ctx.scale);
+  const visibleFraction = box.h > 0 ? (visibleBottom - visibleTop) / (box.h * ctx.scale) : 0;
+  if (visibleFraction < 0.5) return { skip: "below-the-fold" };
+
+  const rect = cropRect(box, g, ctx.scale, ctx.img);
+  const crop = cropImage(ctx.img, rect);
+  if (!crop) return { skip: "below-the-fold" };
+
+  annotate(crop.raster, {
+    x: box.x * ctx.scale - crop.rect.x,
+    y: box.y * ctx.scale - crop.rect.y,
+    w: box.w * ctx.scale,
+    h: box.h * ctx.scale,
+  });
+
+  return {
+    png: encodePng(crop.raster),
+    width: crop.raster.width,
+    height: crop.raster.height,
+    box,
+    scale: ctx.scale,
+    clipped: visibleFraction < 1,
+  };
+}
+
+// ---- prose -------------------------------------------------------------------------------
+// Every refusal has a sentence, in both languages. A missing image with no explanation reads
+// as "the tool found nothing here", which is the opposite of what happened.
+
+const S: Record<Lang, { alt: (sel: string, page: string) => string; notImaged: (n: number) => string; reasons: Record<EvidenceSkip, string> }> = {
+  fr: {
+    // No `N.N —` sequence: src/check.ts scans the WHOLE document for criterion mentions.
+    alt: (sel, page) => `Capture recadrée de l'élément ${sel} sur la page ${page}, entouré d'un cadre`,
+    notImaged: (n) => `${n} occurrence(s) ne sont pas illustrées :`,
+    reasons: {
+      "no-snapshot": "constat levé sur le code source, pas sur une page capturée — il n'y a pas de pixels à montrer",
+      "no-screenshot": "le producteur n'a pas fourni de capture pour cette page, donc le niveau pixel est inactif ici",
+      "unreadable-image": "la capture n'est pas décodable (le moteur lit le truecolour 8 bits uniquement) — mieux vaut aucune image qu'une fausse",
+      "no-boxes":
+        "les positions d'éléments ne se vérifient pas contre le DOM sérialisé, elles ont donc été refusées en bloc plutôt que d'encadrer le mauvais élément",
+      truncated: "la page dépasse la limite de collecte : aucune position n'a été enregistrée pour cet élément",
+      "no-offsets": "le constat ne porte pas d'ancrage dans la source, il ne peut pas être joint à une position",
+      unjoinable: "l'ancrage du constat ne correspond à aucun élément du DOM sérialisé",
+      "page-scope": "le constat porte sur la page entière — la capture de page ci-dessus est l'illustration",
+      "zero-area": "l'élément n'occupe aucune surface peinte",
+      "below-the-fold": "l'élément est hors de la capture (la capture couvre la fenêtre, pas la page entière) — sa référence fichier:ligne reste valable",
+      "unknown-scale": "le rapport pixels/CSS est indéterminé pour cette page ; un rapport deviné encadrerait le mauvais endroit",
+      capped: "occurrences regroupées : une illustration par élément distinct, dans la limite fixée",
+    },
+  },
+  en: {
+    alt: (sel, page) => `Cropped screenshot of the ${sel} element on the ${page} page, outlined`,
+    notImaged: (n) => `${n} occurrence(s) are not illustrated:`,
+    reasons: {
+      "no-snapshot": "raised on source code, not on a captured page — there are no pixels to show",
+      "no-screenshot": "the producer supplied no screenshot for this page, so the pixel tier is inactive here",
+      "unreadable-image": "the screenshot does not decode (the engine reads 8-bit truecolour only) — no image beats a wrong one",
+      "no-boxes": "the element positions do not verify against the serialized DOM, so they were refused wholesale rather than outlining the wrong element",
+      truncated: "the page exceeded the collection cap: no position was recorded for this element",
+      "no-offsets": "the finding carries no source anchor, so it cannot be joined to a position",
+      unjoinable: "the finding's anchor matches no element in the serialized DOM",
+      "page-scope": "the finding is about the whole page — the page screenshot above is the illustration",
+      "zero-area": "the element paints no box",
+      "below-the-fold": "the element sits outside the capture (the screenshot covers the viewport, not the whole page) — its file:line reference still holds",
+      "unknown-scale": "the image-pixel to CSS-pixel ratio is indeterminate for this page; a guessed ratio would outline the wrong place",
+      capped: "occurrences grouped: one illustration per distinct element, up to the cap",
+    },
+  },
+};
+
+/** What the report says about what it did NOT draw — per page, or overall when `pageId` is
+ *  null. Empty when everything located was imaged. */
+export function evidenceNotice(m: EvidenceManifest, pageId: string | null, lang: Lang): string[] {
+  const t = pageId === null ? m.totals : m.perPage.get(pageId);
+  if (!t) return [];
+  const missing = t.located - t.imaged;
+  if (missing <= 0) return [];
+  const s = S[lang];
+  const out = [s.notImaged(missing)];
+  for (const [reason, n] of Object.entries(t.skipped).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
+    if (!n) continue;
+    out.push(`- ${n} — ${s.reasons[reason as EvidenceSkip]}`);
+  }
+  return out;
+}
+
+// ---- the run -----------------------------------------------------------------------------
+
+function bump(t: EvidencePageTally, reason: EvidenceSkip): void {
+  t.skipped[reason] = (t.skipped[reason] ?? 0) + 1;
+}
+
+/** A filesystem-safe, stable, collision-free name for a finding's crop. Derived from the same
+ *  identity SARIF fingerprints use (src/baseline.ts `findingId`), hashed only because that
+ *  identity contains path separators and pipes. The identity itself is never altered. */
+function cropName(f: Finding): string {
+  return `${createHash("sha1").update(findingId(f)).digest("hex").slice(0, 12)}.png`;
+}
+
+/** Draw every non-conformity that can be drawn, write the PNGs under
+ *  `<outDir>/assets/<page-id>/`, and record what was not drawn and why.
+ *
+ *  Pages are the OUTER loop and the context is dropped between them on purpose: a 2560×1440
+ *  screenshot inflates to ~15 MB, and holding 38 of them at once does not fit. Do not hoist. */
+export function writeEvidence(result: AuditResult, opts: EvidenceOptions): EvidenceManifest {
+  const root = opts.root ?? process.cwd();
+  const caps = { ...DEFAULT_CAPS, ...opts.caps };
+  const manifest: EvidenceManifest = {
+    crops: new Map(),
+    skipped: new Map(),
+    perPage: new Map(),
+    totals: { located: 0, imaged: 0, skipped: {} },
+  };
+
+  // The discriminator is the snapshot PATH, never `f.page`: attribution stamps a page id on
+  // source findings too (src/pages.ts), and those have no pixels.
+  const byPage = new Map<string, Finding[]>();
+  for (const f of [...result.findings, ...(result.packFindings ?? [])]) {
+    if (f.advisory) continue;
+    const page = pageIdOfSnapshot(f.file);
+    if (!page) continue;
+    const list = byPage.get(page);
+    if (list) list.push(f);
+    else byPage.set(page, [f]);
+  }
+
+  for (const [pageId, findings] of [...byPage].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const tally: EvidencePageTally = { located: findings.length, imaged: 0, skipped: {} };
+    manifest.perPage.set(pageId, tally);
+    manifest.totals.located += findings.length;
+
+    const ctx = loadPageEvidence(root, pageId);
+    if ("skip" in ctx) {
+      for (const f of findings) {
+        manifest.skipped.set(findingId(f), ctx.skip);
+        bump(tally, ctx.skip);
+        bump(manifest.totals, ctx.skip);
+      }
+      continue;
+    }
+
+    const dir = join(opts.outDir, "assets", pageId);
+    let wrote = false;
+    const perRule = new Map<string, number>();
+    const seen = new Set<string>();
+    let onPage = 0;
+
+    for (const f of findings) {
+      const id = findingId(f);
+      // One image per distinct element per page: 472 findings of one rule collapse to the
+      // handful of DIFFERENT things actually wrong.
+      const key = `${f.ruleId}\u0000${f.selectorHint}`;
+      const ruleCount = perRule.get(f.ruleId) ?? 0;
+      if (seen.has(key) || ruleCount >= caps.perRule || onPage >= caps.perPage || manifest.crops.size >= caps.total) {
+        manifest.skipped.set(id, "capped");
+        bump(tally, "capped");
+        bump(manifest.totals, "capped");
+        continue;
+      }
+
+      const crop = cropFinding(ctx, f, opts.geometry);
+      if ("skip" in crop) {
+        manifest.skipped.set(id, crop.skip);
+        bump(tally, crop.skip);
+        bump(manifest.totals, crop.skip);
+        continue;
+      }
+
+      const name = cropName(f);
+      const path = join(dir, name);
+      try {
+        if (!wrote) {
+          mkdirSync(dir, { recursive: true });
+          wrote = true;
+        }
+        writeFileSync(path, crop.png);
+      } catch {
+        // A failed image write must never fail a report — the same posture the screenshot
+        // copier already takes. The finding keeps its file:line and is counted as not imaged.
+        manifest.skipped.set(id, "no-screenshot");
+        bump(tally, "no-screenshot");
+        bump(manifest.totals, "no-screenshot");
+        continue;
+      }
+
+      seen.add(key);
+      perRule.set(f.ruleId, ruleCount + 1);
+      onPage++;
+      tally.imaged++;
+      manifest.totals.imaged++;
+      manifest.crops.set(id, {
+        findingId: id,
+        page: pageId,
+        ruleId: f.ruleId,
+        criteriaId: f.criteriaId,
+        href: `./assets/${pageId}/${name}`,
+        path,
+        width: crop.width,
+        height: crop.height,
+        box: crop.box,
+        scale: crop.scale,
+        clipped: crop.clipped,
+        alt: { fr: S.fr.alt(f.selectorHint, pageId), en: S.en.alt(f.selectorHint, pageId) },
+      });
+    }
+  }
+
+  return manifest;
+}

package/src/pixel.ts

@@ -1,4 +1,4 @@
-// PIXEL TIER — reading a page screenshot, with no dependencies.
+// PIXEL TIER — reading a page screenshot, and writing one back, with no dependencies.
 //
 // Why bother, when the computed styles already give us colours? Because `getComputedStyle`
 // answers with the CSS *declaration*, not with what a user sees. Text over a gradient, over a
@@ -12,7 +12,17 @@
 // Playwright actually emits is supported — 8-bit truecolour, with or without alpha. Anything
 // else returns null rather than decoding garbage, because a wrong pixel here becomes a
 // fabricated non-conformity.
-import { inflateSync } from "node:zlib";
+//
+// The WRITE side (`encodePng` and the small raster ops beneath it) is the exact reciprocal,
+// and exists so a non-conformity can be shown rather than only cited: `src/evidence.ts` crops
+// the screenshot around the offending element and rings it. It is deliberately the same
+// encoder `scripts/build-extension-icons.mjs` uses, so the committed icons double as an
+// external PNG-conformance fixture that a decode/encode round-trip could never provide.
+//
+// THIS MODULE IS A LEAF, and must stay one: exactly one runtime import (`node:zlib`),
+// everything else `import type`. The icon script imports it directly through Node's
+// type-stripping, which a value import would break.
+import { deflateSync, inflateSync } from "node:zlib";
 import type { RGBA } from "./color.js";
 
 const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
@@ -215,3 +225,165 @@ export function dominantBackground(img: Image, rect: Rect): RGBA | null {
   if (!best || best.n / total < DOMINANCE) return null;
   return { r: Math.round(best.r / best.n), g: Math.round(best.g / best.n), b: Math.round(best.b / best.n), a: 1 };
 }
+
+// ---- the write side ---------------------------------------------------------------------
+//
+// A mutable pixel buffer, unlike `Image` which is a read-only accessor over decoded bytes.
+// The two are deliberately different types: everything that only READS a screenshot keeps
+// taking `Image`, so adding the encoder cannot accidentally hand a rule a writable page.
+
+/** Row-major RGBA8. `data` is exactly `width * height * 4` bytes. */
+export interface Raster {
+  width: number;
+  height: number;
+  data: Buffer;
+}
+
+/** A cropped raster, with the rect it actually took — which is NOT the rect that was asked
+ *  for when the request ran off the edge. The caller needs the real one to translate an
+ *  element box into crop-local coordinates. */
+export interface Crop {
+  raster: Raster;
+  rect: Rect;
+}
+
+// The standard PNG CRC-32 (IEEE 802.3), table-driven because a screenshot's IDAT is megabytes
+// and the bit-at-a-time loop is measurably slower over that. Same polynomial, same output.
+// `@__PURE__` so a bundle that never encodes drops the table with the rest of the write side.
+// Without it esbuild must assume the IIFE has side effects and keeps 1 KB of dead constant.
+const CRC_TABLE = /* @__PURE__ */ (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+function crc32(buf: Buffer): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = (CRC_TABLE[(c ^ (buf[i] as number)) & 0xff] as number) ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+/** An RGBA raster → a PNG. Colour type 6, 8-bit, filter 0 on every scanline.
+ *
+ *  Filter 0 and `level: 9` are not tuning knobs, they are the reproducibility contract: the
+ *  bytes are then a function of the pixels alone, never of zlib's defaults or of a heuristic
+ *  filter choice that could change between Node releases. `scripts/build-extension-icons.mjs`
+ *  `--check` proves the committed icons still match, which only holds while this stays fixed.
+ *
+ *  Throws when `data` disagrees with the dimensions — that is a programming error upstream,
+ *  never user input, and silently padding it would write a skewed image. */
+export function encodePng(r: Raster): Buffer {
+  const expected = r.width * r.height * 4;
+  if (r.width <= 0 || r.height <= 0) throw new Error(`encodePng: refusing a ${r.width}×${r.height} raster`);
+  if (r.data.length !== expected) {
+    throw new Error(`encodePng: ${r.width}×${r.height} needs ${expected} bytes of RGBA, got ${r.data.length}`);
+  }
+  const stride = r.width * 4;
+  const raw = Buffer.alloc(r.height * (stride + 1));
+  for (let y = 0; y < r.height; y++) {
+    raw[y * (stride + 1)] = 0; // filter: none
+    r.data.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(r.width, 0);
+  ihdr.writeUInt32BE(r.height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // RGBA
+  // bytes 10..12 stay 0: deflate compression, adaptive filtering, no interlace.
+  return Buffer.concat([Buffer.from(SIGNATURE), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw, { level: 9 })), chunk("IEND", Buffer.alloc(0))]);
+}
+
+/** Copy a region of a decoded image into a writable raster. Null when nothing of the rect is
+ *  inside — inherited from `clamp`, so a request that ran entirely off the page yields no
+ *  image at all rather than a fabricated one. */
+export function cropImage(img: Image, rect: Rect): Crop | null {
+  const r = clamp(img, rect);
+  if (!r) return null;
+  const data = Buffer.alloc(r.w * r.h * 4);
+  let i = 0;
+  for (let y = r.y; y < r.y + r.h; y++) {
+    for (let x = r.x; x < r.x + r.w; x++) {
+      const p = img.at(x, y);
+      data[i] = p?.r ?? 0;
+      data[i + 1] = p?.g ?? 0;
+      data[i + 2] = p?.b ?? 0;
+      data[i + 3] = Math.round((p?.a ?? 1) * 255);
+      i += 4;
+    }
+  }
+  return { raster: { width: r.w, height: r.h, data }, rect: r };
+}
+
+/** Source-over blend one pixel. Out of bounds is a no-op, never a throw: every drawing call
+ *  here takes coordinates derived from a browser's box, and a box may legitimately sit
+ *  partly outside the crop. */
+function blend(raster: Raster, x: number, y: number, c: RGBA): void {
+  if (x < 0 || y < 0 || x >= raster.width || y >= raster.height) return;
+  const p = (y * raster.width + x) * 4;
+  const a = Math.min(1, Math.max(0, c.a));
+  if (a >= 1) {
+    raster.data[p] = c.r;
+    raster.data[p + 1] = c.g;
+    raster.data[p + 2] = c.b;
+    raster.data[p + 3] = 255;
+    return;
+  }
+  const inv = 1 - a;
+  raster.data[p] = Math.round(c.r * a + (raster.data[p] as number) * inv);
+  raster.data[p + 1] = Math.round(c.g * a + (raster.data[p + 1] as number) * inv);
+  raster.data[p + 2] = Math.round(c.b * a + (raster.data[p + 2] as number) * inv);
+  raster.data[p + 3] = Math.max(raster.data[p + 3] as number, Math.round(a * 255));
+}
+
+/** Fill a rect, source-over. Clipped to the raster; never throws. */
+export function fillRect(raster: Raster, rect: Rect, color: RGBA): void {
+  const x0 = Math.max(0, Math.round(rect.x));
+  const y0 = Math.max(0, Math.round(rect.y));
+  const x1 = Math.min(raster.width, Math.round(rect.x + rect.w));
+  const y1 = Math.min(raster.height, Math.round(rect.y + rect.h));
+  for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) blend(raster, x, y, color);
+}
+
+/** Stroke a rect INWARD — the band lies inside the rect's own bounds, so a box flush with the
+ *  raster edge keeps its full outline instead of losing the half that would fall outside.
+ *
+ *  `dash` is a period in pixels (half on, half off), phased on absolute coordinates so the
+ *  four sides meet consistently at the corners. Undefined draws solid. */
+export function strokeRect(raster: Raster, rect: Rect, color: RGBA, width: number, dash?: number): void {
+  const t = Math.max(1, Math.round(width));
+  const x0 = Math.round(rect.x);
+  const y0 = Math.round(rect.y);
+  const x1 = Math.round(rect.x + rect.w);
+  const y1 = Math.round(rect.y + rect.h);
+  if (x1 <= x0 || y1 <= y0) return;
+  const on = (coord: number): boolean => {
+    if (!dash || dash <= 1) return true;
+    const half = dash / 2;
+    return Math.floor(coord / half) % 2 === 0;
+  };
+  for (let y = y0; y < y1; y++) {
+    for (let x = x0; x < x1; x++) {
+      const top = y < y0 + t;
+      const bottom = y >= y1 - t;
+      const left = x < x0 + t;
+      const right = x >= x1 - t;
+      if (!top && !bottom && !left && !right) continue;
+      // Horizontal bands dash along x, vertical ones along y, so a corner never blinks twice.
+      if (!on(top || bottom ? x : y)) continue;
+      blend(raster, x, y, color);
+    }
+  }
+}

package/src/snapshot.ts

@@ -298,12 +298,17 @@ export function alignedStyles(dom: string, styles: StyleDigest): Map<number, Sty
   return out;
 }
 
-/** Same verified join for bounding boxes. */
-export function alignedBoxes(dom: string, boxes: BoxDigest): Map<number, BoxEntry> | null {
-  const doc = parseHtml(dom, "snapshot");
+/** Same verified join for bounding boxes.
+ *
+ *  `doc` is optional and purely an economy: a caller that has already parsed this very `dom`
+ *  passes it rather than paying for a second parse of a whole page (src/evidence.ts needs the
+ *  same tree to map source offsets to ordinals). The join itself has ONE definition either
+ *  way — that is the point of this function, and of `align` beside it. */
+export function alignedBoxes(dom: string, boxes: BoxDigest, doc?: Doc): Map<number, BoxEntry> | null {
+  const parsed = doc ?? parseHtml(dom, "snapshot");
   const out = new Map<number, BoxEntry>();
   for (const e of boxes.entries) {
-    const el = doc.elements[e.i];
+    const el = parsed.elements[e.i];
     if (!el || el.tag !== e.tag) return null;
     out.set(e.i, e);
   }

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "3.0.0";
+export const VERSION = "3.1.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,