@mmerterden/dev-toolkit-mcp 2.24.1

package/tools/design-check/visual-compare.js

@@ -0,0 +1,961 @@
+/**
+ * design_visual_compare - generalized visual comparison of a Figma render
+ * against a live device screenshot. Unlike ios_visual_diff it does NOT fail on
+ * size mismatch: it normalizes scale and (optionally) crops device chrome, then
+ * reports three finding families:
+ *   - pixel    : perceptual diff percentage (pixelmatch)
+ *   - spacing/size/position : px deltas between matched Figma vs live elements
+ *   - color    : ΔE between the Figma fill and the sampled live pixels
+ *   - typography: expected font size/family from the Figma spec (advisory)
+ *
+ * Pure JS (pngjs + pixelmatch, both already deps). No native image libs.
+ */
+
+import { readFileSync, writeFileSync } from "fs";
+import { detectCardinalityMismatch, demoteCardinalityNoise } from "./content-cardinality.js";
+import { join } from "path";
+
+let PNG, pixelmatch;
+async function ensureLibs() {
+  if (PNG && pixelmatch) return;
+  ({ PNG } = await import("pngjs"));
+  pixelmatch = (await import("pixelmatch")).default;
+}
+
+function readPng(path) { return PNG.sync.read(readFileSync(path)); }
+
+function cropTop(png, px) {
+  if (!px || px <= 0) return png;
+  const h = Math.max(1, png.height - px);
+  const out = new PNG({ width: png.width, height: h });
+  for (let y = 0; y < h; y++) {
+    const s = ((y + px) * png.width) * 4;
+    const d = (y * png.width) * 4;
+    png.data.copy(out.data, d, s, s + png.width * 4);
+  }
+  return out;
+}
+
+// Crop an arbitrary rectangle, in PIXELS, clamped to the image.
+function cropRect(png, r) {
+  const x = Math.max(0, Math.min(png.width - 1, Math.round(r.x)));
+  const y = Math.max(0, Math.min(png.height - 1, Math.round(r.y)));
+  const w = Math.max(1, Math.min(png.width - x, Math.round(r.w)));
+  const h = Math.max(1, Math.min(png.height - y, Math.round(r.h)));
+  const out = new PNG({ width: w, height: h });
+  for (let row = 0; row < h; row++) {
+    const s = ((y + row) * png.width + x) * 4;
+    const d = (row * w) * 4;
+    png.data.copy(out.data, d, s, s + w * 4);
+  }
+  return out;
+}
+
+// Bilinear resize of an RGBA PNG to (dw, dh).
+function resize(png, dw, dh) {
+  const out = new PNG({ width: dw, height: dh });
+  const { width: sw, height: sh, data: src } = png;
+  const xr = sw / dw, yr = sh / dh;
+  for (let y = 0; y < dh; y++) {
+    const sy = Math.min(sh - 1, y * yr);
+    const y0 = Math.floor(sy), y1 = Math.min(sh - 1, y0 + 1), wy = sy - y0;
+    for (let x = 0; x < dw; x++) {
+      const sx = Math.min(sw - 1, x * xr);
+      const x0 = Math.floor(sx), x1 = Math.min(sw - 1, x0 + 1), wx = sx - x0;
+      const di = (y * dw + x) * 4;
+      for (let c = 0; c < 4; c++) {
+        const p00 = src[(y0 * sw + x0) * 4 + c], p10 = src[(y0 * sw + x1) * 4 + c];
+        const p01 = src[(y1 * sw + x0) * 4 + c], p11 = src[(y1 * sw + x1) * 4 + c];
+        const top = p00 + (p10 - p00) * wx, bot = p01 + (p11 - p01) * wx;
+        out.data[di + c] = Math.round(top + (bot - top) * wy);
+      }
+    }
+  }
+  return out;
+}
+
+function drawRect(png, x, y, w, h, [r, g, b], thickness = 3) {
+  const { width, height, data } = png;
+  const put = (px, py) => {
+    if (px < 0 || py < 0 || px >= width || py >= height) return;
+    const i = (py * width + px) * 4;
+    data[i] = r; data[i + 1] = g; data[i + 2] = b; data[i + 3] = 255;
+  };
+  for (let t = 0; t < thickness; t++) {
+    for (let px = x; px < x + w; px++) { put(px, y + t); put(px, y + h - 1 - t); }
+    for (let py = y; py < y + h; py++) { put(x + t, py); put(x + w - 1 - t, py); }
+  }
+}
+
+function sampleColor(png, x, y, w, h) {
+  const { width, height, data } = png;
+  let r = 0, g = 0, b = 0, n = 0;
+  const x0 = Math.max(0, x), y0 = Math.max(0, y);
+  const x1 = Math.min(width, x + w), y1 = Math.min(height, y + h);
+  const step = Math.max(1, Math.floor(Math.min(x1 - x0, y1 - y0) / 12));
+  for (let py = y0; py < y1; py += step) {
+    for (let px = x0; px < x1; px += step) {
+      const i = (py * width + px) * 4;
+      if (data[i + 3] < 128) continue;
+      r += data[i]; g += data[i + 1]; b += data[i + 2]; n++;
+    }
+  }
+  if (!n) return null;
+  return { r: r / n, g: g / n, b: b / n };
+}
+
+// Text colour cannot be read from a box average: a label's box is mostly
+// background, so the mean returns the background and every font-colour check
+// silently passes. Instead take the ink - the pixels furthest in luminance from
+// the box's dominant (background) tone - and average only those.
+function sampleInkColor(png, x, y, w, h) {
+  const { width, height, data } = png;
+  const x0 = Math.max(0, x), y0 = Math.max(0, y);
+  const x1 = Math.min(width, x + w), y1 = Math.min(height, y + h);
+  if (x1 <= x0 || y1 <= y0) return null;
+  const px = [];
+  for (let py = y0; py < y1; py++) {
+    for (let pxx = x0; pxx < x1; pxx++) {
+      const i = (py * width + pxx) * 4;
+      if (data[i + 3] < 128) continue;
+      const R = data[i], G = data[i + 1], B = data[i + 2];
+      px.push([R, G, B, 0.2126 * R + 0.7152 * G + 0.0722 * B]);
+    }
+  }
+  if (px.length < 8) return null;
+  // Dominant tone = median luminance (the background fills most of the box).
+  const lums = px.map((p) => p[3]).sort((a, b) => a - b);
+  const bg = lums[Math.floor(lums.length / 2)];
+  // Ink = the decile furthest from the background tone.
+  const scored = px.map((p) => [p, Math.abs(p[3] - bg)]).sort((a, b) => b[1] - a[1]);
+  const take = Math.max(4, Math.floor(scored.length * 0.1));
+  let r = 0, g = 0, b = 0;
+  for (let k = 0; k < take; k++) { r += scored[k][0][0]; g += scored[k][0][1]; b += scored[k][0][2]; }
+  const ink = { r: r / take, g: g / take, b: b / take };
+  const contrast = Math.abs((0.2126 * ink.r + 0.7152 * ink.g + 0.0722 * ink.b) - bg);
+  // Too little separation means the box holds no readable ink (icon-only, image,
+  // or an empty container) - reporting a colour there would be a guess.
+  return contrast < 12 ? null : ink;
+}
+
+/**
+ * Where a full-width row visually starts and ends, measured from the PIXELS.
+ *
+ * A Figma node tree reports the INSTANCE wrapper (often full-bleed, x=0
+ * w=frameWidth) while an accessibility tree reports the VISIBLE card inside it.
+ * Comparing one against the other manufactures an inset finding on a screen that
+ * is actually correct - the single largest source of false positives in this
+ * audit. Reading both sides off their own renders removes the mismatch: whatever
+ * the node tree claims, the pixels agree on where the card's edge is.
+ *
+ * Returns { left, right } in frame POINTS, or null when the row is uniform
+ * (nothing drawn on it) and there is no edge to find.
+ */
+function visualRowInsets(png, yPt, frameWPt, frameHPt, tol = 18) {
+  const { width: W, height: H, data } = png;
+  const y = Math.round(yPt * (H / frameHPt));
+  if (y < 0 || y >= H) return null;
+  const at = (x) => { const i = (y * W + x) * 4; return [data[i], data[i + 1], data[i + 2]]; };
+  const bg = at(Math.min(2, W - 1));
+  const differs = (c) => Math.abs(c[0] - bg[0]) + Math.abs(c[1] - bg[1]) + Math.abs(c[2] - bg[2]) > tol;
+  let L = -1, R = -1;
+  for (let x = 0; x < W; x++) if (differs(at(x))) { L = x; break; }
+  if (L < 0) return null;
+  for (let x = W - 1; x >= 0; x--) if (differs(at(x))) { R = x; break; }
+  const sx = W / frameWPt;
+  return { left: L / sx, right: (W - 1 - R) / sx };
+}
+
+/**
+ * The four distances from a box to whatever actually bounds it - the same thing
+ * an on-device layout inspector shows when you select an element ("57pt above,
+ * 89pt below, 12pt each side").
+ *
+ * For each direction: the nearest sibling that overlaps on the perpendicular
+ * axis, else the frame edge. This is the measurement that answers "is it built
+ * 1:1", because it is LOCAL: it does not change when the mock fixture adds a row
+ * somewhere else on the screen, which is exactly what made absolute Y useless.
+ *
+ * Pure geometry over a flat box list, so the identical function runs on the
+ * design spec and on the live geometry - no per-project knowledge, and nothing
+ * that needs to run inside the app.
+ */
+function edgeContext(box, all, frameW, frameH) {
+  const b = { l: box.x, r: box.x + box.w, t: box.y, b: box.y + box.h };
+  const others = all.filter((o) => o !== box);
+  const vOverlap = (o) => Math.min(b.b, o.y + o.h) - Math.max(b.t, o.y) > 1;
+  const hOverlap = (o) => Math.min(b.r, o.x + o.w) - Math.max(b.l, o.x) > 1;
+
+  let left = b.l, leftRef = "frame";
+  for (const o of others) {
+    if (!vOverlap(o)) continue;
+    const or = o.x + o.w;
+    if (or <= b.l + 1) { const d = b.l - or; if (d < left) { left = d; leftRef = o.label || "sibling"; } }
+  }
+  let right = frameW - b.r, rightRef = "frame";
+  for (const o of others) {
+    if (!vOverlap(o)) continue;
+    if (o.x >= b.r - 1) { const d = o.x - b.r; if (d < right) { right = d; rightRef = o.label || "sibling"; } }
+  }
+  let top = b.t, topRef = "frame";
+  for (const o of others) {
+    if (!hOverlap(o)) continue;
+    const ob = o.y + o.h;
+    if (ob <= b.t + 1) { const d = b.t - ob; if (d < top) { top = d; topRef = o.label || "sibling"; } }
+  }
+  let bottom = frameH != null ? frameH - b.b : Infinity, bottomRef = "frame";
+  for (const o of others) {
+    if (!hOverlap(o)) continue;
+    if (o.y >= b.b - 1) { const d = o.y - b.b; if (d < bottom) { bottom = d; bottomRef = o.label || "sibling"; } }
+  }
+  return { left, right, top, bottom, leftRef, rightRef, topRef, bottomRef };
+}
+
+/**
+ * Copy conformance against the design's source-of-truth UX writing.
+ *
+ * A frame render is a stale picture of the words; the authoritative strings are
+ * the design's UX-writing annotations. Comparing against those lets a real copy
+ * defect ("Soyad" where the design says "Soyadı") be reported as a defect, rather
+ * than being lost in a perceptual diff that only says "these pixels differ".
+ *
+ * Matching is deliberately asymmetric. An EXACT live match verifies the string. A
+ * NEAR match is the interesting case: a near miss is almost always a truncated or
+ * stale translation rather than an unrelated element. A string with no plausible
+ * counterpart is reported as absent and advisory, because this capture may simply
+ * not show the state or scroll position that carries it - never silently dropped.
+ */
+function normCopy(s) {
+  return (s || "").toLowerCase()
+    .replace(/[‘’']/g, "'").replace(/[“”]/g, '"')
+    .replace(/\s+/g, " ").trim();
+}
+function similarity(a, b) {
+  a = normCopy(a); b = normCopy(b);
+  if (!a || !b) return 0;
+  if (a === b) return 1;
+  // Token overlap plus prefix credit: enough to tell a truncated string from an
+  // unrelated one without pulling in an edit-distance dependency.
+  const at = new Set(a.split(" ")), bt = new Set(b.split(" "));
+  let shared = 0;
+  for (const t of at) if (bt.has(t)) shared++;
+  const overlap = shared / Math.max(at.size, bt.size);
+  const longer = a.length >= b.length ? a : b;
+  const shorter = a.length >= b.length ? b : a;
+  const prefix = longer.startsWith(shorter) ? shorter.length / longer.length : 0;
+  return Math.max(overlap, prefix);
+}
+
+export function compareCopy(designStrings, liveTexts, { nearThreshold = 0.75 } = {}) {
+  const findings = [];
+  const live = (liveTexts || []).filter(Boolean);
+  const wants = (designStrings || []).filter(Boolean);
+
+  // One live string answers ONE design string. Without that, a single label can be
+  // offered as the near-match for several unrelated design strings, and a loose
+  // threshold then turns "not on this screen" into a fabricated copy defect.
+  // Exact matches claim their counterpart first, then near matches take what is
+  // left, strongest pair first.
+  const claimed = new Set();
+  const exact = new Map();
+  wants.forEach((want) => {
+    const i = live.findIndex((l, idx) => !claimed.has(idx) && normCopy(l) === normCopy(want));
+    if (i >= 0) { claimed.add(i); exact.set(want, live[i]); }
+  });
+
+  const candidates = [];
+  for (const want of wants) {
+    if (exact.has(want)) continue;
+    live.forEach((l, idx) => {
+      if (claimed.has(idx)) return;
+      const sc = similarity(want, l);
+      if (sc >= nearThreshold) candidates.push({ want, l, idx, sc });
+    });
+  }
+  candidates.sort((a, b) => b.sc - a.sc);
+  const near = new Map();
+  for (const c of candidates) {
+    if (near.has(c.want) || claimed.has(c.idx)) continue;
+    near.set(c.want, { text: c.l, sc: c.sc });
+    claimed.add(c.idx);
+  }
+
+  for (const want of wants) {
+    if (exact.has(want)) {
+      findings.push({
+        type: "copy", category: "localization", status: "verified",
+        element: want, detail: "on-spec", expected: want, actual: want,
+      });
+      continue;
+    }
+    const hit = near.get(want);
+    const best = hit && hit.text, bestScore = hit ? hit.sc : 0;
+    if (best) {
+      findings.push({
+        type: "copy", category: "localization", element: want,
+        detail: `design UX writing "${want}" renders as "${best}"`,
+        expected: want, actual: best, similarity: Number(bestScore.toFixed(2)),
+      });
+    } else {
+      findings.push({
+        type: "copy", category: "localization", element: want, advisory: true,
+        detail: `design UX writing "${want}" not found on this screen - advisory: this capture may not show the state or scroll position that carries it`,
+        expected: want, actual: "(not on screen)",
+      });
+    }
+  }
+  return findings;
+}
+
+function hexToRgb(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex || "");
+  if (!m) return null;
+  const v = parseInt(m[1], 16);
+  return { r: (v >> 16) & 255, g: (v >> 8) & 255, b: v & 255 };
+}
+function rgbToHex({ r, g, b }) {
+  const h = (v) => Math.round(v).toString(16).padStart(2, "0");
+  return `#${h(r)}${h(g)}${h(b)}`.toUpperCase();
+}
+function srgbToLin(c) { c /= 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); }
+function rgbToLab({ r, g, b }) {
+  const R = srgbToLin(r), G = srgbToLin(g), B = srgbToLin(b);
+  let x = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;
+  let y = (R * 0.2126 + G * 0.7152 + B * 0.0722);
+  let z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+  const f = (t) => t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+  x = f(x); y = f(y); z = f(z);
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+function deltaE(c1, c2) {
+  const a = rgbToLab(c1), b = rgbToLab(c2);
+  return Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+}
+
+function norm(s) { return (s || "").trim().toLowerCase().replace(/\s+/g, " "); }
+
+// Figma spec fields arrive under a few spellings depending on how the caller
+// flattened the node tree.
+function fe_fontSize(m) {
+  const fe = m.fe || {};
+  return fe.fontSize || fe.font_size || (fe.style && fe.style.fontSize) || null;
+}
+
+// Match figma spec elements to live geometry by text/label, else skip.
+function autoPair(figmaSpec, liveGeom) {
+  const pairs = [];
+  const used = new Set();
+  const liveByText = new Map();
+  liveGeom.forEach((el, i) => {
+    const k = norm(el.text || el.label);
+    if (k && !liveByText.has(k)) liveByText.set(k, i);
+  });
+  for (const fe of figmaSpec) {
+    const k = norm(fe.text || fe.label);
+    if (!k) continue;
+    const i = liveByText.get(k);
+    if (i !== undefined && !used.has(i)) { used.add(i); pairs.push({ figma: fe, live: liveGeom[i] }); }
+  }
+  return pairs;
+}
+
+export async function compareVisual(opts) {
+  await ensureLibs();
+  const {
+    figmaPng, livePng, outDir,
+    cropTopLive = 0, cropTopFigma = 0,
+    figmaSpec = [], liveGeometry = [], pairs: givenPairs = null,
+    figmaFrame = null, liveScreen = null,
+    liveRegion = null, expectedRegion = null,
+    tolerancePx = 2, colorTolerance = 3, perceptualPrecision = 0.1, maxDiffPct = 1.0,
+    // Measure edge insets + inter-element gaps in points instead of raw
+    // width/height in a stretched compare space. On by default: a device and a
+    // Figma frame of different widths make raw size deltas meaningless.
+    responsive = true,
+    relations = true,
+    edges = true,
+    designCopy = null,
+    tolerancePt = null,
+    verifyFontFamily = false,
+    contentCardinality = true,
+    label = "screen",
+  } = opts;
+
+  let figma = readPng(figmaPng);
+  let live = readPng(livePng);
+  const rawLiveW = live.width, rawLiveH = live.height;   // before crop, for unit conversion
+  if (cropTopFigma) figma = cropTop(figma, cropTopFigma);
+
+  // A bottom sheet / modal / partial overlay has a Figma frame covering only the
+  // sheet, while the live capture is the whole screen. Stretching the full screen
+  // onto a sheet-shaped frame misplaces every element inside it, so the deltas
+  // become noise and a real edge inset hides in it. Cropping the live capture to
+  // the sheet's own bounds first makes the two comparable, and then a side inset
+  // is a plain width/position delta.
+  //
+  // liveRegion is in liveScreen units (iOS points / Android px); the PNG is in
+  // device pixels, hence the density conversion.
+  let regionOrigin = { x: 0, y: 0 };
+  let regionSize = null;
+  if (liveRegion) {
+    const dx = (liveScreen && liveScreen.w > 0) ? rawLiveW / liveScreen.w : 1;
+    const dy = (liveScreen && liveScreen.h > 0) ? rawLiveH / liveScreen.h : 1;
+    live = cropRect(live, {
+      x: liveRegion.x * dx, y: liveRegion.y * dy,
+      w: liveRegion.w * dx, h: liveRegion.h * dy,
+    });
+    regionOrigin = { x: liveRegion.x, y: liveRegion.y };
+    regionSize = { w: liveRegion.w, h: liveRegion.h };
+  } else if (cropTopLive) {
+    live = cropTop(live, cropTopLive);
+  }
+
+  const W = figma.width, H = figma.height;               // compare in Figma render space
+  const liveResized = resize(live, W, H);
+
+  // Pixel diff
+  const diff = new PNG({ width: W, height: H });
+  const diffPixels = pixelmatch(figma.data, liveResized.data, diff.data, W, H, {
+    threshold: perceptualPrecision, includeAA: false,
+  });
+  const perceptualPct = parseFloat(((diffPixels / (W * H)) * 100).toFixed(4));
+
+  // Coordinate scales into the compare (Figma render) space.
+  // liveScreen + geometry are in the platform's native unit (iOS points, Android px),
+  // but cropTopLive is in live-screenshot PIXELS - convert it to liveScreen units first
+  // so the y-axis math never mixes points and pixels.
+  const cropUnits = liveRegion
+    ? 0                                                  // the region crop already excluded chrome
+    : ((liveScreen && rawLiveH > 0) ? cropTopLive * (liveScreen.h / rawLiveH) : cropTopLive);
+  const fScale = (figmaFrame && figmaFrame.w > 0) ? W / figmaFrame.w : 1;
+  // With a region, live coordinates are rebased onto the region's own box; without
+  // one they map from the whole (top-cropped) screen.
+  const lSpanX = regionSize ? regionSize.w : (liveScreen ? liveScreen.w : 0);
+  const lSpanY = regionSize ? regionSize.h : (liveScreen ? liveScreen.h - cropUnits : 0);
+  const lScaleX = lSpanX > 0 ? W / lSpanX : 1;
+  const lScaleY = lSpanY > 0 ? H / lSpanY : 1;
+
+  const findings = [];
+
+  // The sheet's own edge insets. Inside a region-aligned comparison the sheet fills
+  // the frame by construction, so a gap between the sheet and the screen edge can
+  // only be caught here - and a design that shows the sheet flush is not satisfied
+  // by one that floats inset from the edges.
+  if (liveRegion && expectedRegion) {
+    const gaps = {
+      left: Math.round(liveRegion.x - expectedRegion.x),
+      right: Math.round((expectedRegion.x + expectedRegion.w) - (liveRegion.x + liveRegion.w)),
+      top: Math.round(liveRegion.y - expectedRegion.y),
+      bottom: Math.round((expectedRegion.y + expectedRegion.h) - (liveRegion.y + liveRegion.h)),
+    };
+    for (const [edge, d] of Object.entries(gaps)) {
+      if (Math.abs(d) > tolerancePx) {
+        findings.push({
+          type: "inset", category: "padding", element: `${label} container`,
+          region: { x: 0, y: 0, w: W, h: H },
+          detail: `${edge} edge inset off by ${d >= 0 ? "+" : ""}${d}pt`,
+          expected: `${edge} ${edge === "left" || edge === "top" ? expectedRegion[edge === "left" ? "x" : "y"] : 0}pt`,
+          actual: `${edge} ${edge === "left" ? liveRegion.x : edge === "top" ? liveRegion.y : Math.abs(d)}pt`,
+          deltaPx: { [edge]: d },
+        });
+      }
+    }
+  }
+  const pairs = givenPairs && givenPairs.length ? givenPairs : autoPair(figmaSpec, liveGeometry);
+
+  const overlay = new PNG({ width: W, height: H });
+  liveResized.data.copy(overlay.data);
+
+  const RED = [227, 24, 55], AMBER = [230, 160, 20];
+
+  // ── Responsive measurement basis ────────────────────────────────────────────
+  // The device and the Figma frame are rarely the same width (e.g. 402pt vs
+  // 375pt). Comparing raw widths across them manufactures deltas: a full-bleed
+  // 375pt design container vs a 402pt-wide screen's 370pt card reads as "-29px
+  // too narrow" when nothing is wrong. Worse, a container whose height follows
+  // its content turns every fixture difference into a "size" finding.
+  //
+  // So measure what is actually device-independent and what a designer specs:
+  //   - edge insets (left / right) in points
+  //   - the gaps BETWEEN consecutive elements in points
+  //   - typography (size / family / colour)
+  // A 16pt margin is 16pt on both sides of the comparison, whatever the frame
+  // width. Raw width/height stay available but as clearly-labelled advisories.
+  const designW = figmaFrame && figmaFrame.w > 0 ? figmaFrame.w : null;
+  const liveW = regionSize ? regionSize.w : (liveScreen && liveScreen.w > 0 ? liveScreen.w : null);
+  const canResolveInsets = responsive && designW && liveW;
+  const tolPt = tolerancePt != null ? tolerancePt : tolerancePx;
+
+  // Point-space geometry per pair, plus the compare-space box used for drawing.
+  const measured = pairs.filter((p) => p && p.figma && p.live).map(({ figma: fe, live: le }) => {
+    const d = { x: fe.x, y: fe.y, w: fe.w, h: fe.h };
+    const l = {
+      x: le.x - regionOrigin.x,
+      y: le.y - regionOrigin.y - cropUnits,
+      w: le.w, h: le.h,
+    };
+    return {
+      fe, le, d, l,
+      name: fe.label || fe.text || fe.identifier || "element",
+      box: {
+        x: Math.round(l.x * lScaleX), y: Math.round(l.y * lScaleY),
+        w: Math.round(l.w * lScaleX), h: Math.round(l.h * lScaleY),
+      },
+    };
+  });
+
+  // Resolve each full-width row's real edges from the pixels ONCE, and let every
+  // check read the same answer. Doing it per-check is how the inset check ended
+  // up pixel-correct while the centring and symmetry checks stayed fooled by the
+  // same wrapper-vs-visible mismatch, reporting a phantom on a correct screen.
+  // A stretching element's width is device-dependent, so its horizontal insets
+  // are only meaningful against its PARENT, never the frame: a button 16pt inside
+  // a modal keeps 16pt on any screen width, while its distance to the frame edge
+  // changes with both the device and the modal's own width. Reference the frame
+  // and a perfectly on-spec button reads as off.
+  //
+  // Parenthood is recovered geometrically - the smallest box that fully contains
+  // this one - so it needs no project knowledge and works on either side.
+  const containerOf = (box, all) => {
+    let best = null;
+    for (const o of all) {
+      if (o === box) continue;
+      const contains = o.x <= box.x + 1 && o.y <= box.y + 1 &&
+        o.x + o.w >= box.x + box.w - 1 && o.y + o.h >= box.y + box.h - 1;
+      if (!contains) continue;
+      if (o.w * o.h <= box.w * box.h) continue;
+      if (!best || o.w * o.h < best.w * best.h) best = o;
+    }
+    return best;
+  };
+  {
+    const dAll = measured.map((m) => ({ ...m.d, label: m.name }));
+    const lAll = measured.map((m) => ({ ...m.l, label: m.name }));
+    measured.forEach((m, i) => {
+      m.dParent = containerOf(dAll[i], dAll);
+      m.lParent = containerOf(lAll[i], lAll);
+    });
+  }
+
+  const designWpx = figmaFrame && figmaFrame.w > 0 ? figmaFrame.w : null;
+  const liveWpx = regionSize ? regionSize.w : (liveScreen && liveScreen.w > 0 ? liveScreen.w : null);
+  for (const m of measured) {
+    m.px = null;
+    if (!responsive || !designWpx || !liveWpx) continue;
+    if (!(m.d.w >= designWpx * 0.8 && m.l.w >= liveWpx * 0.8)) continue;
+    const vf = visualRowInsets(figma, m.d.y + m.d.h / 2, designWpx, figmaFrame.h);
+    const vl = visualRowInsets(live, m.l.y + m.l.h / 2, liveWpx, liveScreen.h);
+    if (vf && vl) m.px = { design: vf, live: vl };
+  }
+
+  const flaggedBoxes = new Set();
+  const flag = (m) => flaggedBoxes.add(m);
+
+  // Measurements are in points now, so `deltaPt` is the accurate field. Keep a
+  // `deltaPx` alias so callers written against the older shape keep working.
+  const pushMeasured = (f) => {
+    if (f.deltaPt && !f.deltaPx) f.deltaPx = f.deltaPt;
+    findings.push(f);
+  };
+
+  for (const m of measured) {
+    const { d, l, name, box } = m;
+    const region = box;
+
+    // Vertical placement is directly comparable in points - both are measured
+    // from the top of the same screen.
+    const dTop = Math.round(l.y - d.y);
+    if (Math.abs(dTop) > tolPt) {
+      // Absolute Y is shifted by everything above it, so a different mock
+      // fixture moves it without anything being wrong. The real vertical
+      // signals are the sibling GAP and the relational checks below; keep this
+      // as context only.
+      pushMeasured({
+        type: "spacing", category: "spacing", element: name, region, advisory: true,
+        detail: `top offset ${l.y.toFixed(0)}pt vs design ${d.y.toFixed(0)}pt (${dTop >= 0 ? "+" : ""}${dTop}pt) - advisory: absolute Y moves with the content above it; see the gap/alignment findings`,
+        expected: `top ${d.y.toFixed(0)}pt`, actual: `top ${l.y.toFixed(0)}pt`,
+        deltaPt: { y: dTop },
+      });
+    }
+
+    // Edge insets - the responsive-safe replacement for a raw width delta.
+    if (canResolveInsets) {
+      let dInsetL, dInsetR, insetRDesign, insetRLive, insetLDesign = d.x, insetLLive = l.x, src = "geometry";
+
+      // For a row that spans (nearly) the whole frame, trust the pixels over the
+      // two geometry sources: the design side is usually an instance wrapper and
+      // the live side the visible card, and that mismatch alone invents a ~16pt
+      // inset on a conformant screen.
+      const vf = m.px && m.px.design, vl = m.px && m.px.live;
+      // Nested in a container on BOTH sides -> measure against it, and the two
+      // sides become directly comparable whatever the device width.
+      if (m.dParent && m.lParent) {
+        insetLDesign = m.d.x - m.dParent.x;
+        insetLLive = m.l.x - m.lParent.x;
+        insetRDesign = (m.dParent.x + m.dParent.w) - (m.d.x + m.d.w);
+        insetRLive = (m.lParent.x + m.lParent.w) - (m.l.x + m.l.w);
+        src = `parent ${m.dParent.label || "container"}`;
+      } else if (vf && vl) {
+        insetLDesign = vf.left; insetLLive = vl.left;
+        insetRDesign = vf.right; insetRLive = vl.right;
+        src = "pixels";
+      } else {
+        insetRDesign = designW - (d.x + d.w);
+        insetRLive = liveW - (l.x + l.w);
+      }
+      dInsetL = Math.round(insetLLive - insetLDesign);
+      dInsetR = Math.round(insetRLive - insetRDesign);
+      if (Math.abs(dInsetL) > tolPt) {
+        pushMeasured({
+          type: "inset", category: "padding", element: name, region, measuredFrom: src,
+          advisory: !(src === "pixels" || src.startsWith("parent")),
+          detail: `left inset ${insetLLive.toFixed(0)}pt vs design ${insetLDesign.toFixed(0)}pt (${dInsetL >= 0 ? "+" : ""}${dInsetL}pt, ${src})` + ((src === "pixels" || src.startsWith("parent")) ? "" : " - advisory: no pixel confirmation, one side may be a wrapper box and the other a glyph run"),
+          expected: `left ${insetLDesign.toFixed(0)}pt`, actual: `left ${insetLLive.toFixed(0)}pt`,
+          deltaPt: { left: dInsetL },
+        });
+        flag(m);
+      }
+      if (Math.abs(dInsetR) > tolPt) {
+        pushMeasured({
+          type: "inset", category: "padding", element: name, region, measuredFrom: src,
+          advisory: !(src === "pixels" || src.startsWith("parent")),
+          detail: `right inset ${insetRLive.toFixed(0)}pt vs design ${insetRDesign.toFixed(0)}pt (${dInsetR >= 0 ? "+" : ""}${dInsetR}pt, ${src})` + ((src === "pixels" || src.startsWith("parent")) ? "" : " - advisory: no pixel confirmation, one side may be a wrapper box and the other a glyph run"),
+          expected: `right ${insetRDesign.toFixed(0)}pt`, actual: `right ${insetRLive.toFixed(0)}pt`,
+          deltaPt: { right: dInsetR },
+        });
+        flag(m);
+      }
+    } else {
+      const dW = Math.round(l.w - d.w);
+      if (Math.abs(dW) > tolPt) {
+        pushMeasured({
+          type: "size", category: "size", element: name, region,
+          detail: `width ${l.w.toFixed(0)}pt vs design ${d.w.toFixed(0)}pt (${dW >= 0 ? "+" : ""}${dW}pt)`,
+          expected: `${d.w.toFixed(0)}pt`, actual: `${l.w.toFixed(0)}pt`, deltaPt: { w: dW },
+        });
+        flag(m);
+      }
+    }
+
+    // Height is reported, but a container that hugs its content changes height
+    // whenever the fixture returns a different number of rows - which is not a
+    // design defect. Mark it advisory so it never outranks a real inset/gap.
+    const dH = Math.round(l.h - d.h);
+    if (Math.abs(dH) > tolPt) {
+      pushMeasured({
+        type: "height", category: "size", element: name, region, advisory: true,
+        detail: `height ${l.h.toFixed(0)}pt vs design ${d.h.toFixed(0)}pt (${dH >= 0 ? "+" : ""}${dH}pt) - advisory: content-driven height differs when the fixture differs`,
+        expected: `${d.h.toFixed(0)}pt`, actual: `${l.h.toFixed(0)}pt`, deltaPt: { h: dH },
+      });
+    }
+
+    // ── Typography ───────────────────────────────────────────────────────────
+    // Font size is not exposed by the accessibility tree, so infer it from the
+    // rendered line box only when the design says how tall one line should be.
+    if (fe_fontSize(m)) {
+      const want = fe_fontSize(m);
+      const designLine = d.h;
+      if (designLine > 0) {
+        const impliedPt = (l.h / designLine) * want;
+        const dPt = impliedPt - want;
+        if (Math.abs(dPt) > Math.max(1, want * 0.12)) {
+          pushMeasured({
+            type: "font-size", category: "font size", element: name, region,
+            detail: `line box implies ~${impliedPt.toFixed(1)}pt vs design ${want}pt${m.fe.fontFamily ? ` (${m.fe.fontFamily})` : ""}`,
+            expected: `${want}pt${m.fe.fontFamily ? ` ${m.fe.fontFamily}` : ""}`,
+            actual: `~${impliedPt.toFixed(1)}pt`,
+          });
+          flag(m);
+        }
+      }
+    }
+    // Font family cannot be measured from the device; surface it as a spec value
+    // to verify in code rather than inventing a delta.
+    if (m.fe.fontFamily && verifyFontFamily) {
+      pushMeasured({
+        type: "font-family", category: "typography", element: name, region, advisory: true,
+        detail: `design font family ${m.fe.fontFamily} - not readable from the device, verify in code`,
+        expected: m.fe.fontFamily, actual: "not measurable",
+      });
+    }
+    // Colour: text uses the ink sampler, filled boxes the box average.
+    if (m.fe.color) {
+      const want = hexToRgb(m.fe.color);
+      const isText = !!(m.fe.text || m.fe.fontSize);
+      const got = isText
+        ? sampleInkColor(liveResized, box.x, box.y, box.w, box.h)
+        : sampleColor(liveResized, box.x, box.y, box.w, box.h);
+      if (want && got) {
+        const dE = deltaE(want, got);
+        if (dE > colorTolerance) {
+          pushMeasured({
+            type: "color", category: isText ? "font color" : "color", element: name, region,
+            detail: `${isText ? "text" : "fill"} colour ΔE ${dE.toFixed(1)} - expected ${rgbToHex(want)}, got ${rgbToHex(got)}`,
+            expected: rgbToHex(want), actual: rgbToHex(got), deltaE: parseFloat(dE.toFixed(1)),
+          });
+          flag(m);
+        }
+      }
+    }
+  }
+
+  // ── Edge context: the on-device-inspector measurement, both sides ──────────
+  // Run the identical local-distance algorithm over the design boxes and the
+  // live boxes, then compare direction by direction. A row that moved because
+  // the fixture above it grew keeps its OWN four distances, so it stays silent -
+  // while a padding or gap that genuinely changed shows up on the exact edge
+  // that changed, naming what it is measured against.
+  if (edges && canResolveInsets) {
+    const dAll = measured.map((m) => ({ ...m.d, label: m.name }));
+    const lAll = measured.map((m) => ({ ...m.l, label: m.name }));
+    for (let i = 0; i < measured.length; i++) {
+      const m = measured[i];
+      const dc = edgeContext(dAll[i], dAll, designW, figmaFrame ? figmaFrame.h : null);
+      const lc = edgeContext(lAll[i], lAll, liveW, liveScreen ? liveScreen.h : null);
+      for (const side of ["left", "right", "top", "bottom"]) {
+        const dv = dc[side], lv = lc[side];
+        if (!Number.isFinite(dv) || !Number.isFinite(lv)) continue;
+        const delta = Math.round(lv - dv);
+        if (Math.abs(delta) <= tolPt) continue;
+        // Report only what no other check already covers, or the same fact lands
+        // in the report two and three times over:
+        //   - left/right to the FRAME  -> `inset` does it, and does it from the
+        //     pixels, so it is not fooled by a wrapper-vs-visible mismatch
+        //   - top/bottom to a SIBLING  -> `gap` is exactly this measurement
+        //   - top/bottom to the FRAME  -> not local (handled as advisory below)
+        // What is left, and genuinely new, is the horizontal distance between
+        // two siblings: an icon-to-label or label-to-divider gap.
+        const toFrame = dc[`${side}Ref`] === "frame" || lc[`${side}Ref`] === "frame";
+        const horizontal = side === "left" || side === "right";
+        if (!horizontal || toFrame) continue;
+        // Only compare like against like: a distance measured to a sibling in the
+        // design but to the frame in live is a different quantity.
+        const dRef = dc[`${side}Ref`], lRef = lc[`${side}Ref`];
+        // A trailing edge sits closer purely because the element itself grew, so
+        // an element whose own size already differs would otherwise have that one
+        // fact reported twice - once as size, again as padding.
+        // A right edge sits closer purely because the element itself grew, which
+        // is already reported as size.
+        const ownSizeDiffers = side === "right" &&
+          Math.abs(m.l.w - m.d.w) > tolPt;
+        const sameRef = dRef === lRef && !ownSizeDiffers;
+        pushMeasured({
+          type: "edge", category: "padding", element: m.name, region: m.box,
+          advisory: !sameRef,
+          detail: `${side} distance ${lv.toFixed(0)}pt vs design ${dv.toFixed(0)}pt (${delta >= 0 ? "+" : ""}${delta}pt), measured to ${lRef}` +
+            (sameRef ? "" : ownSizeDiffers
+              ? " - advisory: explained by this element's own size difference, already reported as size"
+              : ` in live but to ${dRef} in design - not comparable, advisory only`),
+          expected: `${side} ${dv.toFixed(0)}pt to ${dRef}`,
+          actual: `${side} ${lv.toFixed(0)}pt to ${lRef}`,
+          deltaPt: { [side]: delta },
+        });
+        if (sameRef) flag(m);
+      }
+    }
+  }
+
+  // ── Relational checks: is it built 1:1? ────────────────────────────────────
+  // Absolute positions answer the wrong question. Two screens showing the same
+  // component with different mock content put it at different Y, so an absolute
+  // delta flags a conformant screen and hides a real one. What actually says
+  // "1:1" is intrinsic and content-independent:
+  //   - is it the same distance from the edge?
+  //   - is it still centred?
+  //   - are the things that shared a centre line still sharing it?
+  //   - is the icon still the size it was?
+  // Each is computed the same way on BOTH sides and only the DIFFERENCE is a
+  // finding - so a 247pt design text container vs a 78pt live glyph box (the
+  // same text, measured differently) stays silent, while a 28pt icon rendered at
+  // 24pt does not.
+  if (relations && canResolveInsets) {
+    const midX = (b) => b.x + b.w / 2;
+    const midY = (b) => b.y + b.h / 2;
+
+    for (const m of measured) {
+      const { d, l, name, box } = m;
+
+      // Centred in the frame: compare the OFFSET FROM CENTRE, not the position.
+      // Prefer the pixel edges - a wrapper box is trivially centred and a live AX
+      // union rarely is, which invents an off-centre finding on a correct screen.
+      const dEdge = m.px ? m.px.design : { left: d.x, right: designW - (d.x + d.w) };
+      const lEdge = m.px ? m.px.live : { left: l.x, right: liveW - (l.x + l.w) };
+      const offD = (dEdge.left - dEdge.right) / 2;
+      const offL = (lEdge.left - lEdge.right) / 2;
+      const wasCentred = Math.abs(offD) <= tolPt;
+      if (wasCentred && Math.abs(offL) > tolPt) {
+        pushMeasured({
+          type: "alignment", category: "padding", element: name, region: box,
+          detail: `design centres this in the frame; live is ${Math.abs(offL).toFixed(0)}pt off centre`,
+          expected: "centred", actual: `${offL >= 0 ? "+" : "-"}${Math.abs(offL).toFixed(0)}pt off centre`,
+          deltaPt: { centre: Math.round(offL - offD) },
+        });
+        flag(m);
+      }
+
+      // Symmetric side margins - a designer's "equal padding" intent.
+      const symD = Math.abs(dEdge.left - dEdge.right);
+      const symL = Math.abs(lEdge.left - lEdge.right);
+      if (symD <= tolPt && symL > tolPt) {
+        pushMeasured({
+          type: "alignment", category: "padding", element: name, region: box,
+          detail: `design keeps left/right margins equal; live differs by ${symL.toFixed(0)}pt`,
+          expected: "left margin = right margin", actual: `${symL.toFixed(0)}pt apart`,
+          deltaPt: { symmetry: Math.round(symL - symD) },
+        });
+        flag(m);
+      }
+
+      // Icon / control sizing is fixed by the design, never by content - so
+      // unlike a container's height this is a real deviation, not an advisory.
+      const isSmall = d.w <= 64 && d.h <= 64;
+      if (isSmall) {
+        const dW = Math.round(l.w - d.w), dH = Math.round(l.h - d.h);
+        if (Math.abs(dW) > tolPt || Math.abs(dH) > tolPt) {
+          pushMeasured({
+            type: "icon-size", category: "size", element: name, region: box,
+            detail: `${l.w.toFixed(0)}x${l.h.toFixed(0)}pt vs design ${d.w.toFixed(0)}x${d.h.toFixed(0)}pt` +
+                    (l.w < 44 || l.h < 44 ? " - also under the 44pt minimum tap target" : ""),
+            expected: `${d.w.toFixed(0)}x${d.h.toFixed(0)}pt`, actual: `${l.w.toFixed(0)}x${l.h.toFixed(0)}pt`,
+            deltaPt: { w: dW, h: dH },
+          });
+          flag(m);
+        }
+      }
+    }
+
+    // Shared centre lines: elements the design puts on one axis must stay on one
+    // axis. This is how "is the X aligned with the title" gets checked without
+    // caring where either of them sits on screen.
+    for (let i = 0; i < measured.length; i++) {
+      for (let j = i + 1; j < measured.length; j++) {
+        const a = measured[i], b = measured[j];
+        const sharedY = Math.abs(midY(a.d) - midY(b.d)) <= tolPt;
+        if (sharedY) {
+          const liveOff = Math.abs(midY(a.l) - midY(b.l));
+          if (liveOff > tolPt) {
+            pushMeasured({
+              type: "alignment", category: "spacing",
+              element: `${a.name} ↔ ${b.name}`, region: b.box,
+              detail: `design puts these on one horizontal centre line; live is ${liveOff.toFixed(0)}pt apart`,
+              expected: "same centre-y", actual: `${liveOff.toFixed(0)}pt apart`,
+              deltaPt: { centreY: Math.round(liveOff) },
+            });
+            flag(b);
+          }
+        }
+      }
+    }
+  }
+
+  // ── Gaps between consecutive elements ──────────────────────────────────────
+  // "text ↔ divider" spacing is what a designer actually specifies, and it is
+  // invariant to frame width. Walk the pairs in design order and compare the
+  // vertical gap each side leaves between neighbours.
+  const ordered = [...measured].sort((a, b) => a.d.y - b.d.y);
+  for (let i = 0; i + 1 < ordered.length; i++) {
+    const a = ordered[i], b = ordered[i + 1];
+    const gapDesign = b.d.y - (a.d.y + a.d.h);
+    const gapLive = b.l.y - (a.l.y + a.l.h);
+    if (gapDesign < -1 || gapLive < -1) continue;          // overlapping / nested - not a gap
+    const dGap = Math.round(gapLive - gapDesign);
+    if (Math.abs(dGap) > tolPt) {
+      pushMeasured({
+        type: "gap", category: "spacing",
+        element: `${a.name} → ${b.name}`,
+        region: { x: b.box.x, y: Math.round((a.box.y + a.box.h + b.box.y) / 2), w: b.box.w, h: Math.max(4, b.box.y - (a.box.y + a.box.h)) },
+        detail: `gap ${gapLive.toFixed(0)}pt vs design ${gapDesign.toFixed(0)}pt (${dGap >= 0 ? "+" : ""}${dGap}pt)`,
+        expected: `${gapDesign.toFixed(0)}pt`, actual: `${gapLive.toFixed(0)}pt`,
+        deltaPt: { gap: dGap },
+      });
+    }
+  }
+
+  for (const m of flaggedBoxes) drawRect(overlay, m.box.x, m.box.y, m.box.w, m.box.h, RED, 3);
+
+  // Write images
+  const stamp = `${norm(label).replace(/[^a-z0-9]+/g, "-") || "screen"}`;
+  const paths = {};
+  const write = (name, png) => { const p = join(outDir, `${stamp}-${name}.png`); writeFileSync(p, PNG.sync.write(png)); return p; };
+  paths.figma = write("figma", figma);
+  paths.live = write("live", live);              // NATIVE aspect (cropped) - undistorted display
+  paths.liveNormalized = write("live-norm", liveResized);
+  paths.diff = write("diff", diff);
+  paths.overlay = write("overlay", overlay);
+
+  // Side-by-side: figma | live | overlay
+  const gap = 24;
+  const sbs = new PNG({ width: W * 3 + gap * 2, height: H });
+  sbs.data.fill(255);
+  const blit = (src, offX) => {
+    for (let y = 0; y < H; y++) {
+      const s = (y * W) * 4;
+      const d = (y * sbs.width + offX) * 4;
+      src.data.copy(sbs.data, d, s, s + W * 4);
+    }
+  };
+  blit(figma, 0); blit(liveResized, W + gap); blit(overlay, (W + gap) * 2);
+  paths.sideBySide = write("side-by-side", sbs);
+
+  // Copy is compared against the design's UX writing, not the frame render.
+  if (designCopy && designCopy.length) {
+    const liveTexts = liveGeometry.map((e) => e.text || e.label).filter(Boolean);
+    for (const f of compareCopy(designCopy, liveTexts)) findings.push(f);
+  }
+
+  // Content-cardinality demotion (gaps doc section 1). A design frame carries
+  // whatever the mock fixture produced, so 5 design rows against 3 live rows makes
+  // every container height and downstream position differ for a reason that is not
+  // a defect. Detected from the element lists and applied LAST, after every finding
+  // exists, so the same rule sees all of them.
+  //
+  // Nothing is deleted: affected geometry findings become advisory with a shared
+  // rootCause, which is already excluded from the deviation count and rendered
+  // under "DO NOT CHANGE". Copy / colour / typography / tap-target findings and
+  // anything above the first differing group are never touched - see
+  // content-cardinality.js for the full rule set and why it is written this way.
+  //
+  // Opt out with contentCardinality:false to see the raw findings.
+  let cardinality = { mismatch: false, groups: [], boundaryY: null };
+  let cardinalityDemoted = 0;
+  if (contentCardinality) {
+    cardinality = detectCardinalityMismatch(figmaSpec, liveGeometry);
+    if (cardinality.mismatch) {
+      const res = demoteCardinalityNoise(findings, cardinality);
+      findings.length = 0;
+      findings.push(...res.findings);
+      cardinalityDemoted = res.demoted;
+    }
+  }
+
+  // Advisories (content-driven height, unmeasurable font family) must not decide
+  // pass/fail - otherwise a fixture with one extra row fails a conformant screen.
+  const deviations = findings.filter((f) => !f.advisory);
+  const passed = perceptualPct <= maxDiffPct && deviations.length === 0;
+  return {
+    label, passed,
+    // Reported so a demotion is never silent: a run can say what it set aside and
+    // why, which is the difference between suppressing noise and hiding findings.
+    contentCardinality: {
+      mismatch: cardinality.mismatch,
+      groups: cardinality.groups,
+      demoted: cardinalityDemoted,
+    },
+    perceptualPct, diffPixels, maxDiffPct,
+    findingCount: findings.length,
+    deviationCount: deviations.length,
+    advisoryCount: findings.length - deviations.length,
+    findings,
+    images: paths,
+    compareSize: `${W}x${H}`,
+    liveSize: `${live.width}x${live.height}`,
+    measurement: {
+      mode: canResolveInsets ? "responsive (points)" : "absolute (points)",
+      designFrameW: designW, liveFrameW: liveW,
+      tolerancePt: tolPt,
+      note: canResolveInsets
+        ? "Edge insets and inter-element gaps measured in points; raw width suppressed because the design frame and the device differ in width. Height is advisory."
+        : "figmaFrame/liveScreen width missing - fell back to absolute point deltas.",
+    },
+  };
+}