@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/map.mjs

@@ -0,0 +1,640 @@
+// The parity map (`integration/parity.json` in the integration repository):
+// which pages to load, which of their elements is which of ours, what to
+// align and what to tolerate. JSON only, committed with the integration, read
+// by `yarn luma parity` and never written by it (`--init` writes a draft next to it).
+//
+// {
+//   "host": "www.shop.example",            the storefront (LBX_HOST overrides it)
+//   "viewports": [390, 1024, 1440], "height": 900,
+//   "locale": "en-GB", "timezone": "Europe/London",
+//   "tolerance": { "px": 0.5, "deltaE": 2.3, "alpha": 0.02, "pixel": 0.1, "pixels": 0.02 },
+//   "thresholds": { "score": 90, "components": { "tile": 95 } },
+//   "hide": [".cookie-banner"],            both sides, before measuring (never clicked)
+//   "block": { "theirs": ["^https://cdn\\.eu1\\.luigisbox\\.ai/"], "ours": [...] },
+//   "products": { "attr": "data-product-id", "field": "id", "type": "product", "surface": "lbs_collection_x" },
+//                                          "pair": "field" (default: their id = our hit's "field", fetched whatever the build's return_fields)
+//                                          or "url" (their links = our hits' url/web_url, by path; attr "href", field "web_url" by default)
+//   "pages": {
+//     "category": { "path": "/shoes", "ids": ".listing .tile",
+//                   "ready": { "theirs": ".listing .tile", "ours": "lbx-plp .tile" } },
+//     "autocomplete": { "path": "/", "type": { "input": "input[name=q]", "text": "shoe" },
+//                       "ids": { "selector": ".ac-row", "attr": "href", "transform": "absolute", "field": "web_url" } },
+//     "search": { "theirs": { "path": "/shoes", "ids": ".listing .tile" }, "ours": { "path": "/search?q=shoe" },
+//                 "query": "shoe" }
+//                                          a path per side ("path" is both sides' default): our search page against
+//                                          their category listing (their own search disabled); another page of theirs
+//                                          needs "ids" on their side (or "ids": false: by structure only)
+//                                          "query" (or a list): what their products are asked for with, by id (the API's
+//                                          search answers an empty query with nothing on many channels; docs/PARITY.md)
+//     "listing": { "path": "/shoes", "storage": { "theirs": { "localStorage": { "viewMode": "grid" } } },
+//                  "states": [{ "name": "drawer-open", "viewport": 390,
+//                               "steps": [{ "click": { "theirs": ".filters-toggle", "ours": "lbx-plp .filters-toggle" } },
+//                                         { "wait-for": { "theirs": ".drawer", "ours": "lbx-plp [data-lbx-part~=facets]" } }] }] }
+//                                          "storage": set before every load, per side (a view mode their page reads);
+//                                          "states": scripted steps (click, type, hover, press, wait-for, scroll), each
+//                                          side its own selectors; the page's components measured again in each state
+//   },
+//   "components": {
+//     "tile": { "pages": ["category"], "each": { "key": "data-product-id", "sample": 4 },
+//               "theirs": ".listing .tile", "ours": "lbx-plp .tile",
+//               "parts": { "title": ".tile__title", "price": { "theirs": ".price", "ours": "[data-lbx-part~=price]" } },
+//               "states": ["hover"], "mask": [".tile__image"], "ignore": ["transition"] },
+//     "grid": { "pages": ["category"], "theirs": ".listing", "ours": "lbx-plp [data-lbx-list]", "grid": { "item": ".tile" } },
+//     "count": { "pages": ["category"], "theirs": ".result-count", "ours": "[data-lbx-part~=count]", "text": "shape" }
+//   },
+//   "excluded": { "tile.badge": "their tiles show no badge" },
+//                                          mandatory components (MANDATORY) not compared, each with its reason
+//                                          or { "reason": …, "decision": "2026-09-30: …", "by": …, "date": … }: a recorded
+//                                          product decision; on a mapped component, part or property ("tile.badge color",
+//                                          "collateral") its differences are decided, not the template's
+//   "dataGaps": { "facetCounts": "the API returns no facet value counts" }
+//                                          differences owned by the data (GAPS, a component or "component.part"), each with its reason
+//   a part's "interact" (or a component's): true | "click" | "tap" | "check" | "select" | { "action", "watch": { "<name>": "<selector>" },
+//                                          "safe": true|false, "option", "viewport" }: the action taken on both sides for the paired product,
+//                                          its outcome compared (docs/PARITY.md, "Behaviour"; parity/behaviour.mjs)
+//   a part's "parts": its sub-controls ({ "slider": ".ui-slider", "min": "input.min" }), flattened as "<part>.<sub>" ("Parts of parts")
+//   "behaviour": { "viewport": 1440, "scan": true }   where interactions run; our controls without a counterpart probed
+//   "alignment": { "px": 1, "ignore": ["grid~sort align-right"] }   the edges their components share, required of ours; false: off
+//   "search": { "field": "input[name=q]" }  their search field (its visible box: the wrapper that draws it), for the alignment
+//   "hold": true                           a reload of our page paints no frame of their listing (also per page); false: off
+//   "phone": 767,                          widths up to this are a phone (touch, isMobile, a phone's user agent); false: never
+//   "collateral": { "ignore": [".rotating-banner"], "cls": 0.02, "gap": 4 }
+//                                          everything outside our components as on their page without us (false: off);
+//                                          `gap`: the px the space around the listing may differ from their listing page's
+// }
+//
+// A component's "role" (one of MANDATORY's, e.g. "tile", "facet-group") says
+// which mandatory component it is when its name does not: else its name
+// (kebab-cased: facetGroup is facet-group), else its ours selector's marker.
+//
+// A selector is a string (both sides), { "theirs": …, "ours": … }, and each
+// of those a string or { "<page name>": …, "default": … }.
+
+export const DEFAULTS = Object.freeze({
+  viewports: [390, 1024, 1440],
+  height: 900,
+  locale: 'en-US',
+  timezone: 'UTC',
+  thresholds: { score: 90, components: {} },
+  sample: 4,
+  gapMs: 2000,
+  /** Widths up to this are measured as a phone (touch, isMobile, a phone's user agent): a site's phone layout can follow the device, not the width. */
+  phone: 767,
+});
+
+/** Every Luigi's Box script (previous-generation widgets, the platform's loader): `--init` blocks them on both sides, so it never drafts such a widget as theirs. */
+export const BLOCK_LUIGIS = ['^https?://([a-z0-9-]+\\.)*luigisbox\\.(tech|com|ai)/'];
+/**
+ * Markup `--init` never takes as theirs: a previous Luigi's Box generation's
+ * widgets (rendered by its script, or server-side) and known search vendors'.
+ * Their design is no design of the client's to copy.
+ */
+export const LEGACY_MARKUP = Object.freeze([
+  '#lbx-ac-element', '.luigi-ac', '[class*="luigi-ac"]', '[id^="luigi"]', '[class*="luigi-search"]', '[class*="luigisbox"]', '[id^="lbx-"]',
+  '[class*="doofinder"]', '[class^="dfd-"]', '.aa-Panel', '.algolia-autocomplete', '[class^="ais-"]', '[class*="klevu"]', '[class*="snize"]', '[class^="boost-sd"]',
+]);
+
+/** Our side's default blocks: Luigi's Box scripts of the site (previous-generation widgets, the platform's loader): only the build under test runs. */
+export const BLOCK_OURS = ['^https://(cdn\\.luigisbox\\.(com|tech)|scripts\\.luigisbox\\.(com|tech)|cdn\\.[a-z0-9]+\\.luigisbox\\.ai)/'];
+/** Their side's: the platform's loader (Luma itself, if the site already includes it); their previous-generation Luigi's Box widgets are theirs. */
+export const BLOCK_THEIRS = ['^https://cdn\\.[a-z0-9]+\\.luigisbox\\.ai/'];
+
+/** Part names Luma's built-in templates mark with `data-lbx-part` (the default for ours when a part names no selector of ours). */
+export const PARTS = Object.freeze([
+  'tile', 'image', 'title', 'price', 'old-price', 'discount', 'badge', 'rating', 'availability', 'add-to-cart', 'compare', 'wishlist', 'slider', 'range-slider', 'range-min', 'range-max',
+  'list', 'count', 'sort', 'facets', 'facet-group', 'facet-title', 'facet-value', 'chip', 'pagination', 'more', 'empty',
+  'ac-panel', 'ac-section', 'ac-title', 'ac-row', 'ac-all', 'ac-empty',
+]);
+
+/**
+ * A range filter's sub-parts (a slider and its two inputs: "parts" of a part)
+ * and the markers Luma's range template gives ours
+ * (src/widgets/search/template-search-range-default.ts): the default of our
+ * side when the map names none.
+ */
+export const RANGE_PARTS = Object.freeze({ slider: 'range-slider', min: 'range-min', max: 'range-max' });
+/** Ours of a range filter whose sub-parts are RANGE_PARTS: Luma's facet group that holds the range. */
+export const RANGE_GROUP = '[data-lbx-part~="facet-group"]:has([data-lbx-range])';
+
+/**
+ * The components every map covers, or lists in "excluded" with a reason:
+ * `yarn luma parity` prints the coverage and does not converge while one is
+ * neither. `tile.<part>` is a part of the tile; `pagination` is covered by a
+ * pager or a "show more". docs/PARITY.md, "Coverage".
+ */
+export const MANDATORY = Object.freeze([
+  'tile', 'tile.image', 'tile.title', 'tile.price', 'tile.old-price', 'tile.badge',
+  'grid', 'facets', 'facet-group', 'facet-title', 'facet-value', 'sort', 'count', 'pagination', 'empty',
+  'ac-panel', 'ac-section', 'ac-row',
+]);
+/** Roles that cover a mandatory component of another name. */
+const ALIAS = Object.freeze({ list: 'grid', more: 'pagination', 'ac-empty': 'empty', 'ac-title': 'ac-section' });
+const TILE_PARTS = ['image', 'title', 'price', 'old-price', 'badge'];
+
+/**
+ * Known gaps of the API ("dataGaps"): their differences are the data's, not
+ * the template's (parity/owner.mjs). Besides these, a component's name or
+ * "component.part" declares all of its differences the data's.
+ */
+export const GAPS = Object.freeze({
+  facetCounts: "facet value counts the API does not return: a facet value's text that differs only by its count, a count element missing in ours",
+  empty: 'an empty state that cannot occur on the API: every difference of the empty state',
+  acSections: 'autocomplete sections the channel lacks (query suggestions, …): the sections, their titles, the panel height they add',
+});
+
+const isObj = (v) => v != null && typeof v === 'object' && !Array.isArray(v);
+
+/** The steps a state can take (docs/PARITY.md, "States"): each one's target a selector, both sides' or { "theirs", "ours" }. */
+export const STEPS = Object.freeze(['click', 'type', 'hover', 'press', 'wait-for', 'scroll']);
+const STEP_ALIAS = Object.freeze({ waitFor: 'wait-for' });
+
+/**
+ * One step of a state, normalized: { kind, theirs, ours, side, text?, delay?,
+ * key?, y? } (a side's selector null: the target is not on that side), or the
+ * error with it.
+ * @param {any} st @param {string} at where it is, for the error
+ * @returns {{ step?: any, error?: string }}
+ */
+export const normalizeStep = (st, at) => {
+  if (!isObj(st)) return { error: `${at}: { "<${STEPS.join('|')}>": "<selector>" | { "theirs": …, "ours": … } }` };
+  const keys = Object.keys(st).filter((k) => STEPS.includes(STEP_ALIAS[k] ?? k));
+  if (keys.length !== 1) return { error: `${at}: one of ${STEPS.join(', ')} per step (got ${Object.keys(st).join(', ') || 'nothing'})` };
+  const kind = STEP_ALIAS[keys[0]] ?? keys[0];
+  const raw = st[keys[0]];
+  const side = st.side ?? null;
+  if (side != null && side !== 'theirs' && side !== 'ours') return { error: `${at}.side: "theirs" or "ours"` };
+  const step = { kind, theirs: /** @type {string | null} */ (null), ours: /** @type {string | null} */ (null), side };
+  const byY = kind === 'scroll' && isObj(raw) && typeof raw.y === 'number';
+  // press: the key, on a selector given as "on" (else the focused element); scroll: a selector or { "y": px }.
+  const target = kind === 'press' ? st.on : byY ? null : raw;
+  if (byY) step.y = raw.y;
+  if (target != null) {
+    if (typeof target === 'string') step.theirs = step.ours = target;
+    else if (isObj(target) && ('theirs' in target || 'ours' in target)) {
+      step.theirs = typeof target.theirs === 'string' ? target.theirs : null;
+      step.ours = typeof target.ours === 'string' ? target.ours : null;
+    } else return { error: `${at}.${kind === 'press' ? 'on' : kind}: a selector, or { "theirs": "<selector>", "ours": "<selector>" }` };
+  }
+  if (kind === 'press') {
+    if (typeof raw !== 'string' || !raw) return { error: `${at}.press: a key ("Enter", "Escape", "ArrowDown")` };
+    step.key = raw;
+  } else if (kind === 'type') {
+    if (typeof st.text !== 'string') return { error: `${at}: "type" needs a "text"` };
+    if (step.theirs == null && step.ours == null) return { error: `${at}.type: the input's selector` };
+    step.text = st.text;
+    step.delay = Number(st.delay ?? 40);
+  } else if (kind === 'scroll') {
+    if (step.y == null && step.theirs == null && step.ours == null) return { error: `${at}.scroll: a selector, or { "y": <px> }` };
+  } else if (step.theirs == null && step.ours == null) return { error: `${at}.${kind}: a selector for at least one side` };
+  // "side": the step is taken on that side only.
+  if (side === 'theirs') step.ours = null;
+  if (side === 'ours') step.theirs = null;
+  return { step };
+};
+
+/** The actions an interaction takes (docs/PARITY.md, "Behaviour"): `tap` is a click on a phone width. */
+export const ACTIONS = Object.freeze(['click', 'tap', 'check', 'select']);
+
+/** A selector both sides share, or { theirs, ours } (either null), as { theirs, ours }; null when it is neither. */
+const sidesOf = (v) => {
+  if (typeof v === 'string') return { theirs: v, ours: v };
+  if (isObj(v) && ('theirs' in v || 'ours' in v)) return { theirs: typeof v.theirs === 'string' ? v.theirs : null, ours: typeof v.ours === 'string' ? v.ours : null };
+  return null;
+};
+
+/**
+ * A part's (or a component's) interactions, normalized (docs/PARITY.md,
+ * "Behaviour"): `"interact": true | "<action>" | { … } | [{ … }]`, each
+ * { action, option, watch, safe, wait, viewports }. `watch`: a selector, a
+ * list, or { "<name>": <selector or { theirs, ours }> }: the state read before
+ * and after the action (a counter, a checked state, a text). `safe`: true
+ * lets the action's requests through, false only records them (aborted:
+ * compared, never sent); unset, a POST to a cart, a compare list or a
+ * wishlist is not sent. `option` (select): the option to choose, by its
+ * label or value, both sides' or per side (default: the first one not
+ * selected).
+ * @param {any} raw @param {string} at where it is, for the errors
+ * @returns {{ list: any[], errors: string[] }}
+ */
+export const normalizeInteract = (raw, at) => {
+  const errors = [];
+  const list = [];
+  if (raw == null || raw === false) return { list, errors };
+  const items = Array.isArray(raw) ? raw : [raw];
+  for (const [i, x] of items.entries()) {
+    const where = Array.isArray(raw) ? `${at}[${i}]` : at;
+    const o = x === true ? {} : typeof x === 'string' ? { action: x } : isObj(x) ? x : null;
+    if (!o) {
+      errors.push(`${where}: true, an action (${ACTIONS.join(', ')}), or { "action", "watch", "safe" }`);
+      continue;
+    }
+    const action = o.action ?? 'click';
+    if (!ACTIONS.includes(action)) errors.push(`${where}.action: one of ${ACTIONS.join(', ')}`);
+    const watch = [];
+    const w = o.watch;
+    if (w != null) {
+      const entries = typeof w === 'string' ? [[w, w]] : Array.isArray(w) ? w.map((s) => [String(s), s]) : isObj(w) && !('theirs' in w || 'ours' in w) ? Object.entries(w) : [['watch', w]];
+      for (const [name, sel] of entries) {
+        const s = sidesOf(sel);
+        if (!s || (s.theirs == null && s.ours == null)) errors.push(`${where}.watch: a selector, a list of them, or { "<name>": "<selector>" | { "theirs", "ours" } }`);
+        else watch.push({ name, ...s });
+      }
+    }
+    if (o.safe != null && typeof o.safe !== 'boolean') errors.push(`${where}.safe: true (let it through) or false (record the request, never send it)`);
+    const option = o.option == null ? null : typeof o.option === 'number' ? { index: o.option } : sidesOf(o.option);
+    if (o.option != null && !option) errors.push(`${where}.option: the option's label or value (or its index), or { "theirs", "ours" }`);
+    const vps = o.viewport ?? o.viewports;
+    const viewports = vps == null ? null : (Array.isArray(vps) ? vps : [vps]).map(Number);
+    if (viewports && !viewports.every((v) => Number.isInteger(v) && v >= 200 && v <= 3840)) errors.push(`${where}.viewport: a width (or a list) in CSS px`);
+    list.push({ action, option, watch, safe: typeof o.safe === 'boolean' ? o.safe : null, wait: Number(o.wait ?? 500), viewports });
+  }
+  return { list, errors };
+};
+
+/** Whether a step is taken on a side. @param {any} step @param {'theirs' | 'ours'} side */
+export const stepOn = (step, side) => (step.side ? step.side === side : step[side] != null || (step.kind === 'press' && step.theirs == null && step.ours == null) || (step.kind === 'scroll' && step.y != null));
+
+/** Storage a page is loaded with: { localStorage: { k: v }, sessionStorage: { k: v } } (values as strings), or null. */
+const storageOf = (v) => {
+  if (!isObj(v)) return null;
+  const out = {};
+  for (const area of ['localStorage', 'sessionStorage']) if (isObj(v[area])) out[area] = Object.fromEntries(Object.entries(v[area]).map(([k, x]) => [k, typeof x === 'string' ? x : JSON.stringify(x)]));
+  return Object.keys(out).length ? out : null;
+};
+/** facetGroup -> facet-group. @param {string} s */
+export const kebab = (s) => String(s).replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^-/, '');
+/** The marker a selector ends with (`[data-lbx-part~="title"]`, `[data-lbx-part=title]`), or null. @param {unknown} sel */
+export const markerOf = (sel) => (typeof sel === 'string' ? (/\[data-lbx-part[~*]?=["']?([a-z-]+)["']?\]\s*$/.exec(sel)?.[1] ?? null) : null);
+/** Some selector of ours (a per-page one's default or first). */
+const oursOf = (sel) => {
+  const v = pick(sel, 'ours');
+  if (v != null || !isObj(sel) || !isObj(sel.ours)) return v;
+  return sel.ours.default ?? Object.values(sel.ours).find((x) => typeof x === 'string') ?? null;
+};
+const ROLES = new Set([...MANDATORY.map((m) => m.replace(/^tile\./, '')), ...Object.keys(ALIAS)]);
+/** A component's role: its "role", else its name (kebab-cased) when it is one, else its ours selector's marker. @param {string} name @param {any} c */
+export const roleOf = (name, c) => {
+  if (typeof c?.role === 'string') return kebab(c.role);
+  const n = kebab(String(name).replace(/:hover$/, ''));
+  if (ROLES.has(n) || PARTS.includes(n)) return n;
+  return markerOf(oursOf(c?.ours)) ?? (c?.grid ? 'grid' : null);
+};
+/** A part's role: its "role", else its name (kebab-cased) when it is one, else its ours selector's marker. @param {string} name @param {any} p */
+export const partRoleOf = (name, p) => {
+  if (typeof p?.role === 'string') return kebab(p.role);
+  const n = kebab(name);
+  if (ROLES.has(n) || PARTS.includes(n)) return n;
+  return markerOf(oursOf(p?.ours)) ?? null;
+};
+
+/**
+ * A selector for one side on one page, or null.
+ * @param {any} sel @param {'theirs' | 'ours'} side @param {string} [page]
+ * @returns {string | null}
+ */
+export const pick = (sel, side, page) => {
+  if (sel == null) return null;
+  if (typeof sel === 'string') return sel;
+  if (!isObj(sel)) return null;
+  const v = 'theirs' in sel || 'ours' in sel ? sel[side] : sel;
+  if (v == null) return null;
+  if (typeof v === 'string') return v;
+  if (isObj(v)) return (page != null ? v[page] : undefined) ?? v.default ?? null;
+  return null;
+};
+
+/** Ours for a part that names none: the built-in templates' marker. @param {string} name */
+export const partMarker = (name) => `[data-lbx-part~="${kebab(name)}"]`;
+
+/**
+ * The map with defaults filled in, or the problems with it.
+ * @param {any} raw
+ * @returns {{ map: any, errors: string[] }}
+ */
+export const normalize = (raw) => {
+  const errors = [];
+  if (!isObj(raw)) return { map: null, errors: ['the map is not a JSON object'] };
+  const map = {
+    host: raw.host ?? null,
+    viewports: Array.isArray(raw.viewports) && raw.viewports.length ? raw.viewports.map(Number) : [...DEFAULTS.viewports],
+    height: Number(raw.height ?? DEFAULTS.height),
+    locale: raw.locale ?? DEFAULTS.locale,
+    timezone: raw.timezone ?? DEFAULTS.timezone,
+    tolerance: { ...(isObj(raw.tolerance) ? raw.tolerance : {}) },
+    thresholds: { score: raw.thresholds?.score ?? DEFAULTS.thresholds.score, components: { ...(raw.thresholds?.components ?? {}) } },
+    hide: { theirs: [], ours: [] },
+    block: { theirs: [...BLOCK_THEIRS], ours: [...BLOCK_OURS] },
+    products: isObj(raw.products) ? { type: 'product', ...raw.products, pair: raw.products.pair ?? 'field' } : null,
+    archive: { ignore: raw.archive?.ignore ?? null },
+    excluded: /** @type {Record<string, string>} */ ({}),
+    dataGaps: /** @type {Record<string, string>} */ ({}),
+    // A draft from --init, and the picks it was least sure of.
+    draft: raw.draft === true,
+    confirm: Array.isArray(raw.confirm) ? raw.confirm.filter((x) => typeof x === 'string') : [],
+    gapMs: Number(raw.gapMs ?? DEFAULTS.gapMs),
+    phone: raw.phone === false ? 0 : Number(raw.phone ?? DEFAULTS.phone),
+    // Everything outside our components, as on their page without us (docs/PARITY.md, "The collateral check").
+    collateral: raw.collateral === false ? null : { ignore: Array.isArray(raw.collateral?.ignore) ? raw.collateral.ignore.filter((x) => typeof x === 'string') : [], cls: Number(raw.collateral?.cls ?? 0.02), gap: Number(raw.collateral?.gap ?? 4) },
+    /** Recorded product decisions on what the map compares ("excluded" with a "decision"): their differences are decided, not the template's. */
+    decided: /** @type {Record<string, { reason: string, decision: string, by?: string, date?: string }>} */ ({}),
+    /** The product decisions recorded with the exclusion of a mandatory component. */
+    decisions: /** @type {Record<string, { decision: string, by?: string, date?: string }>} */ ({}),
+    // A reload of our page, the rules stored, paints no frame of their listing (docs/PARITY.md, "The hold"); false: off.
+    hold: raw.hold !== false,
+    // The edges their components line up on, required of ours (docs/PARITY.md, "Alignment"); false: off.
+    alignment: raw.alignment === false ? null : { px: Number(raw.alignment?.px ?? 1), ignore: Array.isArray(raw.alignment?.ignore) ? raw.alignment.ignore.filter((x) => typeof x === 'string') : [] },
+    // Their search field (the input; its visible box is the wrapper that draws it): default, a typing page's input.
+    search: { field: sidesOf(raw.search?.field) },
+    // The interactions (docs/PARITY.md, "Behaviour"): at which width (default the widest), our controls without a counterpart probed.
+    behaviour: { viewport: raw.behaviour?.viewport == null ? null : Number(raw.behaviour.viewport), scan: raw.behaviour?.scan !== false },
+    /** Every declared interaction: { id, component, part, …normalizeInteract }. */
+    interactions: /** @type {any[]} */ ([]),
+    pages: {},
+    components: {},
+  };
+  if (raw.alignment != null && raw.alignment !== false && !isObj(raw.alignment)) errors.push('alignment: false, or { "px": 1, "ignore": ["grid~sort align-right"] }');
+  if (map.alignment && !(map.alignment.px >= 0)) errors.push('alignment.px: how far an edge may be off and still line up, in CSS px (default 1)');
+  if (raw.search != null && (!isObj(raw.search) || (raw.search.field != null && !map.search.field))) errors.push('search: { "field": "<their search input>" | { "theirs", "ours" } }');
+  if (raw.behaviour != null && (!isObj(raw.behaviour) || (map.behaviour.viewport != null && !Number.isInteger(map.behaviour.viewport)))) errors.push('behaviour: { "viewport": <the width interactions run at>, "scan": true }');
+  if (!Number.isFinite(map.phone) || map.phone < 0) errors.push('phone: the widest viewport measured as a phone, in CSS px (default 767), or false');
+  if (raw.collateral != null && raw.collateral !== false && raw.collateral !== true && !isObj(raw.collateral)) errors.push('collateral: false, or { "ignore": ["<selector>"], "cls": 0.02 }');
+  if (map.collateral && !(map.collateral.cls >= 0)) errors.push('collateral.cls: the layout shift ours may add, 0-1 (default 0.02)');
+  if (map.collateral && !(map.collateral.gap >= 0)) errors.push('collateral.gap: the px the space around the listing may differ from their listing page\'s (default 4)');
+  const byUrl = map.products?.pair === 'url';
+  if (map.products && map.products.pair !== 'field' && !byUrl) errors.push('products.pair: "field" (by products.field, the default) or "url" (by their links)');
+  for (const side of /** @type {const} */ (['theirs', 'ours'])) {
+    const h = Array.isArray(raw.hide) ? raw.hide : isObj(raw.hide) ? (raw.hide[side] ?? []) : [];
+    map.hide[side] = h.filter((x) => typeof x === 'string');
+    if (isObj(raw.block) && Array.isArray(raw.block[side])) map.block[side] = raw.block[side];
+  }
+  for (const [side, list] of Object.entries(map.block))
+    for (const re of list)
+      try {
+        new RegExp(re);
+      } catch {
+        errors.push(`block.${side}: "${re}" is not a regular expression`);
+      }
+  if (!map.viewports.every((v) => Number.isInteger(v) && v >= 200 && v <= 3840)) errors.push('viewports: widths in CSS px (200-3840)');
+  if (!isObj(raw.pages) || !Object.keys(raw.pages).length) errors.push('pages: at least one page ({ "name": { "path": "/…" } })');
+  for (const [name, p] of Object.entries(isObj(raw.pages) ? raw.pages : {})) {
+    // Each side's path: its own ("theirs": { "path" }, "ours": { "path" }), else the shared "path".
+    // Their page can be another one than ours: our search against their category listing (docs/PARITY.md).
+    const sideDef = (s) => (isObj(p?.[s]) ? p[s] : {});
+    const paths = isObj(p) ? { theirs: sideDef('theirs').path ?? p.path, ours: sideDef('ours').path ?? p.path } : { theirs: undefined, ours: undefined };
+    const badPath = (v) => typeof v !== 'string' || !v.startsWith('/');
+    if (!isObj(p) || badPath(paths.theirs) || badPath(paths.ours)) {
+      errors.push(isObj(p) && (p.theirs != null || p.ours != null) ? `pages.${name}: a path per side starting with "/" ("theirs": { "path" }, "ours": { "path" }, or a shared "path")` : `pages.${name}: a "path" starting with "/"`);
+      continue;
+    }
+    for (const s of ['theirs', 'ours']) if (p[s] != null && !isObj(p[s])) errors.push(`pages.${name}.${s}: { "path": "/…" }`);
+    if (sideDef('ours').ids !== undefined) errors.push(`pages.${name}.ours.ids: their products are read on their page ("ids", or "theirs": { "ids" })`);
+    const rawIds = sideDef('theirs').ids !== undefined ? sideDef('theirs').ids : p.ids;
+    const cross = paths.theirs !== paths.ours;
+    // "ids": false: not paired (another page's products): compared by structure.
+    const unpaired = rawIds === false;
+    if (cross && rawIds == null) errors.push(`pages.${name}: our ${paths.ours} is compared against their ${paths.theirs}, another page: declare "ids" on their side ("theirs": { "path": "${paths.theirs}", "ids": "<their tiles>" }), so ours shows their products; or "ids": false to compare by structure only`);
+    const ids = typeof rawIds === 'string' ? { selector: rawIds } : isObj(rawIds) ? rawIds : null;
+    if (ids && typeof ids.selector !== 'string') errors.push(`pages.${name}.ids: a "selector"`);
+    map.pages[name] = {
+      path: paths.theirs,
+      paths,
+      cross,
+      unpaired,
+      ready: { theirs: pick(p.ready, 'theirs', name), ours: pick(p.ready, 'ours', name) },
+      type: isObj(p.type) && typeof p.type.input === 'string' && typeof p.type.text === 'string' ? { input: p.type.input, text: p.type.text, delay: Number(p.type.delay ?? 40) } : null,
+      ids: ids ? { attr: ids.attr ?? map.products?.attr ?? (byUrl ? 'href' : null), field: ids.field ?? map.products?.field ?? (byUrl ? 'web_url' : null), child: ids.child ?? null, transform: ids.transform ?? null, selector: ids.selector, max: Number(ids.max ?? 60) } : null,
+      settleMs: Number(p.settleMs ?? 0),
+      hold: p.hold !== false,
+      // What their products are asked for with, by id, first (an empty query finds nothing on many channels): pairing.mjs.
+      queries: (typeof p.query === 'string' ? [p.query] : Array.isArray(p.query) ? p.query : []).filter((q) => typeof q === 'string' && q.trim()).map((q) => q.trim()),
+      // Storage set before every load (their page's view mode, …): both sides', or per side.
+      storage: { theirs: storageOf(isObj(p.storage?.theirs) ? p.storage.theirs : p.storage), ours: storageOf(isObj(p.storage?.ours) ? p.storage.ours : p.storage) },
+      states: /** @type {{ name: string, viewports: number[] | null, components: string[] | null, steps: any[] }[]} */ ([]),
+    };
+    if (p.query != null && typeof p.query !== 'string' && !Array.isArray(p.query)) errors.push(`pages.${name}.query: a query (or a list) that finds their products`);
+    if (p.storage != null && !isObj(p.storage)) errors.push(`pages.${name}.storage: { "localStorage": { "<key>": "<value>" } } (or per side: "theirs", "ours")`);
+    if (p.states != null && !Array.isArray(p.states)) errors.push(`pages.${name}.states: a list of { "name", "steps": [...] }`);
+    for (const [i, st] of (Array.isArray(p.states) ? p.states : []).entries()) {
+      const at = `pages.${name}.states[${i}]`;
+      if (!isObj(st) || typeof st.name !== 'string' || !/^[\w-]+$/.test(st.name)) {
+        errors.push(`${at}: a "name" (letters, digits, - or _)`);
+        continue;
+      }
+      if (map.pages[name].states.some((x) => x.name === st.name)) errors.push(`${at}: another state is named "${st.name}"`);
+      const vps = st.viewport ?? st.viewports;
+      const viewports = vps == null ? null : (Array.isArray(vps) ? vps : [vps]).map(Number);
+      if (viewports && !viewports.every((v) => Number.isInteger(v) && v >= 200 && v <= 3840)) errors.push(`${at}.viewport: a width (or a list) in CSS px`);
+      if (!Array.isArray(st.steps) || !st.steps.length) errors.push(`${at}.steps: at least one step`);
+      const steps = [];
+      for (const [j, x] of (Array.isArray(st.steps) ? st.steps : []).entries()) {
+        const r = normalizeStep(x, `${at}.steps[${j}]`);
+        if (r.error) errors.push(r.error);
+        else steps.push(r.step);
+      }
+      map.pages[name].states.push({ name: st.name, viewports, steps, components: Array.isArray(st.components) ? st.components.map(String) : null });
+    }
+    if (p.type != null && !map.pages[name].type) errors.push(`pages.${name}.type: { "input": "<selector>", "text": "<what to type>" }`);
+    if (ids && (!map.pages[name].ids.attr || !map.pages[name].ids.field)) errors.push(`pages.${name}.ids: "attr" and "field" (or "products.attr" / "products.field")`);
+    if (ids && !map.products) errors.push(`pages.${name}.ids: needs "products" (the products' "type", and optionally a collections "surface" to fetch them by id)`);
+  }
+  if (!isObj(raw.components) || !Object.keys(raw.components).length) errors.push('components: at least one component');
+  for (const [name, c] of Object.entries(isObj(raw.components) ? raw.components : {})) {
+    if (!isObj(c)) {
+      errors.push(`components.${name}: an object`);
+      continue;
+    }
+    const pages = (Array.isArray(c.pages) ? c.pages : typeof c.pages === 'string' ? [c.pages] : Object.keys(map.pages)).filter((p) => {
+      if (map.pages[p]) return true;
+      errors.push(`components.${name}.pages: no page "${p}"`);
+      return false;
+    });
+    if (pick(c.theirs ?? c.root, 'theirs', pages[0]) == null && !pages.some((p) => pick(c.theirs ?? c.root, 'theirs', p))) errors.push(`components.${name}: "theirs" (their element's selector)`);
+    const parts = {};
+    /**
+     * A part, and its own parts (a price filter's slider and inputs: "parts" inside a part), flattened as
+     * `<part>.<sub-part>`, each one's selectors inside its parent's on its side (docs/PARITY.md, "Parts of
+     * parts"): a sub-control theirs has and ours lacks is a missing element, CRITICAL.
+     */
+    const addPart = (pn, ps, parent) => {
+      const spec = isObj(ps) && ('theirs' in ps || 'ours' in ps || 'selector' in ps || 'parts' in ps || 'interact' in ps) ? ps : { selector: ps };
+      const name = parent ? `${parent.name}.${pn}` : pn;
+      const own = {
+        theirs: spec.selector ?? spec.theirs ?? null,
+        ours: spec.ours !== undefined ? spec.ours : (spec.selector ?? null),
+      };
+      // A range filter's (a part whose parts are a slider and its inputs): ours is Luma's range group (template-search-range-default.ts).
+      if (own.ours == null && spec.selector == null && isObj(spec.parts) && Object.keys(spec.parts).some((k) => k in RANGE_PARTS)) own.ours = RANGE_GROUP;
+      // Ours when the map names none: the built-in marker (engine.mjs). A sub-part's, inside its parent's.
+      const within = (side, sel) => {
+        const up = side === 'ours' ? (parent.ours ?? partMarker(parent.leaf)) : parent.theirs;
+        const s = sel ?? (side === 'ours' ? partMarker(RANGE_PARTS[pn] ?? pn) : null);
+        if (s == null) return null;
+        if (typeof up !== 'string') return side === 'theirs' && up == null ? null : s;
+        return `${up} ${s}`;
+      };
+      parts[name] = {
+        theirs: parent ? within('theirs', typeof own.theirs === 'string' ? own.theirs : null) : own.theirs,
+        ours: parent ? within('ours', typeof own.ours === 'string' ? own.ours : null) : own.ours,
+        text: spec.text === undefined ? undefined : spec.text,
+        ignore: Array.isArray(spec.ignore) ? spec.ignore : [],
+        role: null,
+        parent: parent?.name ?? null,
+      };
+      // Its role follows from its marker.
+      parts[name].role = partRoleOf(pn, { role: spec.role, ours: (parent ? null : parts[name].ours) ?? partMarker(pn) });
+      if (parent && parts[name].theirs == null) errors.push(`components.${cn}.parts.${name}: "theirs" (their sub-control's selector, inside ${parent.name})`);
+      const ia = normalizeInteract(spec.interact, `components.${cn}.parts.${name}.interact`);
+      errors.push(...ia.errors);
+      for (const x of ia.list) map.interactions.push({ id: `${cn}.${name}`, component: cn, part: name, ...x });
+      if (spec.parts != null && !isObj(spec.parts)) errors.push(`components.${cn}.parts.${name}.parts: { "<sub-part>": "<selector>" }`);
+      for (const [sn, ss] of Object.entries(isObj(spec.parts) ? spec.parts : {})) addPart(sn, ss, { name, leaf: pn, theirs: parts[name].theirs, ours: parent ? parts[name].ours : own.ours });
+    };
+    const cn = name;
+    for (const [pn, ps] of Object.entries(isObj(c.parts) ? c.parts : {})) addPart(pn, ps, null);
+    {
+      const ia = normalizeInteract(c.interact, `components.${name}.interact`);
+      errors.push(...ia.errors);
+      for (const x of ia.list) map.interactions.push({ id: name, component: name, part: 'root', ...x });
+    }
+    const each = c.each === true ? {} : isObj(c.each) ? c.each : null;
+    map.components[name] = {
+      role: roleOf(name, c),
+      pages,
+      theirs: c.theirs ?? c.root ?? null,
+      ours: c.ours ?? null,
+      parts,
+      each: each ? { key: typeof each.key === 'string' ? { attr: each.key } : isObj(each.key) ? each.key : null, sample: Number(each.sample ?? DEFAULTS.sample), max: Number(each.max ?? 60) } : null,
+      grid: isObj(c.grid) ? { item: c.grid.item } : null,
+      text: c.text === undefined ? (c.each ? 'exact' : 'shape') : c.text,
+      ignore: Array.isArray(c.ignore) ? c.ignore : [],
+      mask: Array.isArray(c.mask) ? c.mask : [],
+      states: Array.isArray(c.states) ? c.states.filter((s) => s === 'hover') : [],
+    };
+    if (c.text != null && c.text !== false && c.text !== 'exact' && c.text !== 'shape') errors.push(`components.${name}.text: "exact", "shape" or false`);
+    if (c.grid && !isObj(c.grid)) errors.push(`components.${name}.grid: { "item": "<selector>" }`);
+    if (c.role != null && (typeof c.role !== 'string' || !(ROLES.has(kebab(c.role)) || PARTS.includes(kebab(c.role))))) errors.push(`components.${name}.role: a mandatory component (${MANDATORY.filter((m) => !m.includes('.')).join(', ')}) or a part marker (${PARTS.join(', ')})`);
+  }
+  for (const [pn, pg] of Object.entries(map.pages))
+    for (const st of pg.states) for (const c of st.components ?? []) if (!map.components[c]?.pages.includes(pn)) errors.push(`pages.${pn}.states "${st.name}".components: "${c}" is no component of the page`);
+  // { "<name>": "<reason>" } (or [{ "name": …, "reason": … }]): every entry with its reason; "excluded"
+  // also takes a recorded product decision: { "reason": "<why>", "decision": "<who decided what>", "by", "date" }.
+  const decisions = /** @type {Record<string, { decision: string, by?: string, date?: string }>} */ ({});
+  const reasons = (key, v, idOf, what) => {
+    const out = /** @type {Record<string, string>} */ ({});
+    if (v == null) return out;
+    if (!isObj(v) && !Array.isArray(v)) {
+      errors.push(`${key}: { "<name>": "<reason>" }`);
+      return out;
+    }
+    const list = isObj(v) ? Object.entries(v) : v.map((x) => (isObj(x) ? [x.name ?? x.gap ?? x.component, x] : [x, undefined]));
+    for (const [k, raw] of list) {
+      const rec = isObj(raw) ? raw : null;
+      const r = rec ? (typeof rec.reason === 'string' && rec.reason.trim() ? rec.reason : rec.decision) : raw;
+      const decision = rec && typeof rec.decision === 'string' && rec.decision.trim() ? { decision: rec.decision.trim(), ...(typeof rec.by === 'string' ? { by: rec.by } : {}), ...(rec.date != null ? { date: String(rec.date) } : {}) } : null;
+      const id = typeof k === 'string' ? idOf(k, decision) : null;
+      if (!id) errors.push(`${key}: "${k}" is not ${what}`);
+      else if (typeof r !== 'string' || !r.trim()) errors.push(`${key}: "${k}" needs a reason ({ "${k}": "<why>" }${key === 'excluded' ? ', or { "reason": "<why>", "decision": "<the product decision>" }' : ''})`);
+      else {
+        out[id] = r.trim();
+        if (decision) decisions[id] = decision;
+      }
+    }
+    return out;
+  };
+  /** What a product decision can be on: "tile", "tile.title", either with a property ("tile.title color"), "collateral[.<block>]", "alignment[.<a>~<b>]", "behaviour[.<component>.<part>]", "hold". */
+  const decidable = (k) => {
+    const [where, prop, ...more] = k.trim().split(/\s+/);
+    if (more.length || (prop != null && !/^[a-z-]+$/i.test(prop))) return false;
+    // The page-level checks: the collateral check, the alignment, the behaviour, the hold ("alignment.sort~grid align-right", "behaviour.tile.compare effect").
+    if (/^(collateral|alignment|behaviour|hold)(\.|$)/.test(where)) return true;
+    const [cn, ...rest] = where.split('.');
+    const pn = rest.length ? rest.join('.') : null;
+    const c = map.components[cn];
+    return !!c && (pn == null || pn === 'root' || pn === 'grid' || !!c.parts[pn]);
+  };
+  const excluded = reasons(
+    'excluded',
+    raw.excluded,
+    (k, decision) => {
+      const [head, ...rest] = k.split('.');
+      const id = rest.length ? `${head}.${kebab(rest.join('.'))}` : kebab(head);
+      if (MANDATORY.includes(id)) return id;
+      if (MANDATORY.includes(`tile.${id}`)) return `tile.${id}`;
+      return decision && decidable(k) ? `decided:${k.trim()}` : null;
+    },
+    `a mandatory component (${MANDATORY.join(', ')}), or, with a "decision", a mapped component, "component.part" (either with a property: "tile.title color") or "collateral"`,
+  );
+  for (const [id, reason] of Object.entries(excluded)) {
+    if (id.startsWith('decided:')) map.decided[id.slice(8)] = { reason, ...decisions[id] };
+    else {
+      map.excluded[id] = reason;
+      if (decisions[id]) map.decisions[id] = decisions[id];
+    }
+  }
+  map.dataGaps = reasons(
+    'dataGaps',
+    raw.dataGaps,
+    (k) => {
+      if (k in GAPS) return k;
+      const [cn, pn] = k.split('.');
+      const c = map.components[cn];
+      return c && (pn == null || pn === 'root' || c.parts[pn]) ? k : null;
+    },
+    `a known gap (${Object.keys(GAPS).join(', ')}), a component or "component.part"`,
+  );
+  return { map, errors };
+};
+
+/**
+ * Which mandatory components (MANDATORY) the map covers: per one, "mapped"
+ * (by which component or part), "excluded" (and why) or "missing"; `ok`
+ * when none is missing. A component covers its role; a part covers its role
+ * too (a facets component's facetGroup part), and a tile's parts its parts.
+ * @param {any} map a normalized map
+ * @returns {{ ok: boolean, items: { id: string, status: 'mapped' | 'excluded' | 'missing', by?: string, reason?: string, decision?: { decision: string, by?: string, date?: string } }[], missing: string[] }}
+ */
+export const coverage = (map) => {
+  const as = (role) => (role == null ? null : (ALIAS[role] ?? role));
+  const found = new Map();
+  const note = (id, by) => {
+    if (id && MANDATORY.includes(id) && !found.has(id)) found.set(id, by);
+  };
+  for (const [cn, c] of Object.entries(map.components ?? {})) {
+    const r = as(c.role);
+    note(r, `components.${cn}`);
+    for (const [pn, p] of Object.entries(c.parts ?? {})) {
+      const pr = as(p.role);
+      if (r === 'tile' && TILE_PARTS.includes(pr)) note(`tile.${pr}`, `components.${cn}.parts.${pn}`);
+      else if (!TILE_PARTS.includes(pr)) note(pr, `components.${cn}.parts.${pn}`);
+    }
+  }
+  const items = MANDATORY.map((id) =>
+    found.has(id)
+      ? { id, status: /** @type {const} */ ('mapped'), by: found.get(id) }
+      : map.excluded?.[id]
+        ? { id, status: /** @type {const} */ ('excluded'), reason: map.excluded[id], ...(map.decisions?.[id] ? { decision: map.decisions[id] } : {}) }
+        : { id, status: /** @type {const} */ ('missing') },
+  );
+  const missing = items.filter((i) => i.status === 'missing').map((i) => i.id);
+  return { ok: !missing.length, items, missing };
+};
+
+/**
+ * Every page's two paths (`--record` keeps them in the recording's index):
+ * ours, and the page of theirs it is compared against, its design source.
+ * @param {any} map a normalized map
+ * @returns {Record<string, { theirs: string, ours: string }>}
+ */
+export const recordedPages = (map) => Object.fromEntries(Object.entries(map.pages ?? {}).map(([k, v]) => [k, { theirs: v.paths?.theirs ?? v.path, ours: v.paths?.ours ?? v.path }]));
+
+/**
+ * Per page: ours, the page of theirs it is compared against (the design
+ * source), whether that is another page (`cross`) and whether their products
+ * are paired with ours (`paired`). The report states it for every page.
+ * @param {any} map a normalized map
+ */
+export const designSources = (map) =>
+  Object.entries(map.pages ?? {}).map(([page, v]) => ({ page, theirs: v.paths?.theirs ?? v.path, ours: v.paths?.ours ?? v.path, cross: !!v.cross, paired: !!v.ids }));
+
+/** The pages each component is measured on, as [page, component] pairs, in the map's order. @param {any} map */
+export const plan = (map) => Object.keys(map.pages).map((page) => ({ page, components: Object.entries(map.components).filter(([, c]) => c.pages.includes(page)).map(([n]) => n) }));