@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/compare.mjs

@@ -0,0 +1,985 @@
+// The comparison side of `yarn luma parity` (parity/run.mjs): what the browser
+// measured on their page and on ours (parity/probe.mjs), turned into checks,
+// differences, scores and a verdict. Pure functions, no browser, no I/O:
+// Luma's unit tests run them on fixed inputs.
+//
+// Values are computed styles as the browser returned them, whole: a
+// difference shows both strings in full (a `box-shadow` cut after its first
+// layer reads Tailwind's transparent ring and nothing else). Numbers are
+// compared with a tolerance per kind: px for lengths and boxes, CIEDE2000 for
+// colours (alpha apart), exact for everything else.
+//
+// Every difference has an owner (parity/owner.mjs): the template's (an agent
+// fixes it: `findings`, ranked) or the data's (the client's: the catalog, the
+// API). The verdict is the convergence of the template: its score at or over
+// the target, no CRITICAL or MAJOR template difference, the map's coverage.
+import { attribute, decide } from './owner.mjs';
+
+/** Tolerances (the map's `tolerance` overrides each). */
+export const TOLERANCE = Object.freeze({
+  /** Lengths and boxes, in CSS px: layout positions are multiples of 1/64 px, rounding stays under this. */
+  px: 0.5,
+  /** CIEDE2000: about 2.3 is a just noticeable difference. */
+  deltaE: 2.3,
+  /** Alpha channel, 0-1: a translucent colour and an opaque one are different findings. */
+  alpha: 0.02,
+  /** Per-pixel colour threshold of the pixel diff (pixelmatch's `threshold`, 0-1). */
+  pixel: 0.1,
+  /** Share of a component's pixels allowed to differ before the pixel diff counts as a difference. */
+  pixels: 0.02,
+});
+
+/** Weights of the score: a property is one check; a missing element or a wrong column count weighs this much. */
+export const WEIGHT = Object.freeze({ check: 1, critical: 5, pixels: 2 });
+
+/**
+ * Severities: CRITICAL (a missing or extra element, a text, a column count),
+ * MAJOR (any other property out of tolerance), MINOR (what a shopper hardly
+ * sees: a box off by at most 1px, a colour within ΔE 5 of theirs, the
+ * pointer, a transition, the pixel share, a second signal). The convergence
+ * verdict ends when no CRITICAL or MAJOR template difference remains.
+ */
+export const MINOR = Object.freeze({ px: 1, deltaE: 5, props: ['cursor', 'transition'], gap: 2 });
+/** The space between consecutive siblings of a repeated part (facet groups, facet values, tiles): MINOR up to MINOR.gap px, then MAJOR. */
+export const SIBLING = Object.freeze(['sibling-row-gap', 'sibling-column-gap']);
+const BOX = new Set(['x', 'y', 'width', 'height']);
+/** MINOR, by the rule above. @param {string} prop @param {{ delta: string, px?: number, deltaE?: number } | null} d */
+export const isMinor = (prop, d) => {
+  if (!d) return false;
+  if (MINOR.props.includes(prop)) return true;
+  if (SIBLING.includes(prop)) return d.px != null && d.px <= MINOR.gap;
+  if (BOX.has(prop) || ['columnGap', 'rowGap', 'itemWidth'].includes(prop)) return d.px != null && d.px <= MINOR.px;
+  if (kindOf(prop) === 'color') return d.deltaE != null && d.deltaE <= MINOR.deltaE && !/alpha/.test(d.delta);
+  return false;
+};
+const weightOf = (severity) => (severity === 'critical' ? WEIGHT.critical : WEIGHT.check);
+
+// ------------------------------------------------------------------ properties
+
+/** The computed properties measured on every element (longhands: what a shorthand hides is read on its own). */
+export const PROPS = Object.freeze([
+  'font-family', 'font-size', 'font-weight', 'font-style', 'line-height', 'letter-spacing', 'word-spacing',
+  'text-transform', 'text-align', 'white-space', 'text-overflow', '-webkit-line-clamp', 'font-variant-numeric',
+  'text-decoration-line', 'text-decoration-style', 'text-decoration-color', 'text-decoration-thickness',
+  'color', 'background-color', 'background-image', 'opacity', 'visibility', 'filter',
+  'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+  'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style',
+  'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+  'border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius',
+  'box-shadow', 'text-shadow', 'outline-style', 'outline-width', 'outline-color',
+  'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+  'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+  'display', 'position', 'flex-direction', 'flex-wrap', 'align-items', 'justify-content', 'row-gap', 'column-gap',
+  'grid-template-columns', 'object-fit', 'object-position', 'aspect-ratio', 'overflow-x', 'overflow-y',
+  'transform', 'transition', 'cursor',
+]);
+
+const COLOR = new Set(['color', 'background-color', 'text-decoration-color', 'outline-color', 'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color']);
+const SHADOW = new Set(['box-shadow', 'text-shadow']);
+const LENGTH = new Set([
+  'font-size', 'line-height', 'letter-spacing', 'word-spacing', 'text-decoration-thickness', 'outline-width', 'row-gap', 'column-gap',
+  'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+  'border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius',
+  'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+]);
+/** What a property is compared as. @param {string} prop */
+export const kindOf = (prop) =>
+  COLOR.has(prop) ? 'color' : SHADOW.has(prop) ? 'shadow' : LENGTH.has(prop) ? 'length' : prop === 'font-family' ? 'family' : prop === 'grid-template-columns' ? 'tracks' : prop === 'transform' ? 'transform' : 'string';
+
+/** Property groups, for the report's wording and for `ignore` (a group name ignores all of it). */
+export const GROUPS = Object.freeze({
+  font: ['font-family', 'font-size', 'font-weight', 'font-style', 'line-height', 'letter-spacing', 'word-spacing', 'text-transform', 'text-align', 'white-space', 'text-overflow', '-webkit-line-clamp', 'font-variant-numeric', 'rendered-font'],
+  decoration: ['text-decoration-line', 'text-decoration-style', 'text-decoration-color', 'text-decoration-thickness'],
+  colour: ['color', 'background-color', 'background-image', 'opacity', 'filter'],
+  border: ['border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width', 'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style', 'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color', 'outline-style', 'outline-width', 'outline-color'],
+  radius: ['border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius'],
+  shadow: ['box-shadow', 'text-shadow'],
+  spacing: ['padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left', 'row-gap', 'column-gap', 'sibling-row-gap', 'sibling-column-gap', 'sibling-direction'],
+  layout: ['display', 'position', 'flex-direction', 'flex-wrap', 'align-items', 'justify-content', 'grid-template-columns', 'object-fit', 'object-position', 'aspect-ratio', 'overflow-x', 'overflow-y', 'visibility'],
+  motion: ['transform', 'transition'],
+  box: ['x', 'y', 'width', 'height'],
+});
+const GROUP_OF = Object.fromEntries(Object.entries(GROUPS).flatMap(([g, ps]) => ps.map((p) => [p, g])));
+/** @param {string} prop */
+export const groupOf = (prop) => GROUP_OF[prop] ?? 'other';
+
+// ------------------------------------------------------------------ colours
+
+const clamp01 = (x) => Math.min(1, Math.max(0, x));
+/**
+ * A CSS colour as [r, g, b, a] (0-255, alpha 0-1), or null. Computed styles
+ * serialize sRGB colours as rgb()/rgba() (Chrome: `rgb(0 0 0 / 0.5)` too) or
+ * color(srgb …); other spaces (oklch, lab) come with the browser's own sRGB
+ * reading (probe.mjs), which wins when present.
+ * @param {string} s
+ * @returns {[number, number, number, number] | null}
+ */
+export const parseColor = (s) => {
+  if (s == null) return null;
+  const v = String(s).trim().toLowerCase();
+  if (v === 'transparent') return [0, 0, 0, 0];
+  let m = /^#([0-9a-f]{3,8})$/.exec(v);
+  if (m) {
+    const h = m[1];
+    const x = h.length <= 4 ? [...h].map((c) => parseInt(c + c, 16)) : h.match(/../g).map((c) => parseInt(c, 16));
+    if (x.length !== 3 && x.length !== 4) return null;
+    return [x[0], x[1], x[2], x.length === 4 ? x[3] / 255 : 1];
+  }
+  m = /^rgba?\(\s*([^)]+)\)$/.exec(v);
+  if (m) {
+    const parts = m[1].split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const ch = parts.slice(0, 3).map((p) => (p.endsWith('%') ? (parseFloat(p) * 255) / 100 : parseFloat(p)));
+    const a = parts[3] == null ? 1 : parts[3].endsWith('%') ? parseFloat(parts[3]) / 100 : parseFloat(parts[3]);
+    if ([...ch, a].some((n) => !Number.isFinite(n))) return null;
+    return [ch[0], ch[1], ch[2], clamp01(a)];
+  }
+  m = /^color\(\s*srgb\s+([^)]+)\)$/.exec(v);
+  if (m) {
+    const parts = m[1].split(/[\s/]+/).filter(Boolean);
+    const ch = parts.slice(0, 3).map((p) => (p.endsWith('%') ? parseFloat(p) / 100 : parseFloat(p)) * 255);
+    const a = parts[3] == null ? 1 : parseFloat(parts[3]) / (parts[3].endsWith('%') ? 100 : 1);
+    if ([...ch, a].some((n) => !Number.isFinite(n))) return null;
+    return [ch[0], ch[1], ch[2], clamp01(a)];
+  }
+  return null;
+};
+
+/** sRGB (0-255) to CIE Lab (D65). @param {number[]} rgb */
+export const toLab = ([r, g, b]) => {
+  const lin = (c) => {
+    const x = c / 255;
+    return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+  };
+  const [R, G, B] = [lin(r), lin(g), lin(b)];
+  const X = (R * 0.4124564 + G * 0.3575761 + B * 0.1804375) / 0.95047;
+  const Y = R * 0.2126729 + G * 0.7151522 + B * 0.072175;
+  const Z = (R * 0.0193339 + G * 0.119192 + B * 0.9503041) / 1.08883;
+  const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116);
+  const [fx, fy, fz] = [f(X), f(Y), f(Z)];
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+};
+
+/** CIEDE2000 colour difference of two Lab colours. @param {number[]} lab1 @param {number[]} lab2 */
+export const deltaE2000 = ([L1, a1, b1], [L2, a2, b2]) => {
+  const rad = Math.PI / 180;
+  const C1 = Math.hypot(a1, b1);
+  const C2 = Math.hypot(a2, b2);
+  const Cm = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cm ** 7 / (Cm ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * a1;
+  const a2p = (1 + G) * a2;
+  const C1p = Math.hypot(a1p, b1);
+  const C2p = Math.hypot(a2p, b2);
+  const h = (b, a) => (b === 0 && a === 0 ? 0 : ((Math.atan2(b, a) / rad) + 360) % 360);
+  const h1p = h(b1, a1p);
+  const h2p = h(b2, a2p);
+  const dLp = L2 - L1;
+  const dCp = C2p - C1p;
+  let dhp = 0;
+  if (C1p * C2p !== 0) {
+    dhp = h2p - h1p;
+    if (dhp > 180) dhp -= 360;
+    else if (dhp < -180) dhp += 360;
+  }
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp * rad) / 2);
+  const Lmp = (L1 + L2) / 2;
+  const Cmp = (C1p + C2p) / 2;
+  let hmp = h1p + h2p;
+  if (C1p * C2p !== 0) {
+    if (Math.abs(h1p - h2p) > 180) hmp += h1p + h2p < 360 ? 360 : -360;
+    hmp /= 2;
+  }
+  const T = 1 - 0.17 * Math.cos((hmp - 30) * rad) + 0.24 * Math.cos(2 * hmp * rad) + 0.32 * Math.cos((3 * hmp + 6) * rad) - 0.2 * Math.cos((4 * hmp - 63) * rad);
+  const dTheta = 30 * Math.exp(-(((hmp - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cmp ** 7 / (Cmp ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lmp - 50) ** 2) / Math.sqrt(20 + (Lmp - 50) ** 2);
+  const Sc = 1 + 0.045 * Cmp;
+  const Sh = 1 + 0.015 * Cmp * T;
+  const Rt = -Math.sin(2 * dTheta * rad) * Rc;
+  return Math.sqrt((dLp / Sl) ** 2 + (dCp / Sc) ** 2 + (dHp / Sh) ** 2 + Rt * (dCp / Sc) * (dHp / Sh));
+};
+
+/** #rrggbb (with @alpha when translucent): how a colour is named in the report, next to the raw value. @param {number[] | null} c */
+export const hex = (c) => {
+  if (!c) return '';
+  const h = `#${c.slice(0, 3).map((x) => Math.round(x).toString(16).padStart(2, '0')).join('')}`;
+  return c[3] < 1 ? `${h} @${Math.round(c[3] * 1000) / 1000}` : h;
+};
+
+/**
+ * Two colours: equal, or how they differ. Fully transparent colours are equal
+ * whatever their channels; alpha is compared on its own.
+ * @param {{ raw: string, rgba?: number[] } | string} a @param {{ raw: string, rgba?: number[] } | string} b @param {typeof TOLERANCE} tol
+ */
+export const compareColor = (a, b, tol = TOLERANCE) => {
+  const ca = colorOf(a);
+  const cb = colorOf(b);
+  if (!ca || !cb) return rawOf(a) === rawOf(b) ? null : { delta: 'different' };
+  if (ca[3] === 0 && cb[3] === 0) return null;
+  const dA = Math.abs(ca[3] - cb[3]);
+  const dE = deltaE2000(toLab(ca), toLab(cb));
+  const out = [];
+  if (dE > tol.deltaE) out.push(`ΔE ${round(dE, 1)}`);
+  if (dA > tol.alpha) out.push(`alpha ${round(ca[3], 3)} vs ${round(cb[3], 3)}`);
+  return out.length ? { delta: out.join(', '), deltaE: round(dE, 2) } : null;
+};
+const colorOf = (v) => (v && typeof v === 'object' ? (v.rgba ?? parseColor(v.raw)) : parseColor(v));
+const rawOf = (v) => (v && typeof v === 'object' ? v.raw : v);
+
+// ------------------------------------------------------------------ other kinds
+
+/** @param {number} x @param {number} d */
+export const round = (x, d = 2) => {
+  const f = 10 ** d;
+  return Math.round(x * f) / f;
+};
+
+/** Splits a value at top-level commas (not those inside parentheses). @param {string} s */
+export const splitTop = (s) => {
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of String(s)) {
+    if (ch === '(') depth++;
+    if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      out.push(cur.trim());
+      cur = '';
+    } else cur += ch;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+};
+
+/** Tokens of a value: functions (rgb(...)) kept whole. @param {string} s */
+const tokens = (s) => String(s).match(/[a-z-]+\([^()]*(?:\([^()]*\)[^()]*)*\)|[^\s]+/gi) ?? [];
+const PX = /^(-?[\d.]+(?:e-?\d+)?)px$/i;
+const num = (t) => {
+  const m = PX.exec(t);
+  return m ? Number(m[1]) : t === '0' ? 0 : null;
+};
+
+/** Lengths (one or more px tokens; `normal` and keywords exactly). @param {string} a @param {string} b @param {typeof TOLERANCE} tol */
+export const compareLength = (a, b, tol = TOLERANCE) => {
+  const ta = tokens(a);
+  const tb = tokens(b);
+  if (ta.length !== tb.length) return { delta: 'different' };
+  let max = 0;
+  for (let i = 0; i < ta.length; i++) {
+    const [x, y] = [num(ta[i]), num(tb[i])];
+    if (x == null || y == null) {
+      if (ta[i] !== tb[i]) return { delta: 'different' };
+      continue;
+    }
+    max = Math.max(max, Math.abs(y - x));
+  }
+  if (max <= tol.px) return null;
+  // One length: the signed delta (ours - theirs); several: the largest.
+  const one = ta.length === 1 ? num(tb[0]) - num(ta[0]) : null;
+  return { delta: one != null ? `${one > 0 ? '+' : ''}${round(one, 2)}px` : `up to ${round(max, 2)}px`, px: round(max, 3) };
+};
+
+/**
+ * Shadows (box-shadow, text-shadow): layer by layer, colours by ΔE, lengths by px.
+ * @param {string} a @param {string} b @param {typeof TOLERANCE} tol
+ */
+export const compareShadow = (a, b, tol = TOLERANCE) => {
+  const la = a === 'none' ? [] : splitTop(a);
+  const lb = b === 'none' ? [] : splitTop(b);
+  if (la.length !== lb.length) return { delta: `${la.length} vs ${lb.length} layers` };
+  for (let i = 0; i < la.length; i++) {
+    const ta = tokens(la[i]);
+    const tb = tokens(lb[i]);
+    const ca = ta.find((t) => parseColor(t));
+    const cb = tb.find((t) => parseColor(t));
+    if (!!ca !== !!cb) return { delta: `layer ${i + 1}: colour` };
+    if (ca && compareColor(ca, cb, tol)) return { delta: `layer ${i + 1}: ${compareColor(ca, cb, tol).delta}` };
+    const la2 = ta.filter((t) => t !== ca);
+    const lb2 = tb.filter((t) => t !== cb);
+    const d = compareLength(la2.join(' '), lb2.join(' '), tol);
+    if (d) return { delta: `layer ${i + 1}: ${d.delta}` };
+  }
+  return null;
+};
+
+/** font-family lists: the same families in the same order (quotes and case aside). @param {string} a @param {string} b */
+export const compareFamily = (a, b) => {
+  const n = (s) => splitTop(s).map((f) => f.replace(/^["']|["']$/g, '').trim().toLowerCase()).join(', ');
+  return n(a) === n(b) ? null : { delta: 'different' };
+};
+
+/** grid-template-columns: the number of tracks, then each track's size. @param {string} a @param {string} b @param {typeof TOLERANCE} tol */
+export const compareTracks = (a, b, tol = TOLERANCE) => {
+  const ta = a === 'none' ? [] : tokens(a);
+  const tb = b === 'none' ? [] : tokens(b);
+  if (ta.length !== tb.length) return { delta: `${ta.length} vs ${tb.length} tracks`, critical: ta.length > 0 && tb.length > 0 };
+  return compareLength(a, b, tol);
+};
+
+/** transform: the matrix's numbers (translation in px). @param {string} a @param {string} b @param {typeof TOLERANCE} tol */
+export const compareTransform = (a, b, tol = TOLERANCE) => {
+  if (a === b) return null;
+  const n = (s) => (s === 'none' ? [1, 0, 0, 1, 0, 0] : (/matrix(?:3d)?\(([^)]+)\)/.exec(s)?.[1].split(',').map(Number) ?? null));
+  const [x, y] = [n(a), n(b)];
+  if (!x || !y || x.length !== y.length) return { delta: 'different' };
+  const max = Math.max(...x.map((v, i) => Math.abs(v - y[i])));
+  return max <= Math.max(tol.px, 0.001) ? null : { delta: 'different' };
+};
+
+/** One computed property, by its kind. @param {string} prop @param {any} a @param {any} b @param {typeof TOLERANCE} tol */
+export const compareValue = (prop, a, b, tol = TOLERANCE) => {
+  if (a == null && b == null) return null;
+  if (a == null || b == null) return { delta: 'different' };
+  switch (kindOf(prop)) {
+    case 'color':
+      return compareColor(a, b, tol);
+    case 'shadow':
+      return compareShadow(a, b, tol);
+    case 'length':
+      return compareLength(a, b, tol);
+    case 'family':
+      return compareFamily(a, b);
+    case 'tracks':
+      return compareTracks(a, b, tol);
+    case 'transform':
+      return compareTransform(a, b, tol);
+    default:
+      return norm(a) === norm(b) ? null : { delta: 'different' };
+  }
+};
+const norm = (v) => String(v).replace(/\s+/g, ' ').trim();
+
+/** Text as the comparison sees it: `exact` (whitespace collapsed) or `shape` (every number one placeholder). @param {string} s @param {'exact' | 'shape'} mode */
+export const textOf = (s, mode) => {
+  const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return mode === 'shape' ? t.replace(/\d(?:[\d\s.,'’]*\d)?/g, '#') : t;
+};
+
+// ------------------------------------------------------------------ elements and components
+
+/**
+ * One element of theirs against ours (the component's root or one of its
+ * parts): presence, box, rendered font, text, every computed property.
+ * `a`/`b`: { present, box: {x,y,width,height}, style: {prop: value}, font, text } (probe.mjs).
+ * @returns {{ checks: number, weight: number, diffs: Diff[] }}
+ *
+ * @typedef {{ part: string, prop: string, theirs: any, ours: any, delta: string, severity: 'critical' | 'major' | 'minor', group: string, weight: number, owner?: 'template' | 'data', why?: string, evidence?: any, hint?: string, responsible?: any }} Diff
+ */
+export const compareElement = (part, a, b, { tol = TOLERANCE, text = 'exact', ignore = [], root = false } = {}) => {
+  const out = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]) };
+  const ignored = new Set(ignore.flatMap((p) => GROUPS[p] ?? [p]));
+  // One check: counted with the weight it has when it fails (critical ones weigh more), its difference if any.
+  const tally = (prop, theirs, ours, d, severity = 'major') => {
+    const sev = d?.critical || severity === 'critical' ? 'critical' : isMinor(prop, d) ? 'minor' : 'major';
+    const w = weightOf(sev === 'critical' ? 'critical' : severity);
+    out.checks += w;
+    if (!d) return;
+    out.weight += w;
+    out.diffs.push({ part, prop, theirs, ours, delta: d.delta, severity: sev, group: groupOf(prop), weight: w });
+  };
+  const [pa, pb] = [!!a?.present, !!b?.present];
+  if (!pa && !pb) return out;
+  if (pa !== pb) {
+    tally('presence', pa ? 'present' : 'missing', pb ? 'present' : 'missing', { delta: pa ? 'missing in ours' : 'only in ours' }, 'critical');
+    return out;
+  }
+  for (const k of ['x', 'y', 'width', 'height']) {
+    if (ignored.has(k) || (root && (k === 'x' || k === 'y'))) continue;
+    tally(k, round(a.box[k], 2), round(b.box[k], 2), compareLength(`${a.box[k]}px`, `${b.box[k]}px`, tol));
+  }
+  // A part's controls (a price filter's slider and its inputs): a kind theirs has and ours lacks is a missing element.
+  if (!root && !ignored.has('controls') && a.controls && Object.values(a.controls).some((n) => n > 0)) {
+    const missing = Object.keys(a.controls).filter((k) => a.controls[k] > 0 && !(b.controls?.[k] > 0));
+    tally('controls', controlsText(a.controls), controlsText(b.controls), missing.length ? { delta: `missing in ours: ${missing.join(', ')}` } : null, 'critical');
+  }
+  if (!ignored.has('rendered-font') && (a.font || b.font)) tally('rendered-font', a.font ?? '', b.font ?? '', (a.font ?? '') === (b.font ?? '') ? null : { delta: 'different' });
+  if (text && !ignored.has('text') && (a.text || b.text)) {
+    const same = textOf(a.text, text) === textOf(b.text, text);
+    tally('text', a.text ?? '', b.text ?? '', same ? null : { delta: text === 'shape' ? 'different wording' : 'different' }, 'critical');
+  }
+  for (const prop of PROPS) {
+    if (ignored.has(prop)) continue;
+    const [va, vb] = [a.style?.[prop], b.style?.[prop]];
+    if (va === undefined && vb === undefined) continue;
+    tally(prop, rawOf(va), rawOf(vb), compareValue(prop, va, vb, tol));
+  }
+  return out;
+};
+
+/** A part's controls as the report names them: "slider, 2 inputs". @param {Record<string, number> | null | undefined} c */
+export const controlsText = (c) => {
+  const PLURAL = { slider: 'sliders', input: 'inputs', select: 'selects', checkbox: 'checkboxes', radio: 'radios', button: 'buttons' };
+  const out = Object.entries(c ?? {}).filter(([, n]) => n > 0).map(([k, n]) => (n === 1 ? k : `${n} ${PLURAL[k] ?? `${k}s`}`));
+  return out.length ? out.join(', ') : 'none';
+};
+
+/** The order parts appear in (top to bottom, then left to right), for the parts both sides have. @param {Record<string, any>} parts */
+export const orderOf = (parts) =>
+  Object.entries(parts ?? {})
+    .filter(([, p]) => p?.present)
+    .sort(([na, a], [nb, b]) => (Math.abs(a.box.y - b.box.y) > 2 ? a.box.y - b.box.y : Math.abs(a.box.x - b.box.x) > 2 ? a.box.x - b.box.x : na < nb ? -1 : 1))
+    .map(([n]) => n);
+
+/**
+ * A grid of items (columns per row, gaps, item width, the container's padding).
+ * `a`/`b`: { columns, columnGap, rowGap, itemWidth, padding: [t, r, b, l], items } (probe.mjs `grid`).
+ */
+export const compareGrid = (a, b, tol = TOLERANCE) => {
+  const out = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]) };
+  if (!a || !b) return out;
+  const add = (prop, x, y, d, critical = false) => {
+    const severity = critical ? 'critical' : isMinor(prop, d) ? 'minor' : 'major';
+    const weight = critical ? WEIGHT.critical : WEIGHT.check;
+    out.diffs.push({ part: 'grid', prop, theirs: x, ours: y, delta: d.delta, severity, group: 'layout', weight });
+    out.weight += weight;
+  };
+  out.checks += WEIGHT.critical;
+  if (a.columns !== b.columns) add('columns', a.columns, b.columns, { delta: `${a.columns} vs ${b.columns}` }, true);
+  for (const k of ['columnGap', 'rowGap', 'itemWidth']) {
+    if (a[k] == null && b[k] == null) continue;
+    out.checks += WEIGHT.check;
+    if (a[k] == null || b[k] == null) add(k, a[k] ?? '-', b[k] ?? '-', { delta: 'different' });
+    else {
+      const d = compareLength(`${a[k]}px`, `${b[k]}px`, tol);
+      if (d) add(k, round(a[k], 2), round(b[k], 2), d);
+    }
+  }
+  const sides = ['top', 'right', 'bottom', 'left'];
+  for (let i = 0; i < 4; i++) {
+    out.checks += WEIGHT.check;
+    const d = compareLength(`${a.padding?.[i] ?? 0}px`, `${b.padding?.[i] ?? 0}px`, tol);
+    if (d) add(`padding-${sides[i]}`, a.padding?.[i] ?? 0, b.padding?.[i] ?? 0, d);
+  }
+  return out;
+};
+
+/** The lower median. @param {number[]} xs */
+const median = (xs) => (xs.length ? [...xs].sort((x, y) => x - y)[Math.floor((xs.length - 1) / 2)] : null);
+
+/**
+ * How consecutive siblings lie (page boxes [x, y, width, height], probe.mjs
+ * `siblingsOf`): rows (a box within 2 px of the row's top joins it), the
+ * columns of the first row, the space between neighbours in a row and
+ * between rows (the median: one odd gap is not the pattern), stacked or side
+ * by side. Null for fewer than two.
+ * @param {number[][] | null | undefined} boxes
+ * @returns {{ n: number, columns: number, rows: number, columnGap: number | null, rowGap: number | null, stacked: boolean } | null}
+ */
+export const layoutOf = (boxes) => {
+  if (!Array.isArray(boxes) || boxes.length < 2) return null;
+  const rows = [];
+  for (const b of boxes) {
+    const row = rows.find((r) => Math.abs(r[0][1] - b[1]) < 2);
+    if (row) row.push(b);
+    else rows.push([b]);
+  }
+  for (const r of rows) r.sort((p, q) => p[0] - q[0]);
+  rows.sort((p, q) => p[0][1] - q[0][1]);
+  const inRow = [];
+  for (const r of rows) for (let i = 1; i < r.length; i++) inRow.push(r[i][0] - (r[i - 1][0] + r[i - 1][2]));
+  const between = [];
+  for (let i = 1; i < rows.length; i++) between.push(rows[i][0][1] - Math.max(...rows[i - 1].map((b) => b[1] + b[3])));
+  const g = (v) => (v == null ? null : round(v, 2));
+  return { n: boxes.length, columns: rows[0].length, rows: rows.length, columnGap: g(median(inRow)), rowGap: g(median(between)), stacked: rows.every((r) => r.length === 1) };
+};
+
+/**
+ * The space between consecutive siblings of a repeated part or component
+ * (facet groups squeezed together, facet values, tiles in a column): each
+ * element's own box can match while the gap between one and the next does
+ * not (a `+` rule's margin, the parent's gap). MINOR up to MINOR.gap px,
+ * MAJOR beyond; stacked against side by side MAJOR. `columns`: a repeated
+ * component's columns per row too (a tile without a grid component),
+ * CRITICAL when they differ, at any viewport.
+ * @param {string} part @param {number[][] | null | undefined} a @param {number[][] | null | undefined} b
+ * @param {typeof TOLERANCE} tol @param {{ columns?: boolean }} [o]
+ */
+export const compareSiblings = (part, a, b, tol = TOLERANCE, { columns = false } = {}) => {
+  const out = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]) };
+  const [la, lb] = [layoutOf(a), layoutOf(b)];
+  if (!la || !lb) return out;
+  const add = (prop, x, y, d, critical = false) => {
+    const severity = critical ? 'critical' : isMinor(prop, d) ? 'minor' : 'major';
+    const weight = critical ? WEIGHT.critical : WEIGHT.check;
+    out.diffs.push({ part, prop, theirs: x, ours: y, delta: d.delta, severity, group: prop === 'columns' ? 'layout' : 'spacing', weight });
+    out.weight += weight;
+  };
+  if (columns) {
+    out.checks += WEIGHT.critical;
+    if (la.columns !== lb.columns) add('columns', la.columns, lb.columns, { delta: `${la.columns} vs ${lb.columns}` }, true);
+  } else {
+    out.checks += WEIGHT.check;
+    if (la.stacked !== lb.stacked) add('sibling-direction', la.stacked ? 'stacked' : 'side by side', lb.stacked ? 'stacked' : 'side by side', { delta: 'different' });
+  }
+  for (const [prop, k] of [['sibling-column-gap', 'columnGap'], ['sibling-row-gap', 'rowGap']]) {
+    if (la[k] == null || lb[k] == null) continue;
+    out.checks += WEIGHT.check;
+    const d = compareLength(`${la[k]}px`, `${lb[k]}px`, tol);
+    if (d) add(prop, la[k], lb[k], d);
+  }
+  return out;
+};
+
+/**
+ * One component instance (theirs vs ours, measured by probe.mjs `measure`):
+ * the root, every mapped part, the parts' order, the grid when it is one,
+ * and the pixel diff's share; every difference with its owner (owner.mjs:
+ * the template's or the data's), the score and the template's score.
+ * @param {{ theirs: any, ours: any, pixels?: { ratio: number } | null, hit?: any, siblings?: { theirs: number[][] | null, ours: number[][] | null, columns?: boolean } | null }} pair `hit`: the catalog record of the paired product; `siblings`: a repeated component's instances (compareSiblings)
+ * @param {{ tol?: typeof TOLERANCE, parts?: Record<string, { text?: 'exact' | 'shape' | false, ignore?: string[], role?: string | null }>, text?: 'exact' | 'shape' | false, ignore?: string[], component?: string, role?: string | null, gaps?: Record<string, string>, decided?: Record<string, any> }} opts
+ */
+export const compareInstance = (pair, opts = {}) => {
+  const tol = { ...TOLERANCE, ...(opts.tol ?? {}) };
+  const res = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]) };
+  const merge = (r) => {
+    res.checks += r.checks;
+    res.weight += r.weight;
+    res.diffs.push(...r.diffs);
+  };
+  const { theirs: a, ours: b } = pair;
+  if (!a?.present || !b?.present) {
+    merge(compareElement('root', a ?? { present: false }, b ?? { present: false }, { tol, root: true }));
+    return finish(res, pair, opts);
+  }
+  // A component without parts (a result count, a heading) is its own text.
+  const leaf = !a.grid && !b.grid && !Object.keys(a.parts ?? {}).length && !Object.keys(b.parts ?? {}).length;
+  merge(compareElement('root', a, b, { tol, text: leaf ? (opts.text ?? 'exact') : false, ignore: opts.ignore ?? [], root: true }));
+  const names = [...new Set([...Object.keys(a.parts ?? {}), ...Object.keys(b.parts ?? {})])].sort();
+  for (const n of names) {
+    const po = opts.parts?.[n] ?? {};
+    const ignore = [...(opts.ignore ?? []), ...(po.ignore ?? [])];
+    merge(compareElement(n, a.parts?.[n], b.parts?.[n], { tol, text: po.text ?? opts.text ?? 'exact', ignore }));
+    // A repeated part (facet groups, a group's values): the space between one and the next, not only its own box.
+    if (a.parts?.[n]?.present && b.parts?.[n]?.present && !ignore.includes('spacing') && !ignore.includes('siblings')) merge(compareSiblings(n, a.parts[n].siblings, b.parts[n].siblings, tol));
+  }
+  // A repeated component's instances (tiles, facet groups as a component): their gaps; a tile's columns when no grid is compared.
+  if (pair.siblings && !(opts.ignore ?? []).includes('spacing') && !(opts.ignore ?? []).includes('siblings')) merge(compareSiblings('root', pair.siblings.theirs, pair.siblings.ours, tol, { columns: !!pair.siblings.columns }));
+  const [oa, ob] = [orderOf(a.parts), orderOf(b.parts)];
+  const common = oa.filter((n) => ob.includes(n));
+  if (common.length > 1) {
+    res.checks += WEIGHT.check;
+    const ob2 = ob.filter((n) => common.includes(n));
+    if (common.join() !== ob2.join()) {
+      res.diffs.push({ part: 'root', prop: 'order', theirs: common.join(' > '), ours: ob2.join(' > '), delta: 'different order', severity: 'major', group: 'layout', weight: WEIGHT.check });
+      res.weight += WEIGHT.check;
+    }
+  }
+  if (a.grid || b.grid) merge(compareGrid(a.grid, b.grid, tol));
+  if (pair.pixels) {
+    res.checks += WEIGHT.pixels;
+    if (pair.pixels.ratio > tol.pixels) {
+      res.diffs.push({ part: 'root', prop: 'pixels', theirs: `${pair.pixels.size?.theirs ?? ''}`, ours: `${pair.pixels.size?.ours ?? ''}`, delta: `${round(pair.pixels.ratio * 100, 2)}% of pixels differ`, ratio: pair.pixels.ratio, severity: 'minor', group: 'pixels', weight: WEIGHT.pixels });
+      res.weight += WEIGHT.pixels;
+    }
+  }
+  return finish(res, pair, opts);
+};
+
+/** The owners (owner.mjs), the score and the template's score (the data's differences count as passed checks). */
+const finish = (r, pair = {}, opts = {}) => {
+  const partRoles = Object.fromEntries(Object.entries(opts.parts ?? {}).map(([k, v]) => [k, v.role ?? null]));
+  const diffs = decide(attribute(r.diffs, { component: opts.component, role: opts.role ?? null, partRoles, hit: pair.hit ?? null, gaps: opts.gaps ?? {} }), { component: opts.component, decided: opts.decided ?? {} });
+  // The template's score: the data's differences and the decided ones count as passed.
+  const templateWeight = diffs.filter((d) => (d.owner ?? 'template') === 'template').reduce((s, d) => s + d.weight, 0);
+  return { ...r, diffs, templateWeight, score: scoreOf(r), templateScore: scoreOf({ checks: r.checks, weight: templateWeight }) };
+};
+/** 100 when nothing differs; every difference takes its weight off the checks' total; null when nothing was there to check (on neither side). @param {{ checks: number, weight: number }} r */
+export const scoreOf = (r) => (r.checks ? round(100 * Math.max(0, 1 - r.weight / r.checks), 1) : null);
+
+const SEVERITY_RANK = { critical: 0, major: 1, minor: 2 };
+const FOLLOWS_COLOR = new Set(['border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color', 'outline-color', 'text-decoration-color']);
+
+/**
+ * The same difference across a component's instances (every price 1px small)
+ * is one finding with a count: a finding per tile buries the pattern.
+ * @param {Diff[][]} lists one list per instance
+ */
+export const aggregate = (lists) => {
+  const by = new Map();
+  for (const list of lists)
+    for (const d of list) {
+      // The pixel diff: one finding, its largest share (the sizes and shares differ per instance).
+      const key = JSON.stringify(d.prop === 'pixels' ? [d.part, d.prop, d.owner ?? ''] : [d.part, d.prop, d.theirs, d.ours, d.owner ?? '']);
+      const cur = by.get(key);
+      if (cur) {
+        cur.count++;
+        if (d.prop === 'pixels' && d.ratio > cur.ratio) Object.assign(cur, { ...d, count: cur.count, delta: `up to ${d.delta}` });
+        else if (d.prop === 'pixels' && !cur.delta.startsWith('up to')) cur.delta = `up to ${cur.delta}`;
+      } else by.set(key, { ...d, count: 1 });
+    }
+  const rank = (d) => SEVERITY_RANK[d.severity] ?? 1;
+  return [...by.values()].sort((x, y) => rank(x) - rank(y) || y.count - x.count || (x.part < y.part ? -1 : x.part > y.part ? 1 : 0) || (x.prop < y.prop ? -1 : x.prop > y.prop ? 1 : 0));
+};
+
+/**
+ * A component at one viewport, all its instances: the mean score and
+ * template score, the aggregated differences, the instances' own scores.
+ * `unpaired`: their products the API did not find (not in the catalog):
+ * each a data difference, and an instance scoring 0 in the overall score
+ * (none in the template's).
+ * @param {{ component: string, page: string, viewport: number, pairs: { key: string, theirs: any, ours: any, pixels?: any, hit?: any }[], unpaired?: string[] }} c
+ * @param {Parameters<typeof compareInstance>[1]} opts
+ */
+export const compareComponent = (c, opts = {}) => {
+  const instances = c.pairs.map((p) => ({ key: p.key, ...compareInstance(p, { component: baseOf(c.component), ...opts }), pixels: p.pixels ?? null }));
+  const unpaired = c.unpaired ?? [];
+  const mean = (xs) => (xs.length ? round(xs.reduce((s, x) => s + x, 0) / xs.length, 1) : null);
+  const scores = instances.map((i) => i.score).filter((s) => s != null);
+  const score = mean(scores.length ? [...scores, ...unpaired.map(() => 0)] : []);
+  const templateScore = mean(instances.map((i) => i.templateScore).filter((s) => s != null));
+  const lost = unpaired.map((id) => ({ part: 'root', prop: 'unpaired', theirs: id, ours: 'not found by the API', delta: 'their product is not in the catalog', severity: 'critical', group: 'data', weight: WEIGHT.critical, owner: 'data', why: 'not in the catalog (or not under the pairing field: products.field)', count: 1 }));
+  return {
+    component: c.component,
+    page: c.page,
+    viewport: c.viewport,
+    score,
+    templateScore,
+    instances: instances.map(({ key, score: s, templateScore: ts, checks, weight, pixels }) => ({ key, score: s, templateScore: ts, checks, weight, pixels: pixels ? { ratio: round(pixels.ratio, 4), images: pixels.images ?? null } : null })),
+    diffs: [...lost, ...aggregate(instances.map((i) => i.diffs))],
+  };
+};
+
+/** A result's component as the map names it: `tile@drawer-open:hover` is `tile` (in a state, hovered). @param {string} name */
+export const baseOf = (name) => String(name).replace(/:hover$/, '').replace(/@[\w-]+$/, '');
+
+/**
+ * The collateral check of one page (docs/PARITY.md, "The collateral check"):
+ * their page without us against ours, outside our components (probe.mjs
+ * `blocksOf` on both). A block of theirs missing in ours (a widget removed,
+ * hidden) is CRITICAL, and so is a child of it; a block's box otherwise (a
+ * header moved, a block collapsed) MAJOR: its x, width and height, and its y
+ * when it lies above our components (below them it moves with our
+ * components' height, which their own checks compare). A container of
+ * theirs (their listing's column: it held what ours replaces) may be gone;
+ * when it is there, its x, width and (above) y. A block only in ours is
+ * MAJOR. The pixels of each block both sides show at one size, a second
+ * signal (MINOR). The layout shift (CLS) ours adds over theirs, beyond
+ * `cls`: MAJOR, with the elements that moved.
+ * @param {{ blocks: any[], top: number | null, cls?: { value: number, shifts: any[] } | null }} a their page without us (`cls`: the shifts of their elements above our components)
+ * @param {{ blocks: any[], top: number | null, cls?: { value: number, shifts: any[] } | null }} b ours
+ * @param {{ tol?: typeof TOLERANCE, pixels?: Record<string, number>, cls?: number | null }} [o] `pixels`: per block path, the share of its pixels that differ
+ */
+export const compareCollateral = (a, b, { tol = TOLERANCE, pixels = {}, cls = 0.02, around = null } = {}) => {
+  const t = { ...TOLERANCE, ...tol };
+  const out = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]), layout: /** @type {any} */ (null) };
+  const name = (path) => String(path).replace(/^body > /, '');
+  const add = (path, prop, theirs, ours, d, severity) => {
+    const sev = severity ?? (isMinor(prop, d) ? 'minor' : 'major');
+    const weight = sev === 'critical' ? WEIGHT.critical : prop === 'pixels' ? WEIGHT.pixels : WEIGHT.check;
+    out.diffs.push({ part: name(path), prop, theirs, ours, delta: d.delta, severity: sev, group: 'collateral', weight, ...(d.ratio != null ? { ratio: d.ratio } : {}) });
+    out.weight += weight;
+  };
+  const check = (w = WEIGHT.check) => (out.checks += w);
+  const ours = new Map((b?.blocks ?? []).map((x) => [x.path, x]));
+  const theirs = new Map((a?.blocks ?? []).map((x) => [x.path, x]));
+  // Above our components, on ours: it keeps its place (their header, a breadcrumb), so its y is compared.
+  const above = (x) => b?.top == null || x.box.y + x.box.height <= b.top + 1;
+  const boxes = (path, x, y, props) => {
+    for (const k of props) {
+      if (k === 'y' && !(above(y) && above(x))) continue;
+      check();
+      const d = compareLength(`${x.box[k]}px`, `${y.box[k]}px`, t);
+      if (d) add(path, k, round(x.box[k], 2), round(y.box[k], 2), d);
+    }
+  };
+  // Their containers ours has not (their listing's column, hidden while ours shows): what is in them is replaced.
+  const replaced = (a?.blocks ?? []).filter((x) => x.kind === 'container' && x.present && !ours.get(x.path)?.present).map((x) => `${x.path} > `);
+  for (const x of a?.blocks ?? []) {
+    const y = ours.get(x.path);
+    if (replaced.some((p) => x.path.startsWith(p))) continue;
+    if (!x.present) {
+      // Hidden on their page, shown on ours (something of ours unhid it).
+      if (y?.present && y.kind === 'outside') {
+        check(WEIGHT.critical);
+        add(x.path, 'presence', 'hidden', 'shown', { delta: 'shown only in ours' });
+      }
+      continue;
+    }
+    if (x.kind === 'container') {
+      // Their listing's column: it held what ours replaces; gone or there, both fine. There: in its place.
+      if (y?.present) boxes(x.path, x, y, ['x', 'width', 'y']);
+      continue;
+    }
+    check(WEIGHT.critical);
+    if (!y?.present) {
+      add(x.path, 'presence', 'present', 'missing', { delta: 'their block is missing in ours' }, 'critical');
+      continue;
+    }
+    // Ours holds one of our components in it (our listing in their content column): its height is our component's.
+    boxes(x.path, x, y, y.kind === 'outside' ? ['x', 'y', 'width', 'height'] : ['x', 'y', 'width']);
+    // Its children: a widget inside their header (a menu, a cart) gone from ours (where ours holds ours in it: its blocks).
+    const kids = new Set(y.kind === 'outside' ? (y.children ?? []) : (b?.blocks ?? []).filter((z) => z.present).map((z) => z.path));
+    for (const c of x.children ?? []) {
+      check(WEIGHT.critical);
+      if (!kids.has(c)) add(c, 'presence', 'present', 'missing', { delta: 'their element is missing in ours' }, 'critical');
+    }
+    if (y.kind !== 'outside') continue;
+    if (pixels[x.path] != null) {
+      check(WEIGHT.pixels);
+      if (pixels[x.path] > t.pixels) add(x.path, 'pixels', '', '', { delta: `${round(pixels[x.path] * 100, 2)}% of pixels differ`, ratio: pixels[x.path] }, 'minor');
+    }
+  }
+  for (const y of b?.blocks ?? []) {
+    if (!y.present || y.kind !== 'outside' || theirs.get(y.path)?.present) continue;
+    if (theirs.has(y.path)) continue; // hidden on theirs: counted above
+    check();
+    add(y.path, 'presence', 'missing', 'present', { delta: 'a block only in ours, outside our components' });
+  }
+  if (cls != null && a?.cls && b?.cls) {
+    check();
+    const more = b.cls.value - a.cls.value;
+    if (more > cls) {
+      const moved = [...new Set(b.cls.shifts.flatMap((s) => s.nodes))].slice(0, 4).join(', ');
+      add('page', 'cls', round(a.cls.value, 4), round(b.cls.value, 4), { delta: `+${round(more, 4)} layout shift${moved ? ` (moved: ${moved})` : ''}` });
+    }
+  }
+  // The layout around the listing (their listing page's when ours is against another page of theirs), the empty space under it.
+  if (around) {
+    const x = compareAround(around.theirs, around.ours, around);
+    out.checks += x.checks;
+    out.weight += x.weight;
+    out.diffs.push(...x.diffs);
+    out.layout = x.layout;
+  }
+  return out;
+};
+
+/** What makes an element tall though it renders nothing: its min-height, its padding, its height (aroundOf's styles). */
+export const spacingOf = (x) => {
+  const out = [];
+  if (x.minHeight && !/^(0px|auto|0)$/.test(x.minHeight)) out.push(`min-height: ${x.minHeight}`);
+  if (x.paddingTop) out.push(`padding-top: ${x.paddingTop}px`);
+  if (x.paddingBottom) out.push(`padding-bottom: ${x.paddingBottom}px`);
+  if (x.marginTop) out.push(`margin-top: ${x.marginTop}px`);
+  if (x.marginBottom) out.push(`margin-bottom: ${x.marginBottom}px`);
+  out.push(`height: ${round(x.height, 2)}px`);
+  return out.join('; ');
+};
+
+/** An empty element of theirs a theme keeps tall: what renders nothing above `EMPTY_PX` between our listing and what follows it. */
+export const EMPTY_PX = 100;
+/** A gap around the listing off by more than this is CRITICAL (a shopper sees a hole); within the tolerance (`collateral.gap`) alike. */
+export const GAP_CRITICAL = 100;
+
+/**
+ * The vertical layout around the listing (docs/PARITY.md, "The layout
+ * around the listing"), probe.mjs `aroundOf` on both sides:
+ * - `cross` (ours against another page of theirs: their listing page is the
+ *   design source of what surrounds the listing): the gap from the bottom of
+ *   our listing (its pager, its "show more") to the next element that
+ *   renders something (the next block, the footer), and from what is above
+ *   it (the heading, a toolbar) to its top, against the same gaps on their
+ *   listing page. Off by more than `gap` px MAJOR, by more than 100 px
+ *   CRITICAL, with the element of ours that fills the gap (an empty column
+ *   with a theme's min-height) as the fix hint;
+ * - on any page: an element of theirs between our listing and what follows
+ *   it that renders nothing yet takes more than 100 px, MAJOR, with its
+ *   min-height, padding and height; not when their reference page has the
+ *   same one, as tall (their own design).
+ * @param {ReturnType<import('./probe.mjs').aroundOf> | null} ref their listing page (cross), else their page without us
+ * @param {ReturnType<import('./probe.mjs').aroundOf> | null} ours
+ * @param {{ cross?: boolean, gap?: number, against?: string | null }} [o]
+ */
+export const compareAround = (ref, ours, { cross = false, gap = 4, against = null } = {}) => {
+  const out = { checks: 0, weight: 0, diffs: /** @type {Diff[]} */ ([]), layout: { theirs: summary(ref), ours: summary(ours) } };
+  if (!ours) return out;
+  const where = against ? `their listing page (${against})` : 'their listing page';
+  if (cross && ref) {
+    for (const side of /** @type {const} */ (['above', 'below'])) {
+      const [t, o] = [ref[side], ours[side]];
+      if (!t || !o) continue;
+      out.checks += WEIGHT.critical;
+      const d = o.gap - t.gap;
+      if (Math.abs(d) <= gap) continue;
+      const severity = Math.abs(d) > GAP_CRITICAL ? 'critical' : 'major';
+      const weight = severity === 'critical' ? WEIGHT.critical : WEIGHT.check;
+      out.weight += weight;
+      const fill = ours.fillers?.[side]?.[0] ?? null;
+      const what = side === 'below' ? `from the bottom of our listing to ${name(o.path)}` : `from ${name(o.path)} to the top of our listing`;
+      const fix =
+        d > 0 && fill
+          ? `${name(fill.path)} fills it on our page (${spacingOf(fill)}): hide it there, or reset its min-height and padding (integration/**/style-host.css)`
+          : d > 0
+            ? `${side === 'below' ? `the margin-top of ${name(o.path)}, or our listing's margin-bottom` : `the margin-bottom of ${name(o.path)}, or our listing's margin-top`} (integration/**/*.css)`
+            : `their listing page leaves ${round(t.gap, 2)}px ${side === 'below' ? `before ${name(t.path)}` : `after ${name(t.path)}`}: our listing's margin-${side === 'below' ? 'bottom' : 'top'} (integration/**/*.css)`;
+      out.diffs.push({
+        part: 'listing',
+        prop: `gap-${side}`,
+        theirs: round(t.gap, 2),
+        ours: round(o.gap, 2),
+        delta: `${d > 0 ? '+' : ''}${round(d, 2)}px ${what} (${round(t.gap, 2)}px on ${where})`,
+        severity,
+        group: 'collateral',
+        weight,
+        hint: `the space ${what} is ${round(o.gap, 2)}px, ${round(t.gap, 2)}px on ${where}: ${fix}`,
+        ...(fill ? { responsible: { path: name(fill.path), spacing: spacingOf(fill) } } : {}),
+      });
+    }
+  }
+  for (const e of ours.empty ?? []) {
+    out.checks += WEIGHT.check;
+    // Their reference page has it too, as tall: their design, not ours to fix.
+    if ((ref?.empty ?? []).some((x) => x.path === e.path && Math.abs(x.height - e.height) <= gap)) continue;
+    out.weight += WEIGHT.check;
+    out.diffs.push({
+      part: name(e.path),
+      prop: 'empty-space',
+      theirs: 'none',
+      ours: `${round(e.height, 2)}px`,
+      delta: `renders nothing, yet takes ${round(e.height, 2)}px between our listing and what follows it`,
+      severity: 'major',
+      group: 'collateral',
+      weight: WEIGHT.check,
+      hint: `${name(e.path)} renders nothing on our page, yet takes ${round(e.height, 2)}px under our listing (${spacingOf(e)}): hide it on our page, or reset its min-height and padding (integration/**/style-host.css)`,
+    });
+  }
+  return out;
+};
+const name = (path) => String(path ?? '').replace(/^body > /, '');
+/** The layout around the listing, for the report: the listing's box, the gaps above and below and what bounds them. */
+const summary = (x) =>
+  x ? { listing: x.listing, above: x.above ? { gap: round(x.above.gap, 2), by: name(x.above.path) } : null, below: x.below ? { gap: round(x.below.gap, 2), by: name(x.below.path) } : null, empty: (x.empty ?? []).map((e) => ({ path: name(e.path), height: round(e.height, 2) })) } : null;
+
+/**
+ * The collateral check as a result (compareComponent's shape): component
+ * `collateral` (`collateral@<state>` in a state), one instance, the
+ * differences the template's (decided ones aside).
+ * @param {{ page: string, viewport: number, state?: string | null }} at @param {ReturnType<typeof compareCollateral>} r @param {{ decided?: Record<string, any> }} [o]
+ */
+export const collateralResult = (at, r, { decided = {} } = {}) => {
+  const component = at.state ? `collateral@${at.state}` : 'collateral';
+  const diffs = decide(r.diffs.map((d) => ({ ...d, owner: 'template' })), { component: 'collateral', decided });
+  const templateWeight = diffs.filter((d) => d.owner === 'template').reduce((s, d) => s + d.weight, 0);
+  const score = scoreOf(r);
+  const templateScore = scoreOf({ checks: r.checks, weight: templateWeight });
+  return { component, page: at.page, viewport: at.viewport, state: at.state ?? null, score, templateScore, instances: r.checks ? [{ key: 'page', score, templateScore, checks: r.checks, weight: r.weight, pixels: null }] : [], diffs: aggregate([diffs]), ...(r.layout ? { layout: r.layout } : {}) };
+};
+
+/**
+ * Their products never paired with ours on a page (pairing.mjs
+ * `pairingFailure`): a CRITICAL result scoring 0, never a silent fallback to
+ * structure only. The verdict names it first.
+ * @param {{ page: string, viewport: number }} at @param {{ why: string, queries: any[] }} failure @param {number} asked their products
+ */
+export const pairingResult = (at, failure, asked) => ({
+  component: 'pairing',
+  page: at.page,
+  viewport: at.viewport,
+  state: null,
+  score: 0,
+  templateScore: 0,
+  instances: [{ key: 'pairing', score: 0, templateScore: 0, checks: WEIGHT.critical, weight: WEIGHT.critical, pixels: null }],
+  diffs: [{ part: 'root', prop: 'pairing', theirs: `${asked} products`, ours: '0 paired', delta: failure.why, severity: 'critical', group: 'pairing', weight: WEIGHT.critical, owner: 'template', count: 1, queries: failure.queries }],
+});
+
+/**
+ * A state's steps that could not be taken (a click target missing on ours:
+ * the drawer toggle our template lacks): CRITICAL, one per step and side.
+ * The state's components are measured as far as it got.
+ * @param {{ page: string, viewport: number, state: string }} at @param {{ step: number, kind: string, side: 'theirs' | 'ours', selector: string | null, error: string }[]} failed
+ */
+export const stateResult = (at, failed) => {
+  const diffs = failed.map((f) => ({ part: `step ${f.step}`, prop: 'state', theirs: f.side === 'theirs' ? `failed: ${f.error}` : 'taken', ours: f.side === 'ours' ? `failed: ${f.error}` : 'taken', delta: `${f.kind} ${f.selector ?? ''} failed on ${f.side}`.replace(/\s+/g, ' '), severity: 'critical', group: 'state', weight: WEIGHT.critical, owner: 'template', count: 1, selector: { theirs: f.side === 'theirs' ? f.selector : null, ours: f.side === 'ours' ? f.selector : null } }));
+  const checks = Math.max(1, failed.length) * WEIGHT.critical;
+  const weight = failed.length * WEIGHT.critical;
+  const score = scoreOf({ checks, weight });
+  return { component: `state@${at.state}`, page: at.page, viewport: at.viewport, state: at.state, score, templateScore: score, instances: [{ key: at.state, score, templateScore: score, checks, weight, pixels: null }], diffs };
+};
+
+/**
+ * The template's differences of the whole run, the same one at several
+ * viewports one finding: the list an agent fixes from, ranked by weight
+ * (CRITICAL and MAJOR before MINOR, then the weight they take off the score:
+ * the severity's weight times the instances and viewports it shows on).
+ * `owner: 'data'` gives the data's differences instead (for the client).
+ * @param {ReturnType<typeof compareComponent>[]} results
+ * @param {'template' | 'data'} [owner]
+ */
+export const findings = (results, owner = 'template') => {
+  const by = new Map();
+  for (const r of results)
+    for (const d of r.diffs ?? []) {
+      if ((d.owner ?? 'template') !== owner) continue;
+      const key = JSON.stringify([r.component, r.page, d.part, d.prop, d.prop === 'pixels' ? '' : d.theirs, d.prop === 'pixels' ? '' : d.ours]);
+      let f = by.get(key);
+      if (!f) {
+        const { count: _c, ratio: _r, ...rest } = d;
+        f = { component: r.component, page: r.page, ...rest, viewports: [], count: 0, total: 0, instances: 0 };
+        by.set(key, f);
+      }
+      if (!f.viewports.includes(r.viewport)) f.viewports.push(r.viewport);
+      f.count += d.count ?? 1;
+      f.instances += r.instances.length || 1;
+      f.total += (d.weight ?? WEIGHT.check) * (d.count ?? 1);
+      if (SEVERITY_RANK[d.severity] < SEVERITY_RANK[f.severity]) f.severity = d.severity;
+      if (r.selectors && !f.selector) f.selector = selectorOf(r.selectors, d.part);
+    }
+  // What follows `color` (currentColor: the borders, the outline, the decoration) with the same
+  // values is one fix: folded into the colour's finding (`also`).
+  for (const [k, f] of by) {
+    if (!FOLLOWS_COLOR.has(f.prop)) continue;
+    const c = by.get(JSON.stringify([f.component, f.page, f.part, 'color', f.theirs, f.ours]));
+    if (!c) continue;
+    (c.also ??= []).push(f.prop);
+    by.delete(k);
+  }
+  // A failed pairing first: until it pairs, every product's comparison is by structure only.
+  const blocking = (f) => (f.prop === 'pairing' ? -1 : f.severity === 'minor' ? 1 : 0);
+  return [...by.values()]
+    .map((f) => ({ ...f, viewports: f.viewports.sort((a, b) => a - b) }))
+    .sort((x, y) => blocking(x) - blocking(y) || y.total - x.total || SEVERITY_RANK[x.severity] - SEVERITY_RANK[y.severity] || (x.component < y.component ? -1 : x.component > y.component ? 1 : 0) || (x.part < y.part ? -1 : x.part > y.part ? 1 : 0) || (x.prop < y.prop ? -1 : x.prop > y.prop ? 1 : 0));
+};
+
+/** A part's selectors on both sides, page-level: the root's, then the part's within it. @param {{ theirs: string, ours: string, parts: Record<string, { theirs: string | null, ours: string | null }> }} s @param {string} part */
+export const selectorOf = (s, part) => {
+  if (part === 'root' || part === 'grid' || !s.parts?.[part]) return { theirs: s.theirs, ours: s.ours, role: s.role ?? null };
+  const p = s.parts[part];
+  return { theirs: p.theirs ? `${s.theirs} ${p.theirs}` : null, ours: p.ours ? `${s.ours} ${p.ours}` : null, part: { theirs: p.theirs, ours: p.ours }, role: p.role ?? null };
+};
+
+/**
+ * The verdict: the overall score (every difference, the data's too) and the
+ * template's score (the means over components and viewports), and whether
+ * the port has converged: the template's score at or over `target`, no
+ * CRITICAL or MAJOR template difference left, every mandatory component
+ * mapped or excluded (`coverage`, map.mjs), no component's template score
+ * under its threshold (`thresholds.components[name]`, else
+ * `thresholds.score`). Exit code 0 converged, 1 not, 2 nothing measured.
+ * @param {ReturnType<typeof compareComponent>[]} results
+ * @param {{ score?: number, components?: Record<string, number> }} thresholds
+ * @param {{ target?: number, coverage?: { ok: boolean, missing: string[] } | null }} [opts]
+ */
+export const verdict = (results, thresholds = {}, { target = TARGET, coverage = null } = {}) => {
+  const mean = (xs) => (xs.length ? round(xs.reduce((s, x) => s + x, 0) / xs.length, 1) : null);
+  const scored = results.filter((r) => r.score != null);
+  const overall = mean(scored.map((r) => r.score));
+  const templateScore = mean(scored.map((r) => r.templateScore ?? r.score).filter((s) => s != null));
+  const failing = scored
+    .map((r) => ({ component: r.component, page: r.page, viewport: r.viewport, score: r.templateScore ?? r.score, threshold: thresholds.components?.[baseOf(r.component)] ?? thresholds.score ?? 0 }))
+    .filter((r) => r.score < r.threshold);
+  const todo = findings(results);
+  const blocking = todo.filter((f) => f.severity !== 'minor');
+  const reasons = [];
+  // Their products never paired with ours: everything per product was compared by structure only. Loud, first.
+  for (const r of results.filter((x) => x.component === 'pairing')) reasons.push(`pairing failed on ${r.page} at ${r.viewport}px: ${r.diffs[0]?.delta ?? ''}`);
+  if (templateScore != null && templateScore < target) reasons.push(`the template score ${templateScore} is under the target ${target}`);
+  if (blocking.length) reasons.push(`${blocking.length} CRITICAL or MAJOR template difference${blocking.length > 1 ? 's' : ''} left`);
+  if (coverage && !coverage.ok) reasons.push(`mandatory components neither mapped nor excluded: ${coverage.missing.join(', ')}`);
+  if (failing.length) reasons.push(`${failing.length} under its threshold: ${failing.slice(0, 6).map((f) => `${f.component}@${f.viewport} ${f.score} < ${f.threshold}`).join(', ')}${failing.length > 6 ? ', …' : ''}`);
+  const converged = templateScore != null && !reasons.length;
+  return {
+    overall,
+    templateScore,
+    target,
+    blocking: blocking.length,
+    critical: blocking.filter((f) => f.severity === 'critical').length,
+    coverage: coverage ? { ok: coverage.ok, missing: coverage.missing } : null,
+    failing,
+    converged,
+    reasons: templateScore == null ? ['nothing was measured'] : reasons,
+    exitCode: templateScore == null ? 2 : converged ? 0 : 1,
+  };
+};
+/** The default `--target`: the template score a converged port reaches. */
+export const TARGET = 98;