pixel-perfect-kit 0.1.0

package/tools/cli-selftest.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * cli-selftest.js — guards the TOOL CONTRACTS of the kit's Node entry points.
+ *
+ * selftest.js guards what the diff *measures*; this guards how the tools *behave at their
+ * edges* — the Claude Code tool-contract properties: validate input, bound output, fail
+ * loudly with a self-describing, actionable message (never a raw stack), and use stable
+ * exit codes. Each assertion here is a bug we fixed; this file keeps it fixed.
+ *
+ * Runs against the real pixel-diff CLI (child process) and the pure, exported guards of
+ * serve.js / sink.js (no sockets). Exit 0 = green.
+ */
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const cp = require("child_process");
+
+const PD = path.join(__dirname, "pixel-diff.js");
+const { resolvePath } = require("../harness/serve.js");
+const { classifyBody, sanitizeName } = require("./sink.js");
+
+let failed = 0;
+const ok = (cond, msg) => { if (cond) console.log(`  ✓ ${msg}`); else { failed++; console.log(`  ✗ ${msg}`); } };
+
+// scratch dir in the OS temp area (hermetic)
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ppk-cli-"));
+process.on("exit", () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) {} });
+const w = (f, s) => { const p = path.join(dir, f); fs.writeFileSync(p, s); return p; };
+const snap = JSON.stringify({ viewport: { width: 1728 }, elements: { logo: { present: true, rect: { x: 0, y: 0, w: 10, h: 10, top: 0, right: 10, bottom: 10, fromRight: 0 } } } });
+const run = (args) => { const r = cp.spawnSync(process.execPath, [PD, ...args], { encoding: "utf8" }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+
+const a = w("a.json", snap), b = w("b.json", snap);
+
+console.log("cli-selftest — tool contracts (validate input, self-describing errors, exit codes)");
+
+// pixel-diff: valid diff of identical snapshots exits 0
+ok(run([a, b]).code === 0, "identical snapshots → exit 0");
+
+// --tol now WORKS (regression: the flag value was being counted as a file)
+{ const r = run([a, b, "--tol", "0.5"]); ok(r.code === 0 && !/usage/.test(r.out), "--tol 0.5 is parsed, not treated as a file"); }
+// a bad --tol value is rejected with a clear message
+{ const r = run([a, b, "--tol", "abc"]); ok(r.code === 2 && /--tol needs a non-negative number/.test(r.out), "--tol abc → exit 2 with an actionable message"); }
+// unknown flags are rejected, not silently ignored
+{ const r = run([a, b, "--nope"]); ok(r.code === 2 && /unknown flag/.test(r.out), "unknown flag → exit 2"); }
+
+// missing file → self-describing error (not a raw ENOENT stack), exit 2
+{ const r = run([a, path.join(dir, "nope.json")]); ok(r.code === 2 && /not found/.test(r.out) && !/at Object\./.test(r.out), "missing file → 'not found', no stack trace"); }
+// invalid JSON → self-describing error (not a raw SyntaxError stack)
+{ const bad = w("bad.json", "not json{"); const r = run([a, bad]); ok(r.code === 2 && /not valid JSON/.test(r.out) && !/SyntaxError\b.*\n\s+at /.test(r.out), "invalid JSON → 'not valid JSON', no stack trace"); }
+// a [BLOCKED…] automation sentinel is caught, not diffed as data
+{ const blk = w("blk.json", "[BLOCKED: content filter]"); const r = run([a, blk]); ok(r.code === 2 && /BLOCKED/.test(r.out), "[BLOCKED…] sentinel → exit 2 with guidance"); }
+// wrong shape (no .elements) without --inspect is a clear mix-up error
+{ const noEl = w("noel.json", JSON.stringify({ viewport: { width: 1728 } })); const r = run([a, noEl]); ok(r.code === 2 && /no "elements"/.test(r.out), "snapshot without elements → clear mix-up error"); }
+// wrong count of files → exit 2 + usage
+{ const r = run([a]); ok(r.code === 2 && /expected 2 snapshot files/.test(r.out), "one file → exit 2 with usage"); }
+
+// serve.js path-boundary guard (pure): legit paths resolve, traversal + prefix-siblings rejected
+{
+  const roots = { cloneDir: "/x/clone", toolsDir: "/x/tools" };
+  ok(resolvePath("/", roots) === path.resolve("/x/clone", "index.html"), "'/' → clone/index.html");
+  ok(resolvePath("/styles.css", roots) === path.resolve("/x/clone", "styles.css"), "in-root file resolves");
+  ok(resolvePath("/tools/browser-capture.js", roots) === path.resolve("/x/tools", "browser-capture.js"), "/tools/* → tools dir");
+  ok(resolvePath("/../secret", roots) === null, "../ traversal rejected");
+  ok(resolvePath("/tools/../../etc/passwd", roots) === null, "nested ../ traversal rejected");
+  ok(resolvePath("/%", roots) === null, "malformed percent-encoding returns null instead of throwing (server survives)");
+  ok(resolvePath("/%zz", roots) === null, "invalid escape sequence returns null instead of throwing");
+}
+
+// sink.js body guard (pure): empty / oversize / [BLOCKED] refused; non-JSON warned; good JSON ok
+ok(classifyBody("clone.json", "").write === false && classifyBody("clone.json", "").status === 400, "empty body refused (400)");
+ok(classifyBody("clone.json", "[BLOCKED: x]").write === false, "[BLOCKED…] body refused");
+ok(classifyBody("clone.json", "x".repeat(21 * 1024 * 1024)).status === 413, "oversize body refused (413)");
+{ const r = classifyBody("clone.json", "not json"); ok(r.write === true && /NOT valid JSON/.test(r.message), "non-JSON under .json name is written but warned"); }
+ok(classifyBody("clone.json", snap).status === 200 && classifyBody("clone.json", snap).write === true, "valid JSON snapshot accepted");
+ok(sanitizeName("/a/b/clone.json").renamed === true, "sub-path name flagged as sanitized (silent-rename footgun surfaced)");
+{ const r = sanitizeName("/clone.json?t=1"); ok(r.clean === "clone.json" && r.renamed === false, "query string is stripped, not fused into the filename"); }
+
+// reassemble.js — chunk joining is a VERIFIED operation (the HN dogfood run corrupted a
+// snapshot by hand-concatenating chunks; these lock the validator that prevents it).
+{
+  const RA = path.join(__dirname, "reassemble.js");
+  const runRA = (args) => { const r = cp.spawnSync(process.execPath, [RA, ...args], { encoding: "utf8", cwd: dir }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+  const c0 = w("chunk-00.txt", snap.slice(0, 40));
+  const c1 = w("chunk-01.txt", snap.slice(40));
+  const outFile = path.join(dir, "reassembled.json");
+  { const r = runRA([outFile, "--bytes", String(snap.length), c0, c1]); ok(r.code === 0 && fs.existsSync(outFile) && fs.readFileSync(outFile, "utf8") === snap, "valid chunks + matching byte count reassemble to the exact snapshot"); }
+  { const r = runRA([outFile, "--bytes", String(snap.length + 7), c0, c1]); ok(r.code === 2 && /byte count mismatch/.test(r.out), "byte-count mismatch → exit 2 naming the missing bytes"); }
+  // drop a QUOTE at the boundary → structurally invalid JSON, caught by the parse check
+  { const qi = snap.indexOf('"', 10); const cbad = w("chunk-01bad.txt", snap.slice(qi + 1)); const r = runRA([outFile, w("chunk-00q.txt", snap.slice(0, qi)), cbad]); ok(r.code === 2 && /not valid JSON/.test(r.out), "corrupt chunk boundary (dropped quote) → exit 2, nothing written silently"); }
+  // drop a LETTER at the boundary → still-parseable-but-wrong JSON (the real dogfood bug);
+  // only the byte count catches this class — which is why --bytes must always be passed
+  { const r = runRA([outFile, "--bytes", String(snap.length), w("chunk-00l.txt", snap.slice(0, 40)), w("chunk-01l.txt", snap.slice(41))]); ok(r.code === 2 && /byte count mismatch/.test(r.out), "dropped-letter corruption (valid JSON, wrong data) → caught by --bytes"); }
+  { const r = runRA([outFile]); ok(r.code === 2 && /usage/.test(r.out), "no chunk files → exit 2 with usage"); }
+}
+
+// serve.js port collision → actionable error, not a raw stack
+{
+  const holder = cp.spawn(process.execPath, ["-e", "require('http').createServer(() => {}).listen(18094, () => console.log('up')); setTimeout(() => {}, 30000)"], { stdio: ["ignore", "pipe", "ignore"] });
+  try {
+    let up = false;
+    for (let i = 0; i < 30 && !up; i++) { const ping = cp.spawnSync("curl", ["-s", "-o", "/dev/null", "--max-time", "1", "http://127.0.0.1:18094/"], {}); if (ping.status === 0 || ping.status === 52) up = true; else cp.spawnSync(process.execPath, ["-e", "setTimeout(() => {}, 100)"]); }
+    fs.mkdirSync(path.join(dir, "targets", "col", "clone"), { recursive: true });
+    const r = cp.spawnSync(process.execPath, [path.join(__dirname, "..", "harness", "serve.js"), "col", "18094"], { encoding: "utf8", cwd: dir, timeout: 5000 });
+    const out2 = (r.stdout || "") + (r.stderr || "");
+    ok(r.status === 1 && /already in use/.test(out2) && !/at Server\./.test(out2), "serve on a taken port → 'already in use' + exit 1, no stack trace");
+  } finally { holder.kill(); }
+}
+
+// sink streaming abort (real server, tiny limit via env): the size bound must hold DURING
+// the stream, not just at end — the aborted body must never reach disk.
+{
+  const port = 17799;
+  const sink = cp.spawn(process.execPath, [path.join(__dirname, "sink.js")], {
+    cwd: dir,
+    env: { ...process.env, PPK_SINK_PORT: String(port), PPK_SINK_MAX_BYTES: "1000" },
+    stdio: "ignore",
+  });
+  try {
+    let up = false;
+    for (let i = 0; i < 50 && !up; i++) {
+      const ping = cp.spawnSync("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "-X", "OPTIONS", `http://127.0.0.1:${port}/ping`], { encoding: "utf8" });
+      if (ping.stdout === "200") up = true;
+      else cp.spawnSync(process.execPath, ["-e", "setTimeout(() => {}, 100)"]);
+    }
+    ok(up, "sink starts on an env-configured port");
+    const r = cp.spawnSync("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--data-binary", "x".repeat(5000), `http://127.0.0.1:${port}/big.json`], { encoding: "utf8" });
+    ok(r.stdout === "413", `oversize body is aborted mid-stream with 413 (got ${r.stdout || "no response"})`);
+    ok(!fs.existsSync(path.join(dir, "big.json")), "aborted oversize body is never written to disk");
+  } finally {
+    sink.kill();
+  }
+}
+
+console.log(failed ? `\n❌ cli-selftest: ${failed} assertion(s) failed — a tool contract regressed.` : `\n✓ cli-selftest: tool contracts hold (validated input, self-describing errors, safe paths).`);
+process.exit(failed ? 1 : 0);

package/tools/extract-fonts.js

@@ -0,0 +1,133 @@
+/**
+ * extract-fonts.js — reusable web-font extractor
+ * ------------------------------------------------
+ * Paste this whole file into the DevTools Console on ANY site (or run it via a
+ * browser-automation `javascript_tool`). It:
+ *   1. Reads every @font-face rule in the page's stylesheets.
+ *   2. Fetches each font binary from its real (CORS-permitting) URL.
+ *   3. Bundles them into ONE zip (single download — dodges Chrome's
+ *      "multiple automatic downloads" block) named "<host>-fonts.zip".
+ *   4. Also drops a ready-to-use fonts.css into the same zip.
+ *
+ * Filter which families to grab with the optional argument:
+ *   extractFonts()                      // all families
+ *   extractFonts(/proxima|arquitecta/i) // only matching families
+ *
+ * Notes:
+ *  - Only fonts whose CDN allows cross-origin fetch (most do, incl. Typekit)
+ *    will download; others are reported as errors but don't stop the run.
+ *  - These are usually licensed fonts. Use for local testing only; don't
+ *    redistribute or ship on a public site without a license.
+ */
+async function extractFonts(familyFilter = null) {
+  // ---- minimal store-mode ZIP writer (no deps) ----
+  const crcTable = (() => {
+    const t = [];
+    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;
+  })();
+  const crc32 = (u8) => {
+    let c = 0xffffffff;
+    for (let i = 0; i < u8.length; i++) c = crcTable[(c ^ u8[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const u16 = (n) => [n & 255, (n >> 8) & 255];
+  const u32 = (n) => [n & 255, (n >> 8) & 255, (n >> 16) & 255, (n >> 24) & 255];
+
+  function buildZip(files) {
+    const enc = new TextEncoder();
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    for (const f of files) {
+      const nb = enc.encode(f.name);
+      const crc = crc32(f.data);
+      const sz = f.data.length;
+      const head = [0x50, 0x4b, 3, 4, ...u16(20), ...u16(0), ...u16(0), ...u16(0),
+        ...u16(0), ...u32(crc), ...u32(sz), ...u32(sz), ...u16(nb.length), ...u16(0)];
+      const arr = new Uint8Array(head.length + nb.length + sz);
+      arr.set(head, 0); arr.set(nb, head.length); arr.set(f.data, head.length + nb.length);
+      chunks.push(arr);
+      central.push({ nb, crc, sz, offset });
+      offset += arr.length;
+    }
+    const cd = [];
+    let cdSize = 0;
+    for (const c of central) {
+      const rec = [0x50, 0x4b, 1, 2, ...u16(20), ...u16(20), ...u16(0), ...u16(0),
+        ...u16(0), ...u16(0), ...u32(c.crc), ...u32(c.sz), ...u32(c.sz),
+        ...u16(c.nb.length), ...u16(0), ...u16(0), ...u16(0), ...u16(0),
+        ...u32(0), ...u32(c.offset)];
+      const arr = new Uint8Array(rec.length + c.nb.length);
+      arr.set(rec, 0); arr.set(c.nb, rec.length);
+      cd.push(arr); cdSize += arr.length;
+    }
+    const eocd = new Uint8Array([0x50, 0x4b, 5, 6, ...u16(0), ...u16(0),
+      ...u16(files.length), ...u16(files.length), ...u32(cdSize), ...u32(offset), ...u16(0)]);
+    return new Blob([...chunks, ...cd, eocd], { type: 'application/zip' });
+  }
+
+  // ---- 1. collect @font-face rules ----
+  const faces = [];
+  for (const sheet of document.styleSheets) {
+    let rules;
+    try { rules = sheet.cssRules; } catch (e) { continue; } // skip cross-origin sheets
+    if (!rules) continue;
+    for (const r of rules) {
+      if (!(r.constructor && r.constructor.name === 'CSSFontFaceRule')) continue;
+      const family = (r.style.getPropertyValue('font-family') || '').replace(/["']/g, '').trim();
+      if (familyFilter && !familyFilter.test(family)) continue;
+      const weight = r.style.getPropertyValue('font-weight') || '400';
+      const style = r.style.getPropertyValue('font-style') || 'normal';
+      const src = r.style.getPropertyValue('src') || '';
+      // prefer woff2, fall back to first url()
+      const m = src.match(/url\(["']?([^"')]+)["']?\)\s*format\(["']?woff2["']?\)/i)
+        || src.match(/url\(["']?([^"')]+)["']?\)/i);
+      if (!m) continue;
+      const ext = (m[1].match(/\.(woff2|woff|ttf|otf)(?:[?#]|$)/i) || [, 'woff2'])[1].toLowerCase();
+      const safeFam = (family || 'font').replace(/[^a-z0-9]+/gi, '-').toLowerCase();
+      faces.push({
+        family, weight, style, url: m[1],
+        name: `${safeFam}-${weight}-${style}.${ext}`,
+      });
+    }
+  }
+  if (!faces.length) { console.warn('No matching @font-face rules found.'); return; }
+
+  // ---- 2. fetch binaries ----
+  const files = [];
+  const errors = [];
+  for (const f of faces) {
+    try {
+      const buf = await (await fetch(f.url, { mode: 'cors' })).arrayBuffer();
+      files.push({ name: f.name, data: new Uint8Array(buf), face: f });
+    } catch (e) {
+      errors.push(`${f.name}: ${e.message}`);
+    }
+  }
+
+  // ---- 3. generate fonts.css ----
+  const css = files.map(({ face, name }) =>
+    `@font-face {\n  font-family: "${face.family}";\n  font-weight: ${face.weight};\n  font-style: ${face.style};\n  src: url("./${name}") format("woff2");\n  font-display: swap;\n}`
+  ).join('\n\n') + '\n';
+  files.push({ name: 'fonts.css', data: new TextEncoder().encode(css) });
+
+  // ---- 4. single download ----
+  const host = location.hostname.replace(/^www\./, '');
+  const blob = buildZip(files);
+  const a = document.createElement('a');
+  a.href = URL.createObjectURL(blob);
+  a.download = `${host}-fonts.zip`;
+  document.body.appendChild(a); a.click(); a.remove();
+
+  console.log(`✅ ${files.length - 1} font(s) zipped → ${a.download} (${blob.size} bytes)`);
+  if (errors.length) console.warn('⚠️ skipped (CORS/other):\n' + errors.join('\n'));
+  return { downloaded: files.length - 1, errors };
+}
+
+// Auto-run when pasted directly; comment out if you only want the function defined.
+extractFonts();

package/tools/extract-icons.js

@@ -0,0 +1,255 @@
+/**
+ * extract-icons.js — reusable web-icon extractor (sibling of fonts/extract-fonts.js)
+ * ----------------------------------------------------------------------------------
+ * Paste this whole file into the DevTools Console on ANY site (or run it via a
+ * browser-automation `javascript_tool`). It finds icons however the site ships
+ * them and bundles them into ONE zip (single download — dodges Chrome's
+ * "multiple automatic downloads" block) named "<host>-icons.zip":
+ *
+ *   icons/<name>.svg   one standalone SVG per icon (inline <svg>, sprite <use>,
+ *                      data-URI background/mask, <img src=*.svg>)
+ *   icons.css          ready-to-use classes; CSS-background icons keep their
+ *                      EXACT original data-URI so they render byte-identically
+ *   preview.html       a gallery of everything captured, with names
+ *   report.json        what was captured, by which method, plus anything skipped
+ *
+ * Usage:
+ *   extractIcons()                 // whole page
+ *   extractIcons('header')         // limit to a CSS selector (scope)
+ *   extractIcons('header', /22|24/)// scope + only icons whose viewBox/size matches
+ *
+ * Notes:
+ *  - Icon FONTS (Font Awesome, Material Icons, etc.) can't be turned into SVGs
+ *    here — they're glyphs in a webfont. They're listed in report.json; grab the
+ *    font itself with fonts/extract-fonts.js.
+ *  - External (cross-origin) SVG URLs are fetched best-effort; CORS failures are
+ *    recorded in report.json rather than aborting the run.
+ */
+async function extractIcons(scope = null, filter = null) {
+  const root = scope ? document.querySelector(scope) || document.body : document.body;
+  const SVG_NS = "http://www.w3.org/2000/svg";
+
+  // ---------- minimal store-mode ZIP writer (no deps) ----------
+  const crcTable = (() => {
+    const t = [];
+    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;
+  })();
+  const crc32 = (u8) => {
+    let c = 0xffffffff;
+    for (let i = 0; i < u8.length; i++) c = crcTable[(c ^ u8[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const u16 = (n) => [n & 255, (n >> 8) & 255];
+  const u32 = (n) => [n & 255, (n >> 8) & 255, (n >> 16) & 255, (n >> 24) & 255];
+  function buildZip(files) {
+    const enc = new TextEncoder();
+    const chunks = [], central = [];
+    let offset = 0;
+    for (const f of files) {
+      const data = typeof f.data === "string" ? enc.encode(f.data) : f.data;
+      const nb = enc.encode(f.name), crc = crc32(data), sz = data.length;
+      const head = [0x50, 0x4b, 3, 4, ...u16(20), ...u16(0), ...u16(0), ...u16(0),
+        ...u16(0), ...u32(crc), ...u32(sz), ...u32(sz), ...u16(nb.length), ...u16(0)];
+      const arr = new Uint8Array(head.length + nb.length + sz);
+      arr.set(head, 0); arr.set(nb, head.length); arr.set(data, head.length + nb.length);
+      chunks.push(arr); central.push({ nb, crc, sz, offset }); offset += arr.length;
+    }
+    const cd = []; let cdSize = 0;
+    for (const c of central) {
+      const rec = [0x50, 0x4b, 1, 2, ...u16(20), ...u16(20), ...u16(0), ...u16(0),
+        ...u16(0), ...u16(0), ...u32(c.crc), ...u32(c.sz), ...u32(c.sz),
+        ...u16(c.nb.length), ...u16(0), ...u16(0), ...u16(0), ...u16(0), ...u32(0), ...u32(c.offset)];
+      const arr = new Uint8Array(rec.length + c.nb.length);
+      arr.set(rec, 0); arr.set(c.nb, rec.length); cd.push(arr); cdSize += arr.length;
+    }
+    const eocd = new Uint8Array([0x50, 0x4b, 5, 6, ...u16(0), ...u16(0),
+      ...u16(files.length), ...u16(files.length), ...u32(cdSize), ...u32(offset), ...u16(0)]);
+    return new Blob([...chunks, ...cd, eocd], { type: "application/zip" });
+  }
+
+  // ---------- helpers ----------
+  const used = new Set();
+  const slug = (s) =>
+    (s || "icon").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "icon";
+  const uniqName = (base) => {
+    let n = slug(base), i = 2;
+    while (used.has(n)) n = `${slug(base)}-${i++}`;
+    used.add(n);
+    return n;
+  };
+  // best label for an element: aria-label > title > icon-ish class > tag
+  const labelFor = (el) => {
+    const a = el.closest("a,button,[aria-label],[title]");
+    const lbl = a?.getAttribute("aria-label") || a?.getAttribute("title") || el.getAttribute("aria-label");
+    if (lbl) return lbl;
+    const cls = [...el.classList].find((c) => /icon|ico|svg|glyph/i.test(c));
+    if (cls) return cls.replace(/icon|ico|static|svg/gi, "");
+    return el.tagName.toLowerCase();
+  };
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0 && r.width <= 200 && r.height <= 200;
+  };
+  // normalize an svg string for dedup
+  const norm = (s) => s.replace(/\s+/g, " ").replace(/>\s+</g, "><").trim();
+  const seen = new Set();
+
+  const svgFiles = [];   // {name, svg}
+  const cssIcons = [];   // {name, w, h, bg}  (background/mask data-URIs kept verbatim)
+  const report = { host: location.hostname, captured: [], skipped: [] };
+
+  function pushSvg(svgStr, label, method) {
+    if (filter && !filter.test(`${label} ${svgStr}`)) return null; // optional viewBox/size/name filter
+    const n = norm(svgStr);
+    if (seen.has(n)) return null;
+    seen.add(n);
+    const name = uniqName(label);
+    svgFiles.push({ name: `icons/${name}.svg`, svg: svgStr });
+    report.captured.push({ name, method });
+    return name;
+  }
+
+  // ---------- 1. inline <svg> (skip the giant logo? no — keep everything small) ----------
+  for (const svg of root.querySelectorAll("svg")) {
+    if (!visible(svg)) continue;
+    if (svg.querySelector("use")) continue; // handled by sprite pass
+    const clone = svg.cloneNode(true);
+    if (!clone.getAttribute("xmlns")) clone.setAttribute("xmlns", SVG_NS);
+    pushSvg(clone.outerHTML, labelFor(svg), "inline-svg");
+  }
+
+  // ---------- 2. sprite <use href="#id"> ----------
+  for (const use of root.querySelectorAll("use")) {
+    const svg = use.closest("svg");
+    if (!svg || !visible(svg)) continue;
+    const href = use.getAttribute("href") || use.getAttribute("xlink:href") || "";
+    const id = href.startsWith("#") ? href.slice(1) : href.split("#")[1];
+    if (!id) continue;
+    const sym = document.getElementById(id);
+    if (!sym) { report.skipped.push({ label: labelFor(svg), reason: `sprite ref #${id} not found in DOM` }); continue; }
+    const vb = sym.getAttribute("viewBox") || svg.getAttribute("viewBox") || "0 0 24 24";
+    const out = `<svg xmlns="${SVG_NS}" viewBox="${vb}">${sym.innerHTML}</svg>`;
+    pushSvg(out, labelFor(svg), "sprite-use");
+  }
+
+  // ---------- 3. CSS background-image / mask-image (data-URI or external) ----------
+  // strips the FULL data-URI prefix up to the first comma (handles
+  // `data:image/svg+xml,`, `;charset=utf-8,`, `;base64,`, etc.)
+  const decodeDataSvg = (uri) => {
+    const comma = uri.indexOf(",");
+    if (comma < 0) return null;
+    const meta = uri.slice(0, comma), body = uri.slice(comma + 1);
+    if (/;base64/i.test(meta)) { try { return atob(body); } catch { return null; } }
+    try { return decodeURIComponent(body); } catch { return body; }
+  };
+  for (const el of root.querySelectorAll("*")) {
+    if (!visible(el)) continue;
+    const cs = getComputedStyle(el);
+    const mask = cs.maskImage && cs.maskImage !== "none" ? cs.maskImage
+      : cs.webkitMaskImage && cs.webkitMaskImage !== "none" ? cs.webkitMaskImage : null;
+    const pick = mask || (cs.backgroundImage !== "none" ? cs.backgroundImage : null);
+    if (!pick) continue;
+    const m = pick.match(/url\((['"]?)(.*?)\1\)/s);
+    if (!m) continue;
+    const uri = m[2];
+    const r = el.getBoundingClientRect();
+    const w = Math.round(r.width), h = Math.round(r.height);
+    const label = labelFor(el);
+
+    if (uri.startsWith("data:image/svg")) {
+      const svg = decodeDataSvg(uri);
+      if (svg && svg.includes("<svg")) {
+        const name = pushSvg(svg, label, mask ? "css-mask" : "css-background");
+        // keep the exact original URI for a pixel-perfect CSS class too
+        if (name) cssIcons.push({ name, w: w || null, h: h || null, bg: pick, recolor: mask ? cs.backgroundColor : null });
+      }
+    } else if (/\.svg(\?|#|$)/i.test(uri)) {
+      // external svg — best-effort fetch
+      try {
+        const txt = await (await fetch(uri, { mode: "cors" })).text();
+        if (txt.includes("<svg")) {
+          const name = pushSvg(txt, label, "external-svg");
+          if (name) cssIcons.push({ name, w: w || null, h: h || null, bg: `url("./icons/${name}.svg")` });
+        }
+      } catch (e) { report.skipped.push({ label, reason: "external svg fetch failed (CORS)" }); }
+    }
+  }
+
+  // ---------- 4. <img src="*.svg"> ----------
+  for (const img of root.querySelectorAll("img")) {
+    if (!visible(img)) continue;
+    const src = img.currentSrc || img.src || "";
+    if (!/\.svg(\?|#|$)/i.test(src) && !src.startsWith("data:image/svg")) continue;
+    try {
+      let txt;
+      if (src.startsWith("data:image/svg")) txt = decodeDataSvg(src);
+      else txt = await (await fetch(src, { mode: "cors" })).text();
+      if (txt && txt.includes("<svg")) pushSvg(txt, labelFor(img) || img.alt, "img-svg");
+    } catch (e) { report.skipped.push({ label: img.alt || "img", reason: "img svg fetch failed (CORS)" }); }
+  }
+
+  // ---------- 5. detect (but can't extract) icon fonts ----------
+  const iconFontEls = new Set();
+  for (const el of root.querySelectorAll("*")) {
+    const fam = getComputedStyle(el).fontFamily || "";
+    if (/font ?awesome|material icons|material symbols|ionicons|glyphicon|feather|remixicon/i.test(fam)) {
+      iconFontEls.add(fam.split(",")[0].replace(/["']/g, "").trim());
+    }
+  }
+  if (iconFontEls.size)
+    report.skipped.push({ label: [...iconFontEls].join(", "), reason: "icon font — extract the webfont with extract-fonts.js instead" });
+
+  if (!svgFiles.length) {
+    console.warn("No extractable icons found on this page.", report);
+    return report;
+  }
+
+  // ---------- assemble icons.css ----------
+  let css = "/* " + location.hostname + " icons — generated by extract-icons.js */\n";
+  css += ".icon{display:inline-block;background-repeat:no-repeat;background-position:center;background-size:contain}\n";
+  for (const ic of cssIcons) {
+    const dims = (ic.w ? `width:${ic.w}px;` : "") + (ic.h ? `height:${ic.h}px;` : "");
+    const recolor = ic.recolor && ic.recolor !== "rgba(0, 0, 0, 0)"
+      ? `background-color:${ic.recolor};-webkit-mask:${ic.bg} center/contain no-repeat;mask:${ic.bg} center/contain no-repeat;`
+      : `background-image:${ic.bg};`;
+    css += `.icon-${ic.name}{${dims}${recolor}}\n`;
+  }
+
+  // ---------- preview.html ----------
+  const cards = svgFiles.map((f) => {
+    const nm = f.name.replace("icons/", "").replace(".svg", "");
+    return `<figure><div class="box">${f.svg}</div><figcaption>${nm}</figcaption></figure>`;
+  }).join("\n");
+  const preview = `<!doctype html><meta charset=utf8><title>${location.hostname} icons</title>
+<style>body{font:14px system-ui;padding:24px;background:#fff;color:#111}
+h1{font-size:18px}.grid{display:flex;flex-wrap:wrap;gap:16px;margin-top:16px}
+figure{margin:0;width:120px;text-align:center}.box{height:60px;display:grid;place-items:center;border:1px solid #eee;border-radius:8px}
+.box svg{width:28px;height:28px}figcaption{margin-top:6px;font-size:11px;color:#555;word-break:break-all}</style>
+<h1>${svgFiles.length} icons from ${location.hostname}</h1><div class=grid>${cards}</div>`;
+
+  // ---------- build + download one zip ----------
+  const files = [
+    ...svgFiles.map((f) => ({ name: f.name, data: f.svg })),
+    { name: "icons.css", data: css },
+    { name: "preview.html", data: preview },
+    { name: "report.json", data: JSON.stringify(report, null, 2) },
+  ];
+  const host = location.hostname.replace(/^www\./, "");
+  const blob = buildZip(files);
+  const a = document.createElement("a");
+  a.href = URL.createObjectURL(blob);
+  a.download = `${host}-icons.zip`;
+  document.body.appendChild(a); a.click(); a.remove();
+
+  console.log(`✅ ${svgFiles.length} icon(s) → ${a.download} (${blob.size} bytes)`);
+  if (report.skipped.length) console.warn("⚠️ skipped:", report.skipped);
+  return report;
+}
+
+// Auto-run when pasted directly; comment out to only define the function.
+extractIcons();

package/tools/merge-snapshot.js

@@ -0,0 +1,56 @@
+// tools/merge-snapshot.js <full.json> <partial.json> — fold a PARTIAL re-capture into a
+// full snapshot, for the fix-loop's inner iterations.
+//
+// WHY: the slow half of a verification round is the browser capture, not the diff — and
+// after a one-element fix, re-capturing all N targets to re-run a gate wastes minutes per
+// iteration (astryx: 35-target full captures for single-region fixes, dozens of times).
+// Capture ONLY the affected targets instead (`pxSend(url, subsetTargets)`), then fold them
+// in here: elements present in the partial overwrite their counterparts in the full file;
+// everything else carries over. Gates then run on the merged file in seconds.
+//
+// HONESTY CONTRACT: a merged snapshot is an ITERATION artifact, not a proof — the
+// carried-over elements' measurements are only as fresh as the last full capture, and a fix
+// can shift things outside the subset you re-measured (astryx's bento-height fix moved the
+// FOOTER). So every merge stamps `merged:{at,keys}` into the snapshot root, and the `done`
+// gate REFUSES stamped snapshots: one final full capture (which clears the stamp by
+// overwriting the file) is always required before a clone can claim done.
+//
+// Refuses on viewport-width or compat-mode mismatch (a partial captured at a different
+// width/mode would silently poison x-positions — same rule as the diff itself).
+//
+// USAGE
+//   node tools/merge-snapshot.js targets/<name>/clone.json partial.json
+"use strict";
+
+const fs = require("fs");
+
+function mergeSnapshots(full, partial) {
+  if (!partial.elements || !Object.keys(partial.elements).length) return { error: "partial snapshot has no elements — nothing to merge" };
+  if (full.viewport && partial.viewport && full.viewport.width !== partial.viewport.width)
+    return { error: `viewport widths differ (full=${full.viewport.width} vs partial=${partial.viewport.width}) — a partial captured at another width would poison x-positions; re-capture` };
+  if (full.mode && partial.mode && full.mode !== partial.mode)
+    return { error: `document modes differ (full=${full.mode} vs partial=${partial.mode}) — quirks/standards mismatch (LEARNINGS #18); re-capture` };
+  const keys = Object.keys(partial.elements);
+  for (const k of keys) full.elements[k] = partial.elements[k];
+  const prior = (full.merged && full.merged.keys) || [];
+  full.merged = { at: new Date().toISOString(), keys: [...new Set([...prior, ...keys])] };
+  return { keys, carried: Object.keys(full.elements).length - keys.length };
+}
+
+function main() {
+  const [fullPath, partialPath] = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  if (!fullPath || !partialPath) { console.error("usage: node tools/merge-snapshot.js <full.json> <partial.json>"); process.exit(2); }
+  let full, partial;
+  try { full = JSON.parse(fs.readFileSync(fullPath, "utf8")); } catch (e) { console.error(`cannot read ${fullPath}: ${e.message}`); process.exit(1); }
+  try { partial = JSON.parse(fs.readFileSync(partialPath, "utf8")); } catch (e) { console.error(`cannot read ${partialPath}: ${e.message}`); process.exit(1); }
+  const r = mergeSnapshots(full, partial);
+  if (r.error) { console.error(`❌ ${r.error}`); process.exit(1); }
+  fs.writeFileSync(fullPath, JSON.stringify(full, null, 2));
+  console.log(`✓ merged ${r.keys.length} element(s) into ${fullPath} (${r.carried} carried over from the last full capture)
+  updated: ${r.keys.join(", ")}
+  ⚠ ITERATION artifact — the file is stamped merged:{at,keys}; the done gate refuses stamped
+  snapshots, so take one FULL capture before advancing done (it overwrites the stamp).`);
+}
+
+if (require.main === module) main();
+module.exports = { mergeSnapshots };