ultra11y 2.29.0 → 2.31.0

package/dist/playwright.mjs

@@ -0,0 +1,250 @@
+// src/integrations/playwright.ts
+import { createRequire as createRequire2 } from "module";
+
+// src/collector.ts
+var COLLECTED_CSS = [
+  "color",
+  "backgroundColor",
+  "backgroundImage",
+  "fontSize",
+  "fontWeight",
+  "fontStyle",
+  "textDecorationLine",
+  "textTransform",
+  "lineHeight",
+  "letterSpacing",
+  "wordSpacing",
+  "whiteSpace",
+  "display",
+  "visibility",
+  "opacity",
+  "position",
+  "overflowX",
+  "overflowY",
+  "outlineStyle",
+  "outlineWidth",
+  "outlineColor",
+  // All four borders + the box shadow: WCAG 1.4.11 asks whether a control's BOUNDARY is
+  // perceivable, and a boundary can be drawn by any side, by the fill, by an outline or by a
+  // shadow. Collecting only one side would manufacture non-conformities on the other three.
+  "borderTopStyle",
+  "borderRightStyle",
+  "borderBottomStyle",
+  "borderLeftStyle",
+  "borderTopWidth",
+  "borderRightWidth",
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "boxShadow",
+  "cursor"
+];
+var COLLECT_MAX_ELEMENTS = 5e3;
+var COLLECT_SNAPSHOT = `(() => {
+  const PROPS = ${JSON.stringify(COLLECTED_CSS)};
+  const MAX = ${COLLECT_MAX_ELEMENTS};
+  const els = document.querySelectorAll('*');
+  const styles = [];
+  const boxes = [];
+  const n = Math.min(els.length, MAX);
+  for (let i = 0; i < n; i++) {
+    const el = els[i];
+    const tag = el.tagName.toLowerCase();
+    const cs = getComputedStyle(el);
+    const css = {};
+    for (const p of PROPS) {
+      const v = cs[p];
+      if (v !== undefined && v !== null && v !== '') css[p] = String(v);
+    }
+    styles.push({ i: i, tag: tag, css: css });
+    const r = el.getBoundingClientRect();
+    boxes.push({ i: i, tag: tag, x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) });
+  }
+  // The page's own stylesheets. Some criteria are properties of the STYLESHEET rather than of
+  // any element's computed style \u2014 focus styling removed with no replacement (2.4.7), a media
+  // query that locks the orientation (1.3.4) \u2014 and this is the only place they exist.
+  // A cross-origin sheet throws on .cssRules: COUNT those instead of ignoring them, so a rule
+  // reading this digest can tell "nothing there" apart from "I could not look".
+  const cssRules = [];
+  let unreadable = 0;
+  const MAXR = 4000;
+  const camel = (p) => p.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  const walk = (list, media) => {
+    for (const r of list) {
+      if (cssRules.length >= MAXR) return;
+      if (typeof r.selectorText === 'string' && r.style) {
+        const decls = {};
+        for (let i = 0; i < r.style.length; i++) {
+          const prop = r.style[i];
+          decls[camel(prop)] = r.style.getPropertyValue(prop);
+        }
+        cssRules.push(media ? { selector: r.selectorText, media: media, decls: decls } : { selector: r.selectorText, decls: decls });
+      } else if (r.cssRules) {
+        const cond = r.conditionText || (r.media && r.media.mediaText) || media;
+        walk(r.cssRules, cond);
+      }
+    }
+  };
+  for (const sheet of document.styleSheets) {
+    try {
+      walk(sheet.cssRules, undefined);
+    } catch (e) {
+      unreadable++;
+    }
+  }
+
+  const truncated = els.length > MAX;
+  return {
+    dom: document.documentElement.outerHTML,
+    css: { v: 1, rules: cssRules, unreadable: unreadable, truncated: cssRules.length >= MAXR },
+    title: document.title,
+    lang: document.documentElement.getAttribute('lang') || '',
+    url: location.href,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    styles: { v: 1, entries: styles, truncated: truncated },
+    boxes: { v: 1, entries: boxes, truncated: truncated }
+  };
+})()`;
+
+// src/integrations/core.ts
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+
+// src/integrations/payload.ts
+var RANK = { bloquant: 0, majeur: 1, mineur: 2 };
+var THRESHOLD = { blocking: 0, bloquant: 0, major: 1, majeur: 1, minor: 2, mineur: 2 };
+function failingFindings(result, failOn) {
+  const max = THRESHOLD[failOn];
+  if (max === void 0) throw new Error(`ultra11y: failOn must be blocking|major|minor (got "${failOn}")`);
+  return (result.findings ?? []).filter((f) => !f.advisory && (RANK[f.severity] ?? 99) <= max);
+}
+function formatFailure(pageName, failing) {
+  const lines = [`ultra11y: ${failing.length} accessibility non-conformity(ies) on "${pageName}":`];
+  for (const f of failing.slice(0, 20)) {
+    lines.push(`  [${f.severity}] ${f.ruleId} (WCAG ${f.criteriaId}) \u2014 ${f.origin?.sourceFile ?? f.file} \u2014 ${f.message}`);
+  }
+  if (failing.length > 20) lines.push(`  \u2026 and ${failing.length - 20} more.`);
+  lines.push("Full detail: .ultra11y/pages/ \u2014 re-audit offline with `ultra11y audit`.");
+  return lines.join("\n");
+}
+function slugify(url) {
+  let path = url;
+  try {
+    path = new URL(url).pathname;
+    try {
+      path = decodeURIComponent(path);
+    } catch {
+    }
+  } catch {
+  }
+  const slug = path.normalize("NFD").replace(new RegExp("\\p{Diacritic}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || (path === "/" || path === "" ? "accueil" : "page");
+}
+function buildPayload(collected, url, runner, opts, screenshot) {
+  const id = opts.as || slugify(url);
+  return {
+    meta: {
+      v: 1,
+      id,
+      name: opts.name || collected.title || id,
+      url,
+      runner,
+      viewport: collected.viewport,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...opts.auth !== void 0 ? { auth: opts.auth } : {},
+      ...opts.sources ? { sources: opts.sources } : {},
+      ...opts.notes ? { notes: opts.notes } : {}
+    },
+    dom: collected.dom,
+    styles: collected.styles,
+    boxes: collected.boxes,
+    css: collected.css,
+    ...screenshot ? { screenshot } : {}
+  };
+}
+function gate(result, pageName, failOn) {
+  const threshold = failOn === void 0 ? "blocking" : failOn;
+  if (threshold === false) return;
+  const failing = failingFindings(result, threshold);
+  if (failing.length) throw new Error(formatFailure(pageName, failing));
+}
+
+// src/integrations/core.ts
+function enginePath() {
+  if (process.env.ULTRA11Y) return process.env.ULTRA11Y;
+  try {
+    return createRequire(import.meta.url).resolve("ultra11y/scripts/ultra11y.mjs");
+  } catch {
+    return new URL("../scripts/ultra11y.mjs", import.meta.url).pathname;
+  }
+}
+function auditSnapshot(payload, engine = enginePath()) {
+  const res = spawnSync(process.execPath, [engine, "snapshot", "write", "--json"], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    maxBuffer: 192 * 1024 * 1024
+  });
+  if (res.error) throw new Error(`ultra11y: could not run the engine at ${engine} \u2014 ${res.error.message}`);
+  if (!res.stdout) throw new Error(`ultra11y: the engine produced no output (exit ${res.status})
+${res.stderr || ""}`);
+  try {
+    return JSON.parse(res.stdout);
+  } catch {
+    throw new Error(`ultra11y: could not parse the engine output
+${res.stdout.slice(0, 500)}`);
+  }
+}
+function writePagesReport(opts = {}, engine = enginePath()) {
+  const args = [engine, "pages", "--in", "-", "--format", "report"];
+  if (opts.split !== false) args.push("--split", "page");
+  args.push("--out", opts.out ?? "audits/pages");
+  if (opts.standard) args.push("--standard", opts.standard);
+  if (opts.lang) args.push("--lang", opts.lang);
+  const audit = spawnSync(process.execPath, [engine, "audit", ".ultra11y/pages", "--json"], { encoding: "utf8", maxBuffer: 192 * 1024 * 1024 });
+  if (audit.error || !audit.stdout) return void 0;
+  const res = spawnSync(process.execPath, args, { input: audit.stdout, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  if (res.error || res.status !== 0) return void 0;
+  return res.stdout.trim() || void 0;
+}
+
+// src/integrations/playwright.ts
+async function checkA11y(page, opts = {}) {
+  const collected = await page.evaluate(COLLECT_SNAPSHOT);
+  let shot;
+  if (opts.screenshot !== false) {
+    try {
+      shot = (await page.screenshot({ fullPage: false })).toString("base64");
+    } catch {
+    }
+  }
+  const url = collected.url || page.url();
+  const payload = buildPayload(collected, url, "playwright", opts, shot);
+  const result = auditSnapshot(payload);
+  if (opts.report) writePagesReport(typeof opts.report === "object" ? opts.report : {});
+  gate(result, String(payload.meta.name), opts.failOn);
+  return result;
+}
+var test = (() => {
+  const load = (from) => createRequire2(from)("@playwright/test");
+  for (const from of [`${process.cwd()}/package.json`, import.meta.url]) {
+    try {
+      const base = load(from).test;
+      if (!base?.extend) continue;
+      return base.extend({
+        // biome-ignore lint/suspicious/noExplicitAny: same
+        ultra11y: async ({ page }, use) => {
+          await use((opts) => checkA11y(page, opts));
+        }
+      });
+    } catch {
+    }
+  }
+  return void 0;
+})();
+export {
+  checkA11y,
+  test
+};

package/docker/runner.mjs

@@ -2,10 +2,21 @@ import { chromium } from "playwright";
 import axe from "axe-core";
 const target = process.argv[2];
 const isFile = target.startsWith("/work/");
+const SNAPSHOT = process.env.ULTRA11Y_SNAPSHOT !== "0";
+const COLLECT = "(() => {\n  const PROPS = [\"color\",\"backgroundColor\",\"backgroundImage\",\"fontSize\",\"fontWeight\",\"fontStyle\",\"textDecorationLine\",\"textTransform\",\"lineHeight\",\"letterSpacing\",\"wordSpacing\",\"whiteSpace\",\"display\",\"visibility\",\"opacity\",\"position\",\"overflowX\",\"overflowY\",\"outlineStyle\",\"outlineWidth\",\"outlineColor\",\"borderTopStyle\",\"borderRightStyle\",\"borderBottomStyle\",\"borderLeftStyle\",\"borderTopWidth\",\"borderRightWidth\",\"borderBottomWidth\",\"borderLeftWidth\",\"borderTopColor\",\"borderRightColor\",\"borderBottomColor\",\"borderLeftColor\",\"boxShadow\",\"cursor\"];\n  const MAX = 5000;\n  const els = document.querySelectorAll('*');\n  const styles = [];\n  const boxes = [];\n  const n = Math.min(els.length, MAX);\n  for (let i = 0; i < n; i++) {\n    const el = els[i];\n    const tag = el.tagName.toLowerCase();\n    const cs = getComputedStyle(el);\n    const css = {};\n    for (const p of PROPS) {\n      const v = cs[p];\n      if (v !== undefined && v !== null && v !== '') css[p] = String(v);\n    }\n    styles.push({ i: i, tag: tag, css: css });\n    const r = el.getBoundingClientRect();\n    boxes.push({ i: i, tag: tag, x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) });\n  }\n  // The page's own stylesheets. Some criteria are properties of the STYLESHEET rather than of\n  // any element's computed style — focus styling removed with no replacement (2.4.7), a media\n  // query that locks the orientation (1.3.4) — and this is the only place they exist.\n  // A cross-origin sheet throws on .cssRules: COUNT those instead of ignoring them, so a rule\n  // reading this digest can tell \"nothing there\" apart from \"I could not look\".\n  const cssRules = [];\n  let unreadable = 0;\n  const MAXR = 4000;\n  const camel = (p) => p.replace(/-([a-z])/g, (_, c) => c.toUpperCase());\n  const walk = (list, media) => {\n    for (const r of list) {\n      if (cssRules.length >= MAXR) return;\n      if (typeof r.selectorText === 'string' && r.style) {\n        const decls = {};\n        for (let i = 0; i < r.style.length; i++) {\n          const prop = r.style[i];\n          decls[camel(prop)] = r.style.getPropertyValue(prop);\n        }\n        cssRules.push(media ? { selector: r.selectorText, media: media, decls: decls } : { selector: r.selectorText, decls: decls });\n      } else if (r.cssRules) {\n        const cond = r.conditionText || (r.media && r.media.mediaText) || media;\n        walk(r.cssRules, cond);\n      }\n    }\n  };\n  for (const sheet of document.styleSheets) {\n    try {\n      walk(sheet.cssRules, undefined);\n    } catch (e) {\n      unreadable++;\n    }\n  }\n\n  const truncated = els.length > MAX;\n  return {\n    dom: document.documentElement.outerHTML,\n    css: { v: 1, rules: cssRules, unreadable: unreadable, truncated: cssRules.length >= MAXR },\n    title: document.title,\n    lang: document.documentElement.getAttribute('lang') || '',\n    url: location.href,\n    viewport: { width: window.innerWidth, height: window.innerHeight },\n    styles: { v: 1, entries: styles, truncated: truncated },\n    boxes: { v: 1, entries: boxes, truncated: truncated }\n  };\n})()";
 const browser = await chromium.launch({ args: ["--no-sandbox", "--disable-dev-shm-usage"] });
 try {
   const page = await browser.newPage();
   await page.goto(isFile ? "file://" + target : target, { waitUntil: "load", timeout: 45000 });
+  // Collected FIRST, on the pristine page: axe's injected source and the 320px reflow
+  // resize both come after, and a snapshot must be the page as the browser built it.
+  let snapshot;
+  if (SNAPSHOT) {
+    try {
+      snapshot = await page.evaluate(COLLECT);
+      try { snapshot.screenshot = (await page.screenshot({ fullPage: false })).toString("base64"); } catch {}
+    } catch {}
+  }
   await page.addScriptTag({ content: axe.source });
   const axeRes = await page.evaluate(async () => await window.axe.run(document, { resultTypes: ["violations"] }));
   await page.setViewportSize({ width: 320, height: 800 });
@@ -17,7 +28,7 @@ try {
     id: v.id, impact: v.impact, help: v.help, tags: v.tags,
     nodes: v.nodes.slice(0, 10).map((n) => ({ target: n.target, html: (n.html || "").slice(0, 200) })),
   }));
-  console.log(JSON.stringify({ url: target, violations, reflow }));
+  console.log(JSON.stringify({ url: target, violations, reflow, snapshot }));
 } finally {
   await browser.close();
 }

package/package.json

@@ -1,15 +1,36 @@
 {
   "name": "ultra11y",
-  "version": "2.29.0",
+  "version": "2.31.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",
   "bin": {
     "ultra11y": "scripts/ultra11y.mjs"
   },
+  "exports": {
+    ".": "./.opencode/plugins/ultra11y.js",
+    "./playwright": {
+      "types": "./dist/playwright.d.ts",
+      "import": "./dist/playwright.mjs",
+      "default": "./dist/playwright.mjs"
+    },
+    "./cypress": {
+      "types": "./dist/cypress.d.ts",
+      "import": "./dist/cypress.mjs",
+      "default": "./dist/cypress.mjs"
+    },
+    "./cypress/plugin": {
+      "types": "./dist/cypress-plugin.d.ts",
+      "import": "./dist/cypress-plugin.mjs",
+      "default": "./dist/cypress-plugin.mjs"
+    },
+    "./scripts/ultra11y.mjs": "./scripts/ultra11y.mjs",
+    "./package.json": "./package.json"
+  },
   "files": [
     "scripts",
     "src",
+    "dist",
     "skills",
     "docker",
     ".claude-plugin",
@@ -33,7 +54,7 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "verify:bundle": "node scripts/verify-skill-bundle.mjs",
-    "check:build": "tsup && node scripts/copy-bundle.mjs && git diff --exit-code -- scripts/ultra11y.mjs skills/ultra11y/scripts/ultra11y.mjs skills/review-a11y/scripts/ultra11y.mjs && node scripts/verify-skill-bundle.mjs && node scripts/sync-engine.mjs --check",
+    "check:build": "tsup && node scripts/copy-bundle.mjs && git diff --exit-code -- scripts/ultra11y.mjs skills/ultra11y/scripts/ultra11y.mjs skills/review-a11y/scripts/ultra11y.mjs dist && node scripts/build-extension-icons.mjs --check && node scripts/verify-skill-bundle.mjs && node scripts/sync-engine.mjs --check",
     "build:wcag": "node scripts/build-standards.mjs",
     "build:pack:rgaa": "node scripts/build-pack-rgaa.mjs",
     "check:pack:rgaa": "node scripts/build-pack-rgaa.mjs --check",
@@ -43,7 +64,8 @@
     "build:adjudication": "node scripts/build-adjudication.mjs && UPDATE_ADJUDICATION_MD=1 vitest run tests/adjudication-md-sync.test.ts",
     "check:adjudication": "node scripts/build-adjudication.mjs --check",
     "demo": "node scripts/ultra11y.mjs audit tests/fixtures/non-conforming/bad.html --out /tmp/ultra11y-demo --json > /dev/null && node scripts/ultra11y.mjs report --in /tmp/ultra11y-demo/audit-latest.json --out /tmp/ultra11y-demo && node scripts/ultra11y.mjs check --report /tmp/ultra11y-demo/wcag-*.md && node scripts/ultra11y.mjs criteria --list",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "build:icons": "node scripts/build-extension-icons.mjs"
   },
   "license": "MIT",
   "author": "maxgfr",

package/scripts/build-extension-icons.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Generates the browser extension's icons — DEV ONLY, never shipped in the engine bundle.
+//
+// Why generate rather than commit a binary somebody drew: an icon is the one asset a reviewer
+// cannot diff. Deriving it from a few lines of code means the shape is reviewable, every size
+// is guaranteed consistent, and `--check` can prove the committed PNGs are exactly what this
+// 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.
+//
+//   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";
+
+const OUT = join(dirname(fileURLToPath(import.meta.url)), "..", "extension", "icons");
+const SIZES = [16, 32, 48, 128];
+
+// action.yml declares `color: purple`; keep the extension recognisably the same tool.
+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;
+  const n = size * S;
+  const acc = new Float64Array(size * size * 4);
+  const c = n / 2;
+  const rOuter = n * 0.47; // the rounded square's inscribed radius
+  const corner = n * 0.22;
+  const lensW = n * 0.34;
+  const lensH = n * 0.2;
+  const pupil = n * 0.108;
+
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      const dx = x - c;
+      const dy = y - c;
+      // Rounded square (squircle-ish): outside it the pixel is transparent.
+      const ax = Math.abs(dx);
+      const ay = Math.abs(dy);
+      const inSquare =
+        ax <= rOuter && ay <= rOuter && (ax <= rOuter - corner || ay <= rOuter - corner || (ax - (rOuter - corner)) ** 2 + (ay - (rOuter - corner)) ** 2 <= corner ** 2);
+      if (!inSquare) continue;
+
+      // The lens: an ellipse. The pupil is a disc at its centre.
+      const inLens = (dx / lensW) ** 2 + (dy / lensH) ** 2 <= 1;
+      const inPupil = dx * dx + dy * dy <= pupil * pupil;
+      const [r, g, b] = inLens && !inPupil ? FG : BG;
+
+      const i = (Math.floor(y / S) * size + Math.floor(x / S)) * 4;
+      acc[i] += r;
+      acc[i + 1] += g;
+      acc[i + 2] += b;
+      acc[i + 3] += 255;
+    }
+  }
+
+  const out = Buffer.alloc(size * size * 4);
+  const per = S * S;
+  for (let i = 0; i < size * size; i++) {
+    const a = acc[i * 4 + 3] / per;
+    // Un-premultiply: the accumulator summed colour only over covered samples.
+    const cov = acc[i * 4 + 3] / 255 || 1;
+    out[i * 4] = Math.round(acc[i * 4] / cov);
+    out[i * 4 + 1] = Math.round(acc[i * 4 + 1] / cov);
+    out[i * 4 + 2] = Math.round(acc[i * 4 + 2] / cov);
+    out[i * 4 + 3] = Math.round(a);
+  }
+  return out;
+}
+
+const check = process.argv.includes("--check");
+mkdirSync(OUT, { recursive: true });
+let stale = [];
+for (const size of SIZES) {
+  const file = join(OUT, `icon-${size}.png`);
+  const bytes = png(size, draw(size));
+  if (check) {
+    let current = null;
+    try {
+      current = readFileSync(file);
+    } catch {}
+    if (!current || !current.equals(bytes)) stale.push(`icon-${size}.png`);
+  } else {
+    writeFileSync(file, bytes);
+  }
+}
+if (check && stale.length) {
+  console.error(`build-extension-icons: committed icons differ from the source (${stale.join(", ")}). Run \`node scripts/build-extension-icons.mjs\`.`);
+  process.exitCode = 1;
+} else {
+  console.log(check ? "build-extension-icons: committed icons match the source." : `build-extension-icons: wrote ${SIZES.length} icon(s) to extension/icons/.`);
+}

package/scripts/check-artifact-recall.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// Recall guard for regenerated ENGINE-OUTPUT artifacts.
+//
+// The problem this exists to solve, in one sentence: some committed artifacts
+// are this repo's own product and must never move on an engine bump, and some
+// ARE the engine's output and legitimately move on every one. Treating the
+// second kind as a hard red is how an engine pin rots — ultrasec's sat seven
+// releases behind because twelve goldens moved and every nightly re-pin died on
+// them. Treating it as free is worse: an engine that quietly stopped finding a
+// class of bugs would be committed as the new "expected" and pushed to main.
+//
+// So the re-pin regenerates them, and this compares the regenerated artifacts to
+// the committed ones and fails only on LOSS. Enrichment — more findings, more
+// fields, new files — passes. Losing something is a human decision, never an
+// automatic push.
+//
+// What "loss" means, per file type:
+//   *.json  every array in the structure, keyed by its path; a shorter array is
+//           a loss. `["a","b"] -> ["a"]` fails, `-> ["a","b","c"]` passes.
+//   *.snap  every object key appearing in the text; fewer occurrences of
+//           `"ruleId":` means fewer findings, fewer `"related":` means a
+//           cross-file link was dropped. Text, because a vitest snapshot is not
+//           JSON and hand-parsing it would break on the next vitest release.
+//   other   line count. Blunt on purpose: a prose report that got shorter is
+//           worth a human look, and a file with no finer structure gives
+//           nothing better to measure.
+//
+// Keys under FEWER_IS_BETTER are exempt: a shrinking `warnings` or `todo` array
+// is the fix landing, not recall being lost.
+//
+// Usage: node scripts/check-artifact-recall.mjs [--ref HEAD] [--verbose]
+// Exit 0 = nothing lost · 1 = something was lost · 2 = usage/runtime error.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ---------------------------------------------------------------------------
+// The per-repo table. The ONLY part of this file that differs between repos:
+// which committed paths are engine output. Anything not listed here keeps
+// whatever gate it already had — an `orchestrate` snapshot holds the RUNBOOK
+// this skill generates itself, which no engine bump has any business moving.
+const TRACKED = [
+  // The graph snapshot is `audit --graph` over the golden fixture: the rules are
+  // this repo's, but the cross-file links they fire on come from codeindex, so a
+  // newer engine resolves more of them. The `orchestrate` snapshot beside it is
+  // the RUNBOOK this skill writes itself — deliberately NOT listed, so it stays
+  // a hard red.
+  "tests/__snapshots__/golden-graph.test.ts.snap",
+];
+
+// Arrays whose shrinking is an improvement, not a regression. Matched as a
+// SUFFIX on the last path segment, case-insensitively: a repo calls them
+// `knownGaps`, `parseErrors` or `unresolvedRefs`, and a guard that only knew the
+// bare words would report every closed gap as a loss — a red on good news is a
+// red people learn to ignore.
+const FEWER_IS_BETTER = ["warning", "error", "todo", "unresolved", "skipped", "failure", "gap", "miss"];
+
+const refIdx = process.argv.indexOf("--ref");
+const ref = refIdx === -1 ? "HEAD" : (process.argv[refIdx + 1] ?? "HEAD");
+const verbose = process.argv.includes("--verbose");
+
+/** The committed bytes of a path, or null when it is new in this tree. */
+function committed(rel) {
+  try {
+    return execFileSync("git", ["show", `${ref}:${rel}`], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null; // not in the ref: brand new, nothing to lose yet
+  }
+}
+
+/** Every file under the tracked paths, repo-relative, sorted. */
+function expand(paths) {
+  const out = [];
+  const walk = (rel) => {
+    const abs = join(root, rel);
+    if (!existsSync(abs)) return;
+    if (statSync(abs).isDirectory()) {
+      for (const name of execFileSync("git", ["ls-files", rel], { cwd: root, encoding: "utf8" }).split("\n").filter(Boolean)) {
+        out.push(name);
+      }
+      return;
+    }
+    out.push(relative(root, abs));
+  };
+  for (const p of paths) walk(p);
+  return [...new Set(out)].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Measurements. Each returns a Map of "what" -> count.
+
+function measureJson(text) {
+  const m = new Map();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    return null; // unparseable: fall back to lines rather than guess
+  }
+  // ADD, never set: every element of an array shares one path (`cases[].sites`),
+  // so overwriting would keep only the last sibling's length and go blind to a
+  // loss in any of the others. Summing makes the key mean "sites across all
+  // cases", which is the number that must not go down.
+  const add = (path, n) => m.set(path, (m.get(path) ?? 0) + n);
+  const visit = (node, path) => {
+    if (Array.isArray(node)) {
+      add(path, node.length);
+      node.forEach((v) => visit(v, `${path}[]`));
+      return;
+    }
+    if (node && typeof node === "object") for (const [k, v] of Object.entries(node)) visit(v, path ? `${path}.${k}` : k);
+  };
+  visit(data, "");
+  return m;
+}
+
+function measureSnapshot(text) {
+  const m = new Map();
+  for (const [, key] of text.matchAll(/^\s*"([^"]+)":/gm)) m.set(key, (m.get(key) ?? 0) + 1);
+  // Keys alone are blind to keyless array elements: a dependency cycle is
+  // `["src/a.ts", "src/b.ts"]`, so dropping a whole cycle changes no key count
+  // at all. Count bare scalar elements as their own bucket — that is where a
+  // path, a cycle or a call site actually lives.
+  const bare = [...text.matchAll(/^\s*(?:"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?|true|false|null),?\s*$/gm)].length;
+  if (bare) m.set("«scalar elements»", bare);
+  return m;
+}
+
+const measure = (rel, text) => {
+  if (rel.endsWith(".json")) return measureJson(text) ?? new Map([["lines", text.split("\n").length]]);
+  if (rel.endsWith(".snap")) return measureSnapshot(text);
+  return new Map([["lines", text.split("\n").length]]);
+};
+
+const exempt = (what) => {
+  const last = (what.split(/[.[]/).filter(Boolean).pop() ?? what).toLowerCase().replace(/s$/, "");
+  return FEWER_IS_BETTER.some((w) => last.endsWith(w));
+};
+
+// ---------------------------------------------------------------------------
+
+const files = expand(TRACKED);
+if (files.length === 0) {
+  console.error(`check-artifact-recall: none of the tracked paths exist (${TRACKED.join(", ")})`);
+  process.exit(2);
+}
+
+const lost = [];
+let gained = 0;
+let added = 0;
+let unchanged = 0;
+
+for (const rel of files) {
+  const before = committed(rel);
+  if (before === null) {
+    added++;
+    continue;
+  }
+  let after;
+  try {
+    after = readFileSync(join(root, rel), "utf8");
+  } catch {
+    // A tracked artifact that vanished during regeneration is the loudest
+    // possible loss: report it as one rather than skipping the file.
+    lost.push({ rel, what: "(the file itself)", before: 1, after: 0 });
+    continue;
+  }
+  if (before === after) {
+    unchanged++;
+    continue;
+  }
+  const b = measure(rel, before);
+  const a = measure(rel, after);
+  for (const [what, n] of b) {
+    if (exempt(what)) continue;
+    const now = a.get(what) ?? 0;
+    if (now < n) lost.push({ rel, what, before: n, after: now });
+    else if (now > n) gained++;
+  }
+  for (const [what, n] of a) if (!b.has(what) && n > 0) gained++;
+}
+
+const summary = `${files.length} tracked · ${unchanged} unchanged · ${added} new · ${gained} enriched`;
+
+if (lost.length) {
+  console.error(`check-artifact-recall: RECALL LOST — ${summary}`);
+  for (const l of lost) console.error(`  ${l.rel}: ${l.what} ${l.before} -> ${l.after}`);
+  console.error("");
+  console.error("A regenerated artifact that finds LESS than the committed one is a behaviour");
+  console.error("change, not a re-pin. Nothing was pushed. Review it by hand and commit it");
+  console.error("deliberately if the loss is correct.");
+  process.exit(1);
+}
+
+if (verbose) for (const rel of files) console.log(`  ok ${rel}`);
+console.log(`check-artifact-recall: no recall lost — ${summary}`);