@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/engine.mjs

@@ -0,0 +1,848 @@
+// The browser side of `yarn luma parity`: per page of the map and per viewport,
+// their page and ours (the same page with the integration's build in it,
+// showing the products theirs shows), settled, every mapped component
+// measured on both (parity/probe.mjs), paired (the same product on both
+// sides), captured as crops and compared (parity/compare.mjs, pixels.mjs);
+// then everything outside our components against their page without us
+// (the collateral check), and every scripted state of the page the same way.
+//
+// The engine gets pages from a driver, which decides what the network is
+// (the live site, a recording, the test suite's fake shop):
+//   driver.origin                      the storefront's origin
+//   driver.page(side, { width, device }) -> Page
+//                                      a fresh page for 'theirs' or 'ours', routes installed; `device`: the
+//                                      context options of a phone width (isMobile, hasTouch, userAgent), {} otherwise
+//   driver.wait?(side)                 called before every load of a page (pacing on a live site)
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EMPTY_PX, PROPS, TARGET, TOLERANCE, collateralResult, compareCollateral, compareComponent, findings, pairingResult, stateResult, verdict } from './compare.mjs';
+import { hintFor } from './hints.mjs';
+import { coverage, designSources, partMarker, pick, plan, stepOn } from './map.mjs';
+import { formatQueries, pairingFailure, queryCandidates } from './pairing.mjs';
+import { diffPng } from './pixels.mjs';
+import { alignInit, aroundOf, blocksOf, boxes, clsInit, collectIds, deepInit, edgesOf, framesInit, measure, mutationsInit, readWatches, seedRandom, stabilize, storageInit, strayControls, targetOf, theirHints } from './probe.mjs';
+import { FIELD, alignmentResult, compareAlignment, relationsOf } from './alignment.mjs';
+import { behaviourResult, compareOutcome, compareStray, fateOf, holdResult, knownIds, outcomeOf } from './behaviour.mjs';
+
+export class Blocked extends Error {}
+
+const SEED = 20261001;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** A phone's user agent: a site that lays its phone page out by the device (server-side, or a script reading it) shows its phone layout. */
+export const PHONE_UA = 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36';
+
+/**
+ * How a width is measured: up to the map's `phone` (default 767 px) as a
+ * phone (touch, isMobile: the page's meta viewport applies, a phone's user
+ * agent), else as a desktop window of that width. A shop whose phone grid is
+ * one column on a phone and two in a narrow desktop window is measured as a
+ * shopper's phone shows it. DPR stays 1 (the crops compare pixel for pixel).
+ * @param {number} width @param {{ phone?: number }} map
+ * @returns {{ mobile: boolean, isMobile?: boolean, hasTouch?: boolean, userAgent?: string }}
+ */
+export const deviceOf = (width, map) => (map.phone && width <= map.phone ? { mobile: true, isMobile: true, hasTouch: true, userAgent: PHONE_UA } : { mobile: false });
+/** The context options of a device (deviceOf), for a driver. @param {ReturnType<typeof deviceOf>} d */
+export const contextOf = ({ mobile: _m, ...o }) => o;
+
+/** A bot challenge, a block or a rate limit instead of the storefront's page ('' when it is the page). */
+export const challenge = async (res, page) => {
+  if (!res) return '';
+  const status = res.status();
+  const h = res.headers();
+  if (h['cf-mitigated'] === 'challenge') return `a Cloudflare challenge (HTTP ${status})`;
+  const title = await page.title().catch(() => '');
+  if (/verifying your browser|just a moment|attention required|are you a robot|captcha/i.test(title)) return `a bot challenge ("${title}", HTTP ${status})`;
+  if (status === 429) return 'HTTP 429 (rate limited, or a bot challenge)';
+  if (status === 403 || status === 503) return `HTTP ${status}`;
+  return '';
+};
+
+/** Waits until the page has had no request in flight for `quiet` ms (at most `max`). */
+const networkQuiet = async (page, inflight, quiet = 500, max = 8000) => {
+  const t0 = Date.now();
+  let since = Date.now();
+  while (Date.now() - t0 < max) {
+    if (inflight.size) since = Date.now();
+    else if (Date.now() - since >= quiet) return;
+    await sleep(50);
+  }
+};
+
+/** The layout of the measured roots unchanged over two reads (at most `tries`). */
+const layoutSettled = async (page, roots, tries = 8) => {
+  let last = await page.evaluate(boxes, roots);
+  for (let i = 0; i < tries; i++) {
+    await sleep(150);
+    const now = await page.evaluate(boxes, roots);
+    if (now === last) return true;
+    last = now;
+  }
+  return false;
+};
+
+/** The font each measured element's text is drawn in (CDP: the platform font with the most glyphs), not the declared family. */
+const renderedFonts = async (page, refs) => {
+  const out = new Map();
+  if (!refs.length) return out;
+  let cdp;
+  try {
+    cdp = await page.context().newCDPSession(page);
+    await cdp.send('DOM.enable');
+    await cdp.send('CSS.enable');
+    await cdp.send('DOM.getDocument', { depth: 0 });
+    for (const ref of refs) {
+      const { result } = await cdp.send('Runtime.evaluate', { expression: `window.__parityEls[${ref}]` });
+      if (!result.objectId) continue;
+      const { nodeId } = await cdp.send('DOM.requestNode', { objectId: result.objectId });
+      const { fonts } = await cdp.send('CSS.getPlatformFontsForNode', { nodeId });
+      const best = [...fonts].sort((a, b) => b.glyphCount - a.glyphCount || (a.familyName < b.familyName ? -1 : 1))[0];
+      if (best) out.set(ref, best.familyName);
+    }
+  } catch {
+    // Not Chromium, or the page moved on: no rendered fonts (the declared family is still compared).
+  } finally {
+    await cdp?.detach().catch(() => {});
+  }
+  return out;
+};
+
+/**
+ * Instances to compare: their order, keys both sides have (else by position:
+ * `byPosition`, another page's products), covering every part theirs shows at
+ * least once, then the first ones.
+ */
+export const sample = (theirs, ours, n, byPosition = false) => {
+  const byKey = new Map(ours.filter((o) => o.key != null).map((o) => [o.key, o]));
+  const keyed = !byPosition && theirs.some((t) => t.key != null) && byKey.size > 0;
+  const pairs = theirs.map((t, i) => ({ key: keyed ? t.key : String(i), theirs: t, ours: keyed ? (byKey.get(t.key) ?? null) : (ours[i] ?? null) })).filter((p) => p.ours);
+  const chosen = [];
+  const covered = new Set();
+  for (const p of pairs) {
+    if (chosen.length >= n) break;
+    const shows = Object.entries(p.theirs.parts ?? {}).filter(([, v]) => v.present).map(([k]) => k);
+    if (shows.some((k) => !covered.has(k))) {
+      chosen.push(p);
+      shows.forEach((k) => covered.add(k));
+    }
+  }
+  for (const p of pairs) {
+    if (chosen.length >= n) break;
+    if (!chosen.includes(p)) chosen.push(p);
+  }
+  return chosen.sort((a, b) => theirs.indexOf(a.theirs) - theirs.indexOf(b.theirs));
+};
+
+/** File-safe name. */
+const slug = (s) => String(s).replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').slice(0, 60) || 'x';
+
+/** The roots of a page's components on one side (theirs: their selectors; ours: ours, else the markers). */
+const rootsOf = (map, name, side, comps) =>
+  comps.map(([cn, c]) => (side === 'theirs' ? pick(c.theirs, 'theirs', name) : (pick(c.ours, 'ours', name) ?? partMarker(cn)))).filter(Boolean);
+
+/**
+ * Loads one page of the map on one side at one width and settles it.
+ * `o.path` loads another path (their page without us at our path, for the
+ * collateral check of a page compared against another page of theirs), and
+ * `o.wait: false` waits for no component there.
+ * @returns {Promise<{ page: import('playwright-core').Page, notes: string[], inflight: Set<any> }>}
+ */
+const open = async (driver, map, name, side, width, ids, o = {}) => {
+  const def = map.pages[name];
+  const notes = [];
+  await driver.wait?.(side);
+  const device = deviceOf(width, map);
+  // `isolated`: a context of its own (an interaction's actions reach no other page); `scope`: recorded and replayed apart.
+  const page = await driver.page(side, { width, device: contextOf(device), ...(o.isolated ? { isolated: true } : {}), ...(o.scope ? { scope: o.scope } : {}) });
+  const inflight = new Set();
+  page.on('request', (r) => inflight.add(r));
+  page.on('requestfinished', (r) => inflight.delete(r));
+  page.on('requestfailed', (r) => inflight.delete(r));
+  await page.setViewportSize({ width, height: map.height });
+  await page.addInitScript(seedRandom, SEED);
+  // Selectors see into open shadow roots (Luma's autocomplete, a web-component header): probe.mjs deepInit.
+  await page.addInitScript(deepInit);
+  // The storage the map sets (a view mode), and what the page reads from it (reported); the layout shifts (collateral).
+  await page.addInitScript(storageInit, { set: def.storage?.[side] ?? null });
+  await page.addInitScript(clsInit);
+  if (o.frames) await page.addInitScript(framesInit, o.frames);
+  if (side === 'ours' && map.products) {
+    const field = def.ids?.field ?? map.products.field;
+    await page.addInitScript(alignInit, { ids: ids ?? [], field, type: map.products.type, surface: map.products.surface, numeric: !!map.products.numeric, pair: map.products.pair, queries: o.queries ?? [''] });
+  }
+  const comps = Object.entries(map.components).filter(([, c]) => c.pages.includes(name));
+  const mine = o.wait === false ? [] : rootsOf(map, name, side, comps);
+  // A page with something to type: its input first; `ready` is then what typing brings.
+  const ready = o.wait === false ? null : def.type ? def.type.input : (def.ready[side] ?? mine[0]);
+  const path = o.path ?? def.paths?.[side] ?? def.path;
+  // Ours handed back by Luma's fail-safe (no render within its hold, 4 s: a cold first load on a
+  // busy machine) is loaded again, twice at most: the comparison is of our listing, not of the fallback.
+  for (let attempt = 0; ; attempt++) {
+    const res = await page.goto(new URL(path, driver.origin).href, { waitUntil: 'domcontentloaded', timeout: 120000 });
+    // `load` bounded: a request that never ends (a beacon, a stream) must not end the run.
+    await page.waitForLoadState('load', { timeout: 20000 }).catch(() => notes.push(`${name} ${width}px ${side}: no load event within 20 s (measured anyway)`));
+    const why = await challenge(res, page);
+    if (why) {
+      await page.close().catch(() => {});
+      throw new Blocked(`${path} (${side}): the storefront answered with ${why}`);
+    }
+    if (ready) await page.waitForSelector(ready, { state: 'visible', timeout: 30000 }).catch(() => notes.push(`${name} ${width}px ${side}: "${ready}" never showed`));
+    if (side !== 'ours') break;
+    await page.waitForFunction(() => !document.querySelector(':is(lbx-search, lbx-plp)[aria-busy="true"]'), null, { timeout: 15000 }).catch(() => notes.push(`${name} ${width}px ours: the listing stayed busy`));
+    const released = await page.evaluate(() => (window.__lbx?.health?.timeline ?? []).filter(([, w]) => / takeover released$/.test(w)).map(([, w]) => w)).catch(() => []);
+    if (!released.length) break;
+    notes.push(`${name} ${width}px ours: ${released.join(', ')}: Luma's fail-safe handed the page back (its request failed or came too late: an API answer the recording lacks, or a machine too busy for the 4 s hold)${attempt < 2 ? '; loaded again' : ''}`);
+    if (attempt >= 2) break;
+  }
+  if (def.type && o.wait !== false) {
+    await page.evaluate(stabilize, { roots: [], hide: map.hide[side] });
+    const input = page.locator(def.type.input).first();
+    await input.focus();
+    await input.fill('');
+    await input.pressSequentially(def.type.text, { delay: def.type.delay });
+    const after = def.ready[side] ?? mine[0];
+    if (after) await page.waitForSelector(after, { state: 'visible', timeout: 15000 }).catch(() => notes.push(`${name} ${width}px ${side}: "${after}" never showed after typing`));
+  }
+  await networkQuiet(page, inflight);
+  if (def.settleMs) await sleep(def.settleMs);
+  await page.evaluate(stabilize, { roots: mine, hide: map.hide[side] });
+  // LBX_PARITY_DUMP=<selector>: the markup it finds on both sides (writing a map).
+  if (process.env.LBX_PARITY_DUMP) console.error(`[${name} ${width}px ${side}] ${await page.evaluate((s) => document.querySelector(s)?.outerHTML.slice(0, 6000) ?? '(none)', process.env.LBX_PARITY_DUMP)}`);
+  if (!(await layoutSettled(page, mine))) notes.push(`${name} ${width}px ${side}: the layout kept moving`);
+  return { page, notes, inflight, ready, device };
+};
+
+/**
+ * A state's steps on one side (map.mjs STEPS), in order; the first that
+ * fails ends them (what follows depends on it). Then the page settles as on
+ * load. Returns the failures (stateResult).
+ * @param {{ page: any, inflight: Set<any> }} p @param {any} state @param {'theirs' | 'ours'} side @param {string[]} roots @param {string[]} hide
+ */
+const runSteps = async (p, state, side, roots, hide) => {
+  const { page } = p;
+  const failed = [];
+  for (const [i, st] of state.steps.entries()) {
+    if (!stepOn(st, side)) continue;
+    const sel = st[side];
+    const at = sel ? page.locator(sel).first() : null;
+    try {
+      if (st.kind === 'click') await at.click({ timeout: 10000 });
+      else if (st.kind === 'hover') await at.hover({ timeout: 10000 });
+      else if (st.kind === 'type') {
+        await at.focus({ timeout: 10000 });
+        await at.fill('');
+        await at.pressSequentially(st.text, { delay: st.delay });
+      } else if (st.kind === 'press') {
+        if (at) await at.press(st.key, { timeout: 10000 });
+        else await page.keyboard.press(st.key);
+      } else if (st.kind === 'wait-for') await page.waitForSelector(sel, { state: 'visible', timeout: 15000 });
+      else if (st.kind === 'scroll') {
+        if (st.y != null) await page.evaluate((y) => window.scrollTo(0, y), st.y);
+        else await at.scrollIntoViewIfNeeded({ timeout: 10000 });
+      }
+      // What a step brings (a drawer's request, a re-render) before the next one.
+      await networkQuiet(p.page, p.inflight, 300, 6000);
+    } catch (e) {
+      failed.push({ step: i + 1, kind: st.kind, side, selector: sel, error: String(e?.message ?? e).split('\n')[0].slice(0, 200) });
+      break;
+    }
+  }
+  await networkQuiet(page, p.inflight);
+  await page.evaluate(stabilize, { roots, hide });
+  await layoutSettled(page, roots);
+  return failed;
+};
+
+/** Re-takes a state's hover steps (a crop scrolls, and the pointer stays where it was: the hover state goes). */
+const rehover = async (page, state, side) => {
+  for (const st of state?.steps ?? []) if (st.kind === 'hover' && stepOn(st, side)) await page.locator(st[side]).first().hover({ timeout: 5000 }).catch(() => {});
+  if (state?.steps.some((s) => s.kind === 'hover')) await page.evaluate(stabilize, { roots: [], hide: [] });
+};
+
+/** Measures one component on a settled page. */
+const measureOn = async (page, map, name, comp, side, extra = {}) => {
+  const root = side === 'theirs' ? pick(comp.theirs, 'theirs', name) : (pick(comp.ours, 'ours', name) ?? partMarker(comp.name));
+  const parts = {};
+  for (const [pn, p] of Object.entries(comp.parts)) {
+    const sel = side === 'theirs' ? pick(p.theirs, 'theirs', name) : (pick(p.ours, 'ours', name) ?? partMarker(pn));
+    if (sel) parts[pn] = sel;
+  }
+  const inst = await page.evaluate(measure, {
+    root,
+    parts,
+    key: comp.each?.key ?? null,
+    all: !!comp.each,
+    max: comp.each?.max ?? 1,
+    grid: comp.grid ? { item: pick(comp.grid.item, side, name) } : null,
+    props: PROPS,
+    ...extra,
+  });
+  const refs = inst.flatMap((i) => [i.ref, ...Object.values(i.parts).filter((p) => p.present && p.text).map((p) => p.ref)]);
+  const fonts = await renderedFonts(page, refs);
+  for (const i of inst) {
+    i.font = i.text ? (fonts.get(i.ref) ?? null) : null;
+    for (const p of Object.values(i.parts)) if (p.present) p.font = p.text ? (fonts.get(p.ref) ?? null) : null;
+  }
+  return { root, parts, inst };
+};
+
+/** The catalog record shown in our instance: by their id (the key), else by our position. */
+const hitFor = (records, key, index) => {
+  if (!records.length) return null;
+  for (let i = records.length - 1; i >= 0; i--) {
+    const r = records[i].find((x) => String(x.id) === String(key));
+    if (r) return r.hit;
+  }
+  return records[records.length - 1][index]?.hit ?? null;
+};
+
+/** A crop of one measured element (its ref), animations and the caret off, the component's masks painted over. */
+const crop = async (page, ref, root, masks, { top = true } = {}) => {
+  if (top) await page.evaluate(() => window.scrollTo(0, 0));
+  const h = await page.evaluateHandle((i) => window.__parityEls[i], ref);
+  const el = h.asElement();
+  if (!el) return null;
+  try {
+    return await el.screenshot({ animations: 'disabled', caret: 'hide', scale: 'css', mask: root ? masks.map((m) => page.locator(root).locator(m)) : [], maskColor: '#FF00FF', timeout: 15000 });
+  } catch {
+    return null;
+  } finally {
+    await h.dispose();
+  }
+};
+
+/** Drops what is only the probe's bookkeeping from a measurement. */
+const clean = (i) => {
+  if (!i) return i;
+  const { ref, siblings: _s, ...rest } = i;
+  return { ...rest, parts: Object.fromEntries(Object.entries(i.parts ?? {}).map(([k, { ref: _r, ...v }]) => [k, v])) };
+};
+
+/** Our autocomplete panel when the map has none: the built-in marker in the overlay (its shadow root). */
+const AC_PANEL = '[data-lbx="ac-overlay"] [data-lbx-part~="ac-panel"]';
+
+/**
+ * The boxes the alignment compares on a side (docs/PARITY.md, "Alignment"):
+ * every component's root (a repeated one's first instance), the top-level
+ * parts of the components that are not repeated (a toolbar's sort, a facet
+ * group), and their search field (the map's `search.field`, else the page's
+ * typing input).
+ */
+const alignItems = (map, name, side, comps, def) => {
+  const items = [];
+  for (const cn of comps) {
+    const c = map.components[cn];
+    const root = side === 'theirs' ? pick(c.theirs, 'theirs', name) : (pick(c.ours, 'ours', name) ?? partMarker(cn));
+    if (!root) continue;
+    items.push({ key: cn, root });
+    if (c.each) continue;
+    for (const [pn, p] of Object.entries(c.parts)) {
+      if (p.parent) continue;
+      const sel = side === 'theirs' ? pick(p.theirs, 'theirs', name) : (pick(p.ours, 'ours', name) ?? partMarker(pn));
+      if (sel) items.push({ key: `${cn}.${pn}`, root, part: sel });
+    }
+  }
+  const field = pick(map.search?.field, side, name) ?? def.type?.input ?? null;
+  if (field) items.push({ key: FIELD, field });
+  return items;
+};
+
+/** Roles whose instances are their products (paired with the catalog's records). */
+const PRODUCTS = new Set(['tile', 'ac-row']);
+/** Roles whose text is facet values (textsOn). */
+const VALUES = new Set(['facets', 'facet-group', 'facet-value', 'chip']);
+
+/**
+ * How texts compare on a page. Ours against another page of theirs (our
+ * search against their category listing): their products are ours too
+ * (paired by id), so a product's texts stay exact; every other text (the
+ * count, a heading, a facet's title) is the shape, not the words ("6
+ * products" against "48 products"). Facet values are not compared as text:
+ * their category's values and our query's belong to other result sets (so
+ * are a facet container's and a group's texts, which hold the values).
+ * Unpaired ("ids": false) the products are others: their texts are not
+ * compared, the instances pair by position. A text the map turns off stays off.
+ * @param {any} def the page @param {any} comp the component @param {boolean} product
+ */
+export const textsOn = (def, comp, product) => {
+  if (!def?.cross) return { text: comp.text, parts: Object.fromEntries(Object.entries(comp.parts ?? {}).map(([pn, p]) => [pn, p.text])) };
+  const as = (t, role) => {
+    if (t === false) return false;
+    if (product) return def.unpaired ? false : t;
+    return VALUES.has(role) ? false : 'shape';
+  };
+  const parts = Object.entries(comp.parts ?? {}).map(([pn, p]) =>
+    // A paired product's part without its own setting: the component's (exact), as on any page.
+    [pn, p.text === undefined && product && !def.unpaired ? undefined : as(p.text === undefined ? comp.text : p.text, p.role)],
+  );
+  return { text: as(comp.text, comp.role), parts: Object.fromEntries(parts) };
+};
+
+/** Where to fix what is not one of our elements: the pairing (the map), the collateral check, a state's step. */
+const specialHint = (f) => {
+  if (f.prop === 'pairing') return { file: 'integration/parity.json', kind: 'map', hint: `integration/parity.json: pages.${f.page}.query (a query that finds their products), or products.field / products.pair / pages.${f.page}.ids` };
+  // The layout around the listing, an empty block under it: the hint names our element and its spacing.
+  if (f.component.startsWith('collateral') && f.hint) return { file: null, kind: 'collateral', hint: f.hint };
+  if (f.component.startsWith('collateral'))
+    return {
+      file: null,
+      kind: 'collateral',
+      hint:
+        f.prop === 'cls'
+          ? 'something of ours moves their page after it painted: hold their listing until ours renders (the early-hold snippet), reserve our height, no late insert above their content'
+          : `outside our components: ${f.part} is not as on their page without us; a style of ours that leaks (an unscoped selector in integration/**/*.css, style-host.css hiding too much), or a script of ours moving or removing it`,
+    };
+  // The page-level checks: the alignment, the hold, the behaviour (their own hint, else the element's template).
+  if (/^(alignment|hold|behaviour)(@|$)/.test(f.component) && f.hint) return { file: null, kind: 'template', hint: f.hint };
+  if (f.component === 'behaviour')
+    return {
+      file: null,
+      kind: 'template',
+      hint: `${f.part} ${f.prop === 'error' ? 'errs' : f.prop === 'effect' ? 'does nothing' : 'does otherwise'} on ours (theirs: ${f.theirs}; ours: ${f.ours}): the element's link or handler in the integration's template that renders ${f.selector?.ours ?? 'it'} (the URL it calls, the product id it sends: the one their tile uses)`,
+    };
+  if (f.prop === 'state') return { file: null, kind: 'template', hint: `the state's step: ${f.delta}; the element it targets (render it in the integration's template, or fix the step's selector in the map)` };
+  return null;
+};
+
+/**
+ * The verdict of a run's results, and the lists it is made of: `todo` (the
+ * template's differences ranked, each with where to fix it: hints.mjs over
+ * the integration's `files`), `data` (the data's, for the client), `decided`
+ * (the recorded product decisions' differences) and the map's `coverage`.
+ * @param {any[]} results @param {any} map @param {{ target?: number, files?: { path: string, text: string }[] }} [o]
+ */
+export const conclude = (results, map, { target = TARGET, files = [] } = {}) => {
+  const cov = coverage(map);
+  const todo = findings(results).map((f) => ({ ...f, fix: specialHint(f) ?? hintFor(f, files) }));
+  return { verdict: verdict(results, map.thresholds, { target, coverage: cov }), todo, data: findings(results, 'data'), decided: findings(results, 'decision'), coverage: cov };
+};
+
+/** Storage keys that read like a listing's view mode (grid or list, its columns). */
+const VIEW_KEY = /view|mode|grid|list|layout|column|display|tiles?\b/i;
+
+/**
+ * Everything of one page at one width, in one state (null: as loaded):
+ * every component measured on both sides before anything scrolls, the
+ * collateral blocks (their page without us, `off`, against ours), then the
+ * crops, then the components' hover.
+ */
+const compareOn = async (ctx) => {
+  const { map, name, width, def, comps, ids, records, unpaired, state, t, o, off, tol, out, decided } = ctx;
+  const results = [];
+  const tag = state ? `@${state.name}` : '';
+  const products = comps.filter((cn) => map.components[cn].each && PRODUCTS.has(map.components[cn].role));
+  // A tile's columns from its instances when no grid component is compared on the page (columns CRITICAL at any viewport).
+  const gridHere = comps.some((cn) => map.components[cn].grid);
+  const measured = [];
+  for (const cn of comps) {
+    const comp = { ...map.components[cn], name: cn };
+    const [a, b] = [await measureOn(t, map, name, comp, 'theirs'), await measureOn(o, map, name, comp, 'ours')];
+    const isProduct = products.includes(cn);
+    const pairs = comp.each ? sample(a.inst, b.inst, comp.each.sample, !!def.cross && def.unpaired) : [{ key: '0', theirs: a.inst[0] ?? null, ours: b.inst[0] ?? null }];
+    if (isProduct) for (const p of pairs) p.hit = hitFor(records, p.key, b.inst.indexOf(p.ours));
+    // The instances side by side (tiles in a row or a column, facet groups): their gaps; a tile's columns without a grid.
+    if (comp.each && pairs[0]) pairs[0].siblings = { theirs: a.inst[0]?.siblings ?? null, ours: b.inst[0]?.siblings ?? null, columns: comp.role === 'tile' && !gridHere };
+    const texts = textsOn(def, comp, isProduct);
+    const opts = { tol, text: texts.text, ignore: comp.ignore, role: comp.role, gaps: map.dataGaps ?? {}, decided, parts: Object.fromEntries(Object.entries(comp.parts).map(([pn, p]) => [pn, { text: texts.parts[pn], ignore: p.ignore, role: p.role }])) };
+    // The selectors as resolved on this page (the fix list names them; hints.mjs finds the file from ours).
+    const selectors = { theirs: a.root, ours: b.root, role: comp.role ?? null, parts: Object.fromEntries(Object.keys(comp.parts).map((pn) => [pn, { theirs: a.parts[pn] ?? null, ours: b.parts[pn] ?? null, role: comp.parts[pn].role ?? null }])) };
+    measured.push({ cn, comp, a, b, pairs, opts, selectors, unpaired: isProduct && cn === products[0] ? unpaired : [] });
+  }
+  // The collateral check: the blocks outside our components, before anything scrolls.
+  let coll = null;
+  if (map.collateral && off) {
+    const all = Object.entries(map.components).filter(([, c]) => c.pages.includes(name));
+    const ignore = [...map.collateral.ignore];
+    const [ta, tb] = [await off.evaluate(blocksOf, { regions: rootsOf(map, name, 'theirs', all), ignore: [...ignore, ...map.hide.theirs] }), await o.evaluate(blocksOf, { regions: rootsOf(map, name, 'ours', all), ignore: [...ignore, ...map.hide.ours] })];
+    // The layout shift of the load (not in a state: a step's own shift is the state's).
+    if (state) ta.cls = tb.cls = null;
+    // The layout around the listing: against their listing page (`t`) when ours is against another page of
+    // theirs (the design source of what surrounds the listing), else their page without us.
+    const ref = def.cross ? t : off;
+    const around = {
+      theirs: await ref.evaluate(aroundOf, { regions: rootsOf(map, name, 'theirs', all), ignore: [...ignore, ...map.hide.theirs], empty: EMPTY_PX }),
+      ours: await o.evaluate(aroundOf, { regions: rootsOf(map, name, 'ours', all), ignore: [...ignore, ...map.hide.ours], empty: EMPTY_PX }),
+      cross: !!def.cross,
+      gap: map.collateral.gap ?? 4,
+      against: def.paths.theirs,
+    };
+    coll = { ta, tb, around };
+  }
+  // The alignment: the edges their components line up on, required of ours, before anything scrolls.
+  let align = null;
+  if (map.alignment) {
+    const items = { theirs: alignItems(map, name, 'theirs', comps, def), ours: alignItems(map, name, 'ours', comps, def) };
+    // Our autocomplete panel against their visible search field, even with no panel of theirs (a house design: excluded).
+    const ac = comps.find((cn) => map.components[cn].role === 'ac-panel') ?? null;
+    if (def.type && !ac) items.ours.push({ key: 'ac-panel', root: AC_PANEL });
+    const [ba, bb] = [await t.evaluate(edgesOf, { items: items.theirs }), await o.evaluate(edgesOf, { items: items.ours })];
+    const relations = relationsOf(ba, { px: map.alignment.px, ignore: map.alignment.ignore });
+    const panel = ac ?? 'ac-panel';
+    if (def.type && bb[FIELD] && bb[panel] && !(ac && ba[ac] && ba[FIELD]) && !map.alignment.ignore.includes(`${panel}~${FIELD}`))
+      relations.push({ a: panel, b: FIELD, edge: 'left', required: `our panel against their visible search field${ac ? '' : ' (no panel of theirs mapped)'}` });
+    align = { r: compareAlignment(relations, bb, { px: map.alignment.px, theirs: ba }), found: { theirs: Object.values(ba).filter(Boolean).length, ours: Object.values(bb).filter(Boolean).length } };
+  }
+  const keepScroll = !!state?.steps.some((s) => s.kind === 'scroll');
+  // Then the crops, top of the page first between them.
+  for (const { cn, comp, a, b, pairs, opts, selectors, unpaired: lost } of measured) {
+    const rows = [];
+    for (const [k, p] of pairs.entries()) {
+      const row = { key: p.key, theirs: clean(p.theirs) ?? { present: false }, ours: clean(p.ours) ?? { present: false }, pixels: null, hit: p.hit ?? null, siblings: p.siblings ?? null };
+      if (p.theirs && p.ours) {
+        await rehover(t, state, 'theirs');
+        const ia = await crop(t, p.theirs.ref, a.root, comp.mask, { top: !keepScroll });
+        await rehover(o, state, 'ours');
+        const ib = await crop(o, p.ours.ref, b.root, comp.mask, { top: !keepScroll });
+        if (ia && ib) {
+          const d = diffPng(ia, ib, { threshold: tol.pixel });
+          row.pixels = { ratio: d.ratio, size: d.size, images: null };
+          if (out) {
+            const base = `${slug(cn)}${state ? `-${slug(state.name)}` : ''}-${slug(name)}-${width}-${k}`;
+            const images = { theirs: `img/${base}-theirs.png`, ours: `img/${base}-ours.png`, diff: `img/${base}-diff.png` };
+            writeFileSync(join(out, images.theirs), ia);
+            writeFileSync(join(out, images.ours), ib);
+            writeFileSync(join(out, images.diff), d.diff);
+            row.pixels.images = images;
+          }
+        }
+      }
+      rows.push(row);
+    }
+    results.push({ ...compareComponent({ component: `${cn}${tag}`, page: name, viewport: width, pairs: rows, unpaired: lost }, opts), state: state?.name ?? null, found: { theirs: a.inst.length, ours: b.inst.length }, selectors, against: def.paths.theirs });
+  }
+  if (align && align.r.checks) results.push({ ...alignmentResult({ page: name, viewport: width, state: state?.name ?? null }, align.r, { decided }), found: align.found, selectors: null, against: def.paths.theirs });
+  if (coll) {
+    // Each block both sides show at one size: its pixels.
+    const pixels = {};
+    const ours = new Map(coll.tb.blocks.map((x) => [x.path, x]));
+    for (const x of coll.ta.blocks) {
+      const y = ours.get(x.path);
+      if (x.ref == null || y?.ref == null || Math.abs(x.box.width - y.box.width) > 1 || Math.abs(x.box.height - y.box.height) > 1) continue;
+      const [ia, ib] = [await crop(off, x.ref, null, [], { top: !keepScroll }), await crop(o, y.ref, null, [], { top: !keepScroll })];
+      if (ia && ib) pixels[x.path] = diffPng(ia, ib, { threshold: tol.pixel }).ratio;
+    }
+    const r = compareCollateral(coll.ta, coll.tb, { tol, pixels, cls: map.collateral.cls, around: coll.around });
+    results.push({ ...collateralResult({ page: name, viewport: width, state: state?.name ?? null }, r, { decided }), found: { theirs: coll.ta.blocks.length, ours: coll.tb.blocks.length }, selectors: null, against: off === t ? def.paths.theirs : def.paths.ours });
+  }
+  // Last, hover: the first pair again, the pointer on each root.
+  for (const { cn, comp, pairs, opts, selectors } of measured) {
+    if (!comp.states.includes('hover') || !pairs[0]?.theirs || !pairs[0]?.ours) continue;
+    const hovered = [];
+    for (const [pg, side, m] of [[t, 'theirs', pairs[0].theirs], [o, 'ours', pairs[0].ours]]) {
+      const h = await pg.evaluateHandle((i) => window.__parityEls[i], m.ref);
+      await h.asElement()?.hover({ timeout: 5000 }).catch(() => {});
+      await pg.evaluate(stabilize, { roots: [], hide: [] });
+      const again = await measureOn(pg, map, name, comp, side, { ref: m.ref });
+      hovered.push(again.inst[0] ?? null);
+      await pg.mouse.move(0, 0);
+      await h.dispose();
+    }
+    results.push({ ...compareComponent({ component: `${cn}${tag}:hover`, page: name, viewport: width, pairs: [{ key: pairs[0].key, theirs: clean(hovered[0]) ?? { present: false }, ours: clean(hovered[1]) ?? { present: false }, hit: pairs[0].hit ?? null }] }, opts), state: state?.name ?? null, found: { theirs: 1, ours: 1 }, selectors, against: def.paths.theirs });
+  }
+  return results;
+};
+
+/**
+ * The hold check (docs/PARITY.md, "The hold"): our page loaded once (the
+ * build stores its rules), then reloaded with every frame recorded
+ * (probe.mjs framesInit): a frame that painted their listing (their
+ * components' elements, outside Luma's) is what production never shows with
+ * the early-hold snippet first in <head>. In a context of its own (the
+ * stored rules of no other page).
+ */
+const holdCheck = async ({ driver, map, name, width, ids, queries, notes }) => {
+  const def = map.pages[name];
+  const comps = Object.entries(map.components).filter(([, c]) => c.pages.includes(name));
+  const theirs = [...new Set(rootsOf(map, name, 'theirs', comps))];
+  // A page with something to type (the autocomplete) has no listing to hold.
+  if (!theirs.length || def.type) return null;
+  const o = await open(driver, map, name, 'ours', width, ids, { queries, isolated: true, scope: `hold:${name}`, frames: { theirs } });
+  try {
+    notes.push(...o.notes.map((n) => `hold: ${n}`));
+    await o.page.reload({ waitUntil: 'domcontentloaded', timeout: 60000 });
+    await o.page.waitForLoadState('load', { timeout: 20000 }).catch(() => {});
+    if (o.ready) await o.page.waitForSelector(o.ready, { state: 'visible', timeout: 15000 }).catch(() => {});
+    await o.page.waitForFunction(() => !document.querySelector(':is(lbx-search, lbx-plp)[aria-busy="true"]'), null, { timeout: 15000 }).catch(() => {});
+    await networkQuiet(o.page, o.inflight);
+    // A few frames more: what paints after the listing settled.
+    await o.page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => requestAnimationFrame(r)))));
+    const frames = await o.page.evaluate(() => window.__parityFrames ?? null);
+    const snippet = await o.page.evaluate(() => !!window.__lbx?.early || [...document.scripts].some((s) => !s.src && s.textContent.includes('lbx:early')));
+    if (!frames) notes.push(`hold: ${name} ${width}px: no frames recorded on the reload`);
+    return { frames, snippet };
+  } finally {
+    await o.page.close().catch(() => {});
+  }
+};
+
+/** A prefetch or prerender the page asks for (Luma's on a pointer down, speculation rules): no outcome of the action. */
+const prefetch = (r) => /prefetch|prerender/i.test(r.headers()['sec-purpose'] ?? r.headers()['purpose'] ?? '') || r.resourceType() === 'prefetch';
+
+/** The width an interaction runs at: its own, else the map's `behaviour.viewport`, else the widest one of the run. */
+const widthsOf = (it, map) => {
+  const own = (it.viewports ?? []).filter((v) => map.viewports.includes(v));
+  if (own.length) return own;
+  if (it.viewports?.length) return [];
+  return [map.behaviour?.viewport && map.viewports.includes(map.behaviour.viewport) ? map.behaviour.viewport : Math.max(...map.viewports)];
+};
+
+/**
+ * One interaction on one side (docs/PARITY.md, "Behaviour"): a fresh page in
+ * a context of its own (and its own recording scope), settled; the target
+ * (the paired product's instance, the part in it, the control in that);
+ * the watches read; every request of the action recorded, and aborted when
+ * it must not go through (behaviour.mjs fateOf: never checkout, payment or
+ * login; a POST to a cart, a compare list or a wishlist only when the map
+ * says "safe": true); the action taken; the page settled again (a
+ * navigation loaded, the network quiet); the watches read again.
+ */
+const act = async ({ driver, map, name, side, width, ids, queries, it, comp, key, scope, path = null, safe }) => {
+  const root = side === 'theirs' ? pick(comp.theirs, 'theirs', name) : (pick(comp.ours, 'ours', name) ?? partMarker(comp.name));
+  const part = path ?? (it.part === 'root' ? null : side === 'theirs' ? pick(comp.parts[it.part]?.theirs, 'theirs', name) : (pick(comp.parts[it.part]?.ours, 'ours', name) ?? partMarker(it.part)));
+  const o = await open(driver, map, name, side, width, side === 'ours' ? ids : null, { queries, isolated: true, scope });
+  const { page } = o;
+  const raw = { start: page.url(), final: page.url(), navigations: 0, requests: [], before: null, after: null, pageErrors: [], error: null, target: null };
+  try {
+    await page.addInitScript(mutationsInit);
+    await page.evaluate(mutationsInit);
+    if (!root || (it.part !== 'root' && !part)) {
+      raw.error = `no selector of ${side} for ${it.id}`;
+      return raw;
+    }
+    const target = await page.evaluate(targetOf, { root, part, key: comp.each?.key ?? null, value: key });
+    raw.target = target;
+    if (!target.found) {
+      raw.error = `the element is not there (${target.why})`;
+      return raw;
+    }
+    const watch = it.watch.map((w) => ({ name: w.name, sel: w[side] }));
+    raw.before = await page.evaluate(readWatches, { watch });
+    const recs = new Map();
+    page.on('request', (r) => {
+      if (r.frame() !== page.mainFrame() && r.resourceType() === 'document') return;
+      const rec = { method: r.method(), url: r.url(), type: r.resourceType(), body: r.postData() ?? null, fate: prefetch(r) ? 'asset' : fateOf({ method: r.method(), url: r.url(), type: r.resourceType() }, safe), status: null, failed: null };
+      recs.set(r, rec);
+      raw.requests.push(rec);
+    });
+    page.on('requestfinished', async (r) => {
+      const rec = recs.get(r);
+      if (rec) rec.status = (await r.response().catch(() => null))?.status() ?? null;
+    });
+    page.on('requestfailed', (r) => {
+      const rec = recs.get(r);
+      if (rec && rec.fate !== 'never' && rec.fate !== 'intercept') rec.failed = r.failure()?.errorText ?? 'failed';
+    });
+    page.on('framenavigated', (f) => {
+      if (f === page.mainFrame()) raw.navigations++;
+    });
+    page.on('pageerror', (e) => raw.pageErrors.push(String(e?.message ?? e).split('\n')[0].slice(0, 200)));
+    // Real actions on a live site: what must not go through is recorded and aborted, before any other route answers it.
+    await page.route('**/*', (route) => {
+      const q = route.request();
+      const fate = prefetch(q) ? 'asset' : fateOf({ method: q.method(), url: q.url(), type: q.resourceType() }, safe);
+      if (fate === 'never' || fate === 'intercept') return route.abort('blockedbyclient');
+      return route.fallback();
+    });
+    const h = await page.evaluateHandle(() => window.__parityTarget);
+    const el = h.asElement();
+    try {
+      if (it.action === 'select') {
+        const opts = target.options ?? [];
+        const want = it.option?.index != null ? opts[it.option.index] : it.option ? opts.find((x) => x.label === it.option[side] || x.value === it.option[side]) : opts.find((x) => !x.selected);
+        if (!want) throw new Error(`no option ${it.option ? JSON.stringify(it.option[side] ?? it.option.index) : 'to choose'} in the select`);
+        await el.selectOption(want.value, { timeout: 10000 });
+      } else if (o.device.hasTouch && it.action !== 'check') await el.tap({ timeout: 10000 });
+      else await el.click({ timeout: 10000 });
+    } catch (e) {
+      raw.error = `the ${it.action} could not be taken: ${String(e?.message ?? e).split('\n')[0].slice(0, 160)}`;
+    } finally {
+      await h.dispose().catch(() => {});
+    }
+    // What the action brings: a navigation (its load), its requests, a re-render.
+    await sleep(it.wait ?? 500);
+    if (raw.navigations) await page.waitForLoadState('load', { timeout: 20000 }).catch(() => {});
+    await networkQuiet(page, o.inflight, 400, 8000);
+    if (side === 'ours') await page.waitForFunction(() => !document.querySelector(':is(lbx-search, lbx-plp)[aria-busy="true"]'), null, { timeout: 10000 }).catch(() => {});
+    raw.final = page.url();
+    raw.after = await page.evaluate(readWatches, { watch }).catch(() => null);
+    return raw;
+  } finally {
+    await page.close().catch(() => {});
+  }
+};
+
+/**
+ * The behaviour of one page at one width (docs/PARITY.md, "Behaviour"):
+ * every declared interaction of its components, on both sides, for the
+ * paired product their first compared instance shows (the outcomes
+ * compared: behaviour.mjs), then our controls of those components that have
+ * no counterpart, each probed with nothing let through: one that does
+ * nothing is CRITICAL.
+ */
+const behaviourOn = async ({ driver, map, name, width, ids, queries, records, keys, decided, notes, log }) => {
+  const its = map.interactions.filter((x) => map.components[x.component]?.pages.includes(name) && widthsOf(x, map).includes(width));
+  if (!its.length) return null;
+  const r = { checks: 0, weight: 0, diffs: [] };
+  const merge = (x) => {
+    r.checks += x.checks;
+    r.weight += x.weight;
+    r.diffs.push(...x.diffs);
+  };
+  const seen = new Map();
+  const summary = [];
+  for (const it of its) {
+    const comp = { ...map.components[it.component], name: it.component };
+    const key = comp.each?.key ? (keys[it.component] ?? null) : null;
+    const n = (seen.get(it.id) ?? 0) + 1;
+    seen.set(it.id, n);
+    const tag = `${it.id}${n > 1 ? `#${n}` : ''}`;
+    log(`${name} at ${width}px, ${it.action} ${tag}`);
+    const hit = key != null ? hitFor(records, key, 0) : null;
+    const [ra, rb] = [
+      await act({ driver, map, name, side: 'theirs', width, ids, queries, it, comp, key, scope: `theirs:${name}:${tag}`, safe: it.safe }),
+      await act({ driver, map, name, side: 'ours', width, ids, queries, it, comp, key, scope: `ours:${name}:${tag}`, safe: it.safe }),
+    ];
+    const known = knownIds([key, ...(ra.target?.ids ?? []), ...(rb.target?.ids ?? [])], hit);
+    const cross = !!map.pages[name].cross;
+    const [oa, ob] = [outcomeOf(ra, known, { cross }), outcomeOf(rb, known, { cross })];
+    if (oa.missed || ob.missed) notes.push(`behaviour: ${tag} on ${name}: ${oa.missed + ob.missed} requests of the action not in the recording (re-record: yarn luma parity --record)`);
+    const cmp = compareOutcome(oa, ob, { part: it.id === it.component ? it.component : it.id });
+    // The selectors on both sides (the fix list names them; hints.mjs finds our template from ours).
+    const sel = (side) => {
+      const root = side === 'theirs' ? pick(comp.theirs, 'theirs', name) : (pick(comp.ours, 'ours', name) ?? partMarker(comp.name));
+      const p = it.part === 'root' ? null : side === 'theirs' ? pick(comp.parts[it.part]?.theirs, 'theirs', name) : (pick(comp.parts[it.part]?.ours, 'ours', name) ?? partMarker(it.part));
+      return root ? `${root}${p ? ` ${p}` : ''}` : null;
+    };
+    for (const d of cmp.diffs) d.selector = { theirs: sel('theirs'), ours: sel('ours'), role: comp.role ?? null };
+    merge(cmp);
+    summary.push({ id: tag, action: it.action, key, theirs: oa, ours: ob });
+  }
+  // Our controls without a counterpart, in the components that declare interactions.
+  if (map.behaviour?.scan !== false) {
+    const cns = [...new Set(its.map((x) => x.component))];
+    const items = cns.map((cn) => {
+      const c = map.components[cn];
+      const mapped = Object.entries(c.parts).filter(([, p]) => pick(p.theirs, 'theirs', name)).map(([pn, p]) => pick(p.ours, 'ours', name) ?? partMarker(pn));
+      return { component: cn, root: pick(c.ours, 'ours', name) ?? partMarker(cn), mapped, key: c.each?.key ?? null, value: c.each?.key ? (keys[cn] ?? null) : null };
+    });
+    const probe = await open(driver, map, name, 'ours', width, ids, { queries, isolated: true, scope: `ours:${name}:stray` });
+    const stray = await probe.page.evaluate(strayControls, { items, max: 6 }).catch(() => []);
+    await probe.page.close().catch(() => {});
+    const probed = [];
+    for (const [i, s] of stray.entries()) {
+      const comp = { ...map.components[s.component], name: s.component };
+      const key = comp.each?.key ? (keys[s.component] ?? null) : null;
+      const it = { id: `${s.component}.extra`, component: s.component, part: 'root', action: s.tag === 'select' ? 'select' : 'click', option: null, watch: [], safe: false, wait: 500 };
+      const raw = await act({ driver, map, name, side: 'ours', width, ids, queries, it, comp, key, scope: `ours:${name}:stray${i}`, path: s.path, safe: false });
+      probed.push({ ...s, outcome: outcomeOf(raw, knownIds([key, ...(raw.target?.ids ?? [])])) });
+    }
+    merge(compareStray(probed));
+    if (probed.length) summary.push(...probed.map((s) => ({ id: `${s.component}.extra`, action: 'click', control: `${s.tag} "${s.label}" (${s.path})`, ours: s.outcome })));
+  }
+  return behaviourResult({ page: name, viewport: width }, r, { decided, interactions: summary });
+};
+
+/**
+ * The whole run: every page of the map at every viewport, theirs then ours,
+ * every component compared, the collateral check; every state of the page;
+ * the verdict against `target` (conclude).
+ * @param {{ map: any, driver: { origin: string, page: (side: 'theirs' | 'ours', o?: { width: number, device: Record<string, unknown> }) => Promise<import('playwright-core').Page>, wait?: (side: string) => Promise<void> }, out?: string | null, log?: (s: string) => void, only?: string[], target?: number, files?: { path: string, text: string }[] }} opts
+ */
+export const runParity = async ({ map, driver, out = null, log = () => {}, only = [], target = TARGET, files = [] }) => {
+  const tol = { ...TOLERANCE, ...map.tolerance };
+  const results = [];
+  const notes = [];
+  const aligned = [];
+  const decided = map.decided ?? {};
+  // --only names components; the collateral check runs with them when it is named too.
+  const collateralOn = !!map.collateral && (!only.length || only.includes('collateral'));
+  // The page-level checks run with --only when it names them: the alignment, the hold, the behaviour (or the interaction's component).
+  const alignOn = !!map.alignment && (!only.length || only.includes('alignment'));
+  const holdOn = map.hold !== false && (!only.length || only.includes('hold'));
+  const cmap = { ...map, collateral: collateralOn ? map.collateral : null, alignment: alignOn ? map.alignment : null };
+  if (out) mkdirSync(join(out, 'img'), { recursive: true });
+  let stopped = null;
+  const close = (...ps) => Promise.all(ps.filter(Boolean).map((p) => p.close().catch(() => {})));
+  try {
+    for (const { page: name, components } of plan(map)) {
+      const comps = components.filter((c) => !only.length || only.includes(c));
+      const def = map.pages[name];
+      if (!comps.length && !collateralOn && !(holdOn && def.hold) && !(map.interactions ?? []).some((x) => components.includes(x.component) && only.includes('behaviour'))) continue;
+      for (const width of map.viewports) {
+        log(`${name} at ${width}px${deviceOf(width, map).mobile ? ' (a phone)' : ''}`);
+        const t = await open(driver, map, name, 'theirs', width, null);
+        notes.push(...t.notes);
+        const ids = def.ids ? await t.page.evaluate(collectIds, def.ids) : null;
+        if (def.ids && !ids.length) notes.push(`${name} ${width}px: no product ids on their page${def.cross ? ` ${def.paths.theirs}` : ''} ("${def.ids.selector}" [${def.ids.attr}])`);
+        // The queries their products are asked for with (an empty one finds nothing on many channels).
+        const hints = ids?.length ? await t.page.evaluate(theirHints, { selector: def.ids.selector }) : null;
+        const queries = queryCandidates({ queries: def.queries, oursPath: def.paths.ours, typed: def.type?.text ?? null, cross: def.cross, heading: hints?.heading ?? null, titles: hints?.titles ?? [] });
+        let o;
+        let off = null;
+        try {
+          o = await open(driver, map, name, 'ours', width, ids, { queries });
+          // Their page without us at our path (ours against another page of theirs): the collateral check's reference.
+          if (cmap.collateral) off = def.cross ? await open(driver, map, name, 'theirs', width, null, { path: def.paths.ours, wait: false }) : t;
+        } catch (e) {
+          await close(t.page, o?.page);
+          throw e;
+        }
+        notes.push(...o.notes, ...(off && off !== t ? off.notes : []));
+        const al = await o.page.evaluate(() => window.__parity?.aligned ?? []);
+        if (ids) aligned.push({ page: name, viewport: width, ids: ids.length, queries, requests: al });
+        // Their products never paired: CRITICAL, never a silent fallback to structure only.
+        const failure = pairingFailure(ids, al, { selector: def.ids?.selector, type: map.products?.type });
+        if (failure) results.push({ ...pairingResult({ page: name, viewport: width }, failure, ids.length), found: { theirs: ids.length, ours: 0 }, selectors: null, against: def.paths.theirs });
+        else for (const q of al) if (q.queries?.length > 1) notes.push(`${name} ${width}px: their products asked for with ${formatQueries(q.queries)}`);
+        // A view mode (grid or list, the columns) their page reads from storage: the map can pin it.
+        for (const r of await t.page.evaluate(() => window.__parityStorage ?? [])) if (VIEW_KEY.test(r.key)) notes.push(`${name}: their page reads ${r.area} "${r.key}" (${r.value === null ? 'not set' : JSON.stringify(r.value)}): if it is the listing's view mode (its columns), pin it with pages.${name}.storage`);
+        // The catalog's records our products show (the data's evidence), and their products the API did not find.
+        const records = ids ? await o.page.evaluate(() => window.__parity?.hits ?? []) : [];
+        const unpaired = al.length ? (al[al.length - 1].missing ?? []) : [];
+        const base = { map: cmap, name, width, def, comps, ids, records, unpaired, tol, out, decided };
+        const loaded = await compareOn({ ...base, state: null, t: t.page, o: o.page, off: off?.page ?? null });
+        results.push(...loaded);
+        await close(t.page, o.page, off && off !== t ? off.page : null);
+        // The hold: a reload of our page paints no frame of their listing (once per page, at its first width).
+        if (holdOn && def.hold && width === map.viewports[0]) {
+          const h = await holdCheck({ driver, map, name, width, ids, queries, notes });
+          const painted = (h?.frames ?? []).filter((f) => f.theirs).reduce((s, f) => s + f.n, 0);
+          if (painted) notes.push(`hold: ${name} ${width}px: a reload of our page painted their listing in ${painted} frame${painted > 1 ? 's' : ''}${h.snippet ? '' : ' (no early-hold snippet on the page)'}`);
+          if (h) results.push({ ...holdResult({ page: name, viewport: width }, h.frames, { snippet: h.snippet, decided }), found: { theirs: 1, ours: 1 }, selectors: null, against: def.paths.theirs });
+        }
+        // The behaviour: the declared interactions at their width, for the paired product the first compared instance shows.
+        const keys = Object.fromEntries(loaded.filter((r) => comps.includes(r.component) && r.instances?.length).map((r) => [r.component, r.instances[0].key]));
+        const bh = await behaviourOn({ driver, map: { ...map, interactions: (map.interactions ?? []).filter((x) => !only.length || only.includes('behaviour') || only.includes(x.component)) }, name, width, ids, queries, records, keys, decided, notes, log });
+        if (bh) results.push({ ...bh, found: { theirs: bh.interactions.length, ours: bh.interactions.length }, selectors: null, against: def.paths.theirs });
+        // Every scripted state of the page at this width: fresh pages, the steps on each side, measured again.
+        for (const state of def.states ?? []) {
+          if (state.viewports && !state.viewports.includes(width)) continue;
+          const sc = (state.components ?? components).filter((c) => !only.length || only.includes(c));
+          if (!sc.length && !cmap.collateral) continue;
+          log(`${name} at ${width}px, state ${state.name}`);
+          const t2 = await open(driver, map, name, 'theirs', width, null);
+          let o2;
+          try {
+            o2 = await open(driver, map, name, 'ours', width, ids, { queries });
+          } catch (e) {
+            await close(t2.page);
+            throw e;
+          }
+          notes.push(...t2.notes, ...o2.notes);
+          const all = Object.entries(map.components).filter(([, c]) => c.pages.includes(name));
+          const failed = [...(await runSteps(t2, state, 'theirs', rootsOf(map, name, 'theirs', all), map.hide.theirs)), ...(await runSteps(o2, state, 'ours', rootsOf(map, name, 'ours', all), map.hide.ours))];
+          if (failed.length) results.push({ ...stateResult({ page: name, viewport: width, state: state.name }, failed), found: { theirs: 1, ours: 1 }, selectors: null, against: def.paths.theirs });
+          const records2 = ids ? await o2.page.evaluate(() => window.__parity?.hits ?? []) : [];
+          // Their page without us in the state: theirs itself (another page of theirs has not our state).
+          results.push(...(await compareOn({ ...base, comps: sc, records: records2, state, t: t2.page, o: o2.page, off: def.cross ? null : t2.page })));
+          await close(t2.page, o2.page);
+        }
+      }
+    }
+  } catch (e) {
+    if (!(e instanceof Blocked)) throw e;
+    stopped = e.message;
+  }
+  if (map.draft || map.confirm?.length) notes.push(`the map is a draft from --init${map.confirm?.length ? ` with ${map.confirm.length} picks to confirm ("confirm")` : ''}: confirm them, then remove "draft" and "confirm"`);
+  return { results, ...conclude(results, map, { target, files }), pages: designSources(map), aligned, notes: [...new Set(notes)], stopped };
+};