@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/init.mjs

@@ -0,0 +1,703 @@
+// `yarn luma parity --init`: a draft map from the site's own pages, for an agent
+// or a person to confirm.
+//
+// Their side, by structure (not by class names alone): the product tile is
+// the element repeated as siblings with an image, a link and a price; its
+// parts by role (the largest image, the price-like text, the crossed one as
+// the old price, the heading or the longest link text as the title, a short
+// label as the badge); the facet container is the element whose children are
+// groups of options (checkboxes, role=checkbox, links with counts); the sort
+// control a select (or a menu) of sort orders; the count the shortest text
+// with a number of products. Our side: Luma's `data-lbx-part` markers (the
+// built-in templates carry them, and so should an integration's own
+// templates, docs/PARITY.md), else their selector when a 1:1 port has it.
+// The product pairing comes from evidence: their ids (or links) matched
+// against the catalog records our page received.
+//
+// Every pick the heuristics were not sure of is listed in "confirm"; the
+// mandatory components (map.mjs MANDATORY) not found on their pages too.
+//
+// What is not theirs is never drafted as theirs: every Luigi's Box script
+// (*.luigisbox.{tech,com,ai}: a previous generation's dropdown, the
+// platform's loader) and the vendor scripts `--block` names are blocked on
+// both sides, and previous-generation or vendor markup (map.mjs LEGACY_MARKUP:
+// `#lbx-ac-element`, `.luigi-ac`, a server-rendered remnant) is never picked.
+// The pairing found is checked as a run makes it (their products by id with
+// the queries of parity/pairing.mjs): a pairing that finds none of them is
+// listed to confirm, and a query a run needs is drafted as the page's.
+import { BLOCK_LUIGIS, LEGACY_MARKUP, MANDATORY, PARTS, RANGE_GROUP, RANGE_PARTS, kebab, partMarker } from './map.mjs';
+import { formatQueries, pairingFailure, queryCandidates, queryOfPath } from './pairing.mjs';
+import { alignInit, deepInit, stabilize, theirHints } from './probe.mjs';
+
+/**
+ * In the page: their components, as selectors (page-level roots,
+ * root-relative parts), with the picks of low confidence (`low`).
+ * @param {{ empty: boolean, legacy?: string[] }} arg `legacy`: markup never theirs (map.mjs LEGACY_MARKUP)
+ */
+export function proposeTheirs(arg) {
+  // A previous Luigi's Box generation's widgets and vendors' are not their design: never picked.
+  const legacy = (el) =>
+    (arg.legacy ?? []).some((s) => {
+      try {
+        return !!el.closest(s);
+      } catch {
+        return false;
+      }
+    });
+  const PRICE = /(\d[\d\s.,]*\s?(€|\$|£|kč|zł|kr\b|ft\b|lei\b|chf\b|eur\b|usd\b|,-))|((€|\$|£)\s?\d)/i;
+  const UTIL = /\d|^([a-z]+-)?(d|m[trblxyse]?|p[trblxyse]?|w|h|col|row|g|gap|flex|align|justify|order|text|font|fw|fs|bg|border|rounded|shadow|position|top|bottom|start|end|float|overflow|visible|invisible|hidden|show|is|has|js)(-|$)/;
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== 'hidden';
+  };
+  const area = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width * r.height;
+  };
+  const classes = (el) => [...el.classList].filter((c) => !UTIL.test(c) && /^[a-z_-][\w-]*$/i.test(c));
+  const cssEsc = (s) => CSS.escape(s);
+  const text = (el) => (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+  /** A document-level selector: an id, a unique class, or the parent's selector and a child step. */
+  const docSel = (el, depth = 0) => {
+    if (el.id && /^[a-z][\w-]*$/i.test(el.id) && !/\d{3,}/.test(el.id)) return `#${cssEsc(el.id)}`;
+    for (const c of classes(el)) if (document.querySelectorAll(`.${cssEsc(c)}`).length === 1) return `.${cssEsc(c)}`;
+    const cs = classes(el);
+    const self = `${el.tagName.toLowerCase()}${cs.slice(0, 2).map((c) => `.${cssEsc(c)}`).join('')}`;
+    if (!el.parentElement || el.parentElement === document.body || depth > 4) return self;
+    if (cs.length && document.querySelectorAll(self).length === 1) return self;
+    return `${docSel(el.parentElement, depth + 1)} > ${self}`;
+  };
+  /** A selector of `el` inside `root` that finds it first. */
+  const relSel = (el, root) => {
+    for (const c of classes(el)) if (root.querySelector(`.${cssEsc(c)}`) === el) return `.${cssEsc(c)}`;
+    const t = el.tagName.toLowerCase();
+    for (const c of classes(el)) if (root.querySelector(`${t}.${cssEsc(c)}`) === el) return `${t}.${cssEsc(c)}`;
+    if (root.querySelector(t) === el) return t;
+    for (const a of ['itemprop', 'data-testid', 'role']) {
+      const v = el.getAttribute(a);
+      if (v && root.querySelector(`${t}[${a}="${cssEsc(v)}"]`) === el) return `${t}[${a}="${v}"]`;
+    }
+    const path = [];
+    for (let e = el; e && e !== root; e = e.parentElement) {
+      const sibs = e.parentElement ? [...e.parentElement.children].filter((x) => x.tagName === e.tagName) : [e];
+      path.unshift(`${e.tagName.toLowerCase()}${sibs.length > 1 ? `:nth-of-type(${sibs.indexOf(e) + 1})` : ''}`);
+    }
+    return `:scope > ${path.join(' > ')}`;
+  };
+  const sig = (el) => `${el.tagName}.${classes(el).sort().join('.')}`;
+  /** The innermost elements whose text is a price (no child holds the whole price). */
+  const prices = (scope) =>
+    [...scope.querySelectorAll('*')].filter((e) => vis(e) && text(e).length < 40 && PRICE.test(text(e)) && ![...e.children].some((c) => PRICE.test(text(c))));
+  const crossed = (e, stop) => {
+    for (let x = e; x && x !== stop; x = x.parentElement) {
+      if (getComputedStyle(x).textDecorationLine.includes('line-through') || /^(DEL|S|STRIKE)$/.test(x.tagName) || /old|crossed|strike|was|before|original|regular/i.test(String(x.className))) return true;
+    }
+    return false;
+  };
+  const out = { components: {}, ids: null, links: null, notes: [] };
+  const low = (comp, part, why) => {
+    const c = out.components[comp];
+    if (!c) return;
+    c.low = c.low ?? {};
+    c.low[part ?? '.'] = why;
+  };
+
+  // ---- the product tile: siblings alike, each with an image and a link, most with a price.
+  let best = null;
+  for (const parent of document.querySelectorAll('body *')) {
+    if (parent.children.length < 3 || parent.closest('header, nav, footer') || legacy(parent)) continue;
+    const by = new Map();
+    for (const ch of parent.children) {
+      if (!vis(ch)) continue;
+      const k = sig(ch);
+      if (!by.has(k)) by.set(k, []);
+      by.get(k).push(ch);
+    }
+    for (const members of by.values()) {
+      const ok = members.filter((m) => m.querySelector('img') && (m.matches('a[href]') || m.querySelector('a[href]')));
+      const priced = ok.filter((m) => PRICE.test(text(m)));
+      if (ok.length >= 3 && priced.length >= ok.length * 0.6 && (!best || ok.length > best.members.length)) best = { parent, members: ok };
+    }
+  }
+  if (best) {
+    let tiles = best.members;
+    // Wrappers (grid columns) around the tile: down to the element that is the tile.
+    while (tiles.every((t) => t.children.length === 1 && sig(t.children[0]) === sig(tiles[0].children[0]))) tiles = tiles.map((t) => t.children[0]);
+    const t0 = tiles[0];
+    const common = classes(t0).filter((c) => tiles.every((t) => t.classList.contains(c)));
+    const tileStep = common.length ? `.${cssEsc(common[0])}` : t0.tagName.toLowerCase();
+    const list = docSel(best.parent);
+    const tileSel = `${list} ${tileStep}`;
+    // Their product ids: attributes whose value differs on every tile (the init matches them against the catalog).
+    const attrs = [...t0.attributes].map((a) => a.name).filter((n) => !/^(class|style|href|src|title|alt|role|tabindex|aria-.*)$/.test(n));
+    const distinct = attrs.filter((n) => {
+      const vs = tiles.map((t) => t.getAttribute(n));
+      return vs.every((v) => v && /^[\w:./-]{1,128}$/.test(v)) && new Set(vs).size === vs.length;
+    });
+    distinct.sort((a, b) => (/product|sku|code|item|id/.test(b) ? 1 : 0) - (/product|sku|code|item|id/.test(a) ? 1 : 0));
+    out.ids = { selector: tileSel, candidates: distinct.map((n) => ({ attr: n, values: tiles.slice(0, 60).map((t) => t.getAttribute(n)) })) };
+    out.links = tiles.slice(0, 60).map((t) => (t.matches('a[href]') ? t : t.querySelector('a[href]'))?.href ?? null);
+    // The parts, by role, over the first tiles: a part one tile lacks (an old price, a badge) another has.
+    const parts = {};
+    const lowParts = {};
+    // The tile's controls with an interaction (docs/PARITY.md, "Behaviour"), by what they are named or link to.
+    const interact = {};
+    const CONTROL_ROLES = [
+      ['compare', /compar|vergelijk|vergleich|porovn|porówn|confront/i],
+      ['wishlist', /wish|favou?rit|heart|merkzettel|merkliste|verlanglijst|oblíben|oblúben|ulubion/i],
+      ['addToCart', /cart|basket|\bbuy\b|winkelwagen|warenkorb|ko[sš][ií]k|koszyk|panier|carrello/i],
+    ];
+    /** The counter an action of that role changes, outside the listing (a header's compare count): the interaction's watch. */
+    const counterOf = (role) => {
+      const re = CONTROL_ROLES.find(([r]) => r === role)[1];
+      const el = [...document.querySelectorAll('body *')].find((e) => vis(e) && !best.parent.contains(e) && re.test(`${e.className} ${e.id}`) && /^\(?\d{1,4}\)?$/.test(text(e)));
+      return el ? docSel(el) : null;
+    };
+    for (const tl of tiles.slice(0, 12)) {
+      const pick = (name, el, why) => {
+        if (!el || el === tl || !tl.contains(el) || parts[name]) return;
+        parts[name] = relSel(el, tl);
+        if (why) lowParts[name] = why;
+      };
+      const within = [...tl.querySelectorAll('*')].filter(vis);
+      // The image: the largest, with its frame when the frame is only the image.
+      const img = [...tl.querySelectorAll('img')].filter(vis).sort((a, b) => area(b) - area(a))[0];
+      if (img) {
+        let frame = img;
+        for (let e = img.parentElement; e && e !== tl && area(e) <= area(img) * 1.15 && !text(e); e = e.parentElement) frame = e;
+        pick('image', frame);
+      }
+      // The price: the largest uncrossed price-like text; the old price: a crossed one.
+      const ps = prices(tl);
+      const fs = (e) => parseFloat(getComputedStyle(e).fontSize);
+      const now = ps.filter((e) => !crossed(e, tl)).sort((a, b) => fs(b) - fs(a));
+      pick('price', now[0], now.length > 1 && fs(now[0]) === fs(now[1]) ? 'two prices of one size: the first taken as the price' : null);
+      const was = ps.find((e) => crossed(e, tl));
+      if (was) pick('oldPrice', was);
+      else if (now.length > 1 && now[1] !== now[0]) pick('oldPrice', now[1], 'a second, smaller price taken as the old price (not crossed out)');
+      // The title: a heading, else an element named title/name, else the longest link text.
+      const titled = within.filter((e) => text(e).length >= 3 && text(e).length < 200 && !PRICE.test(text(e)) && !e.querySelector('img'));
+      const heading = titled.filter((e) => /^H[1-6]$/.test(e.tagName))[0];
+      const named = titled.filter((e) => /title|name|heading/i.test(String(e.className)) || e.getAttribute('itemprop') === 'name').sort((a, b) => text(b).length - text(a).length)[0];
+      const linked = titled.filter((e) => e.closest('a[href]') && ![...e.children].some((c) => text(c) === text(e))).sort((a, b) => text(b).length - text(a).length)[0];
+      if (heading) pick('title', heading);
+      else if (named) pick('title', named);
+      else if (linked) pick('title', linked, 'the longest link text (no heading, no element named title)');
+      const title = heading ?? named ?? linked ?? null;
+      const discount = within.find((e) => /^-\s?\d+\s?%$/.test(text(e)) && e.children.length <= 1);
+      if (discount) pick('discount', discount);
+      // The badge: a short label, by its name, else one laid over the image.
+      const short = within.filter((e) => text(e).length >= 1 && text(e).length <= 24 && !PRICE.test(text(e)) && !e.querySelector('img') && e !== discount && (!title || (!title.contains(e) && !e.contains(title))) && ![...e.children].some((c) => text(c) === text(e)));
+      const byName = short.find((e) => /badge|label|flag|ribbon|sticker|tag|promo/i.test(String(e.className)));
+      const over = img ? short.find((e) => {
+        const r = e.getBoundingClientRect();
+        const i = img.getBoundingClientRect();
+        return getComputedStyle(e).position === 'absolute' && r.left < i.right && r.right > i.left && r.top < i.bottom && r.bottom > i.top;
+      }) : null;
+      if (byName) pick('badge', byName);
+      else if (over) pick('badge', over, 'a short label laid over the image');
+      const rating = within.find((e) => /rating|stars|rated|review/i.test(String(e.className)) || /out of 5|stars/i.test(e.getAttribute('aria-label') ?? ''));
+      if (rating) pick('rating', rating);
+      const stock = within.find((e) => /stock|avail|delivery/i.test(String(e.className)) && text(e));
+      if (stock) pick('availability', stock, 'by its class');
+      const cart = within.find((e) => (e.tagName === 'BUTTON' || e.tagName === 'A') && /cart|basket|buy/i.test(`${e.className} ${e.getAttribute('aria-label') ?? ''} ${e.title}`));
+      if (cart) pick('addToCart', cart);
+      // Its other controls (a compare link, a wishlist heart, add to cart): parts with an interaction, each to confirm.
+      const main = (title ?? img)?.closest('a[href]') ?? null;
+      for (const c of within.filter((e) => e.matches('a[href], button, input[type=checkbox], [role=button], [role=checkbox]') && e !== main && !e.contains(img ?? null) && !(title && e.contains(title)))) {
+        const what = `${c.className} ${c.id} ${c.getAttribute('aria-label') ?? ''} ${c.getAttribute('title') ?? ''} ${c.getAttribute('href') ?? ''} ${text(c)}`;
+        const role = CONTROL_ROLES.find(([, re]) => re.test(what))?.[0];
+        if (!role || interact[role]) continue;
+        pick(role, c);
+        interact[role] = { action: c.matches('input[type=checkbox], [role=checkbox]') ? 'check' : 'click', ...(counterOf(role) ? { watch: counterOf(role) } : {}) };
+      }
+    }
+    out.components.tile = { theirs: tileSel, parts, keyCandidates: distinct, ...(Object.keys(interact).length ? { interact } : {}) };
+    if (Object.keys(lowParts).length) out.components.tile.low = Object.fromEntries(Object.entries(lowParts));
+    out.components.grid = { theirs: list, item: tileStep };
+  } else out.notes.push('tile: no repeated element with an image, a link and a price on this page');
+
+  // ---- facets: a container whose children are groups of options.
+  const tileRoot = best?.parent ?? null;
+  const hostOf = (o) => (o.tagName === 'INPUT' ? (o.closest('label') ?? (o.id ? document.querySelector(`label[for="${cssEsc(o.id)}"]`) : null) ?? o) : o);
+  const options = [
+    ...document.querySelectorAll('input[type=checkbox], input[type=radio], [role=checkbox], [role=menuitemcheckbox]'),
+    ...[...document.querySelectorAll('a[href], button, li')].filter((e) => /\(\s*\d[\d\s.,]*\)\s*$/.test(text(e)) && text(e).length < 80),
+  ]
+    .map(hostOf)
+    .filter((e, i, all) => e && all.indexOf(e) === i && vis(e) && !(tileRoot && tileRoot.contains(e)) && !e.closest('header, footer, [role=dialog]') && !legacy(e));
+  let container = null;
+  for (const o of options) {
+    for (let c = o.parentElement; c && c !== document.body; c = c.parentElement) {
+      const groups = [...c.children].filter((g) => vis(g) && options.filter((x) => g.contains(x)).length >= 2);
+      if (groups.length >= 2) {
+        if (!container || container.contains(c)) container = c;
+        break;
+      }
+    }
+    if (container) break;
+  }
+  if (container) {
+    const groups = [...container.children].filter((g) => vis(g) && options.filter((x) => g.contains(x)).length >= 2);
+    const g = groups[0];
+    const value = options.find((x) => g.contains(x));
+    const title = [...g.querySelectorAll('*')].find((e) => vis(e) && text(e) && text(e).length < 60 && !options.some((x) => e.contains(x) || x.contains(e)));
+    const parts = { facetGroup: relSel(g, container), facetValue: relSel(value, container) };
+    if (title) parts.facetTitle = relSel(title, container);
+    out.components.facets = { theirs: docSel(container), parts, interact: { facetValue: { action: value.matches('input[type=checkbox], [role=checkbox]') || value.querySelector('input[type=checkbox], [role=checkbox]') ? 'check' : 'click' } } };
+    if (!title) low('facets', null, 'no title found in the first group (parts.facetTitle)');
+    else if (!/^(H[1-6]|LEGEND|SUMMARY|DT|BUTTON|STRONG)$/.test(title.tagName)) out.components.facets.low = { facetTitle: `the first text of the group (a ${title.tagName.toLowerCase()}, not a heading)` };
+  } else out.notes.push('facets: no container of option groups (checkboxes, role=checkbox, links with counts)');
+
+  // ---- a range filter: a slider (input[type=range], role=slider, jQuery UI's, noUiSlider's) and its inputs, as parts of a part.
+  const SLIDER = '[data-lbx-part~="range-slider"], input[type=range], [role=slider], .ui-slider, .noUi-target, .irs, .rc-slider';
+  const slider = [...document.querySelectorAll(SLIDER)].find((e) => vis(e) && !legacy(e) && !(tileRoot && tileRoot.contains(e)) && !e.parentElement?.closest(SLIDER));
+  if (slider) {
+    const host = container && container.contains(slider) ? container : null;
+    // Its group: the container's child that holds it, else the nearest ancestor with inputs or a title beside it.
+    let g = host ? [...host.children].find((c) => c.contains(slider)) : null;
+    if (!g) for (let e = slider.parentElement; e && e !== document.body; e = e.parentElement) if (e.querySelector('input:not([type=range]):not([type=hidden]), h2, h3, h4, h5, legend, summary') && (g = e)) break;
+    if (g) {
+      const scope = host ?? null;
+      const sub = { slider: relSel(slider, g) };
+      const inputs = [...g.querySelectorAll('input:not([type=range]):not([type=hidden]):not([type=checkbox]):not([type=radio])')].filter((e) => vis(e) && !slider.contains(e));
+      if (inputs[0]) sub.min = relSel(inputs[0], g);
+      if (inputs[1]) sub.max = relSel(inputs[1], g);
+      const range = { theirs: scope ? relSel(g, scope) : docSel(g), parts: sub };
+      if (scope && out.components.facets) out.components.facets.parts.rangeFilter = range;
+      else out.components.rangeFilter = { theirs: range.theirs, parts: sub, role: 'facet-group' };
+    }
+  }
+
+  // ---- sort: a select of sort orders, else a menu named sort.
+  const SORT = /price|name|new|popular|relevan|rating|cheap|expens|best|sort|order|cen|preis|prix/i;
+  const select = [...document.querySelectorAll('select')].find((s) => vis(s) && !legacy(s) && [...s.options].filter((o) => SORT.test(o.text)).length >= 2);
+  const menu = [...document.querySelectorAll('[class*=sort i], [id*=sort i], [class*=order i]')].find((e) => vis(e) && !legacy(e) && e.querySelectorAll('a, button, li, option').length >= 2 && !(tileRoot && tileRoot.contains(e)));
+  const labelled = [...document.querySelectorAll('label, button, span, div')].find((e) => vis(e) && !legacy(e) && text(e).length < 40 && /^(sort|order by|sort by|řadit|zoradiť|sortieren|trier)/i.test(text(e)));
+  const sortEl = select ?? menu ?? labelled ?? null;
+  if (sortEl) {
+    out.components.sort = { theirs: docSel(sortEl), interact: { root: { action: select && sortEl === select ? 'select' : 'click' } } };
+    if (!select && !menu) low('sort', null, 'a control labelled "sort" (no select of sort orders, no element named sort)');
+  }
+  // ---- the count: the shortest text with a number of products.
+  const COUNT = /\d[\d\s.,]*\s+(products?|results?|items?|articles?|pieces?|produkt|výsled|položi|artikel|ergebnis)/i;
+  const count = [...document.querySelectorAll('body *')].filter((e) => vis(e) && !legacy(e) && text(e).length < 80 && (COUNT.test(text(e)) || /\d+\s*(of|from|z|von|de)\s*\d+/i.test(text(e))) && !(tileRoot && tileRoot.contains(e))).sort((a, b) => text(a).length - text(b).length)[0];
+  if (count) {
+    out.components.count = { theirs: docSel(count) };
+    if (!COUNT.test(text(count))) low('count', null, `"${text(count)}" has no word for products or results`);
+  }
+  // ---- pagination: a pager (page links) or a "show more".
+  const pager = [...document.querySelectorAll('nav, ul, ol, div')].find((e) => vis(e) && !legacy(e) && (/pagina|pager|pages/i.test(String(e.className)) || /pag/i.test(e.getAttribute('aria-label') ?? '')) && !(tileRoot && tileRoot.contains(e)));
+  const numbered = pager ? null : [...document.querySelectorAll('nav, ul, ol, div')].find((e) => vis(e) && [...e.querySelectorAll(':scope > a, :scope > li > a')].filter((a) => /^\d+$/.test(text(a))).length >= 2);
+  const more = [...document.querySelectorAll('a, button')].find((e) => vis(e) && !legacy(e) && /show more|load more|more products|next page|další|viac|mehr|weitere/i.test(text(e)));
+  const pg = pager ?? numbered ?? more ?? null;
+  if (pg) {
+    out.components.pagination = { theirs: docSel(pg) };
+    if (!pager) low('pagination', null, numbered ? 'a group of numbered links' : 'a "show more" button');
+  }
+  if (arg.empty) {
+    const e = [...document.querySelectorAll('h1, h2, h3, h4, h5, p, div')].filter((x) => vis(x) && !legacy(x) && /no results|couldn.t find|nothing found|sorry|no products|0 results|nenašl|nichts gefunden|aucun/i.test(text(x)) && text(x).length < 400).sort((a, b) => text(a).length - text(b).length)[0];
+    if (e) out.components.empty = { theirs: docSel(e) };
+  }
+  return out;
+}
+
+/** In the page, before typing: what is visible now (the autocomplete is what appears after). */
+export function markVisible() {
+  const s = (window.__parityBefore = new WeakSet());
+  for (const el of document.querySelectorAll('body *')) {
+    const r = el.getBoundingClientRect();
+    if (r.width > 0 && r.height > 0) s.add(el);
+  }
+}
+
+/**
+ * In the page, after typing: the panel that appeared, its rows (repeated children with a link), a section and its title.
+ * Never a previous-generation Luigi's Box dropdown or a vendor's, nor what holds one (`legacy`: map.mjs LEGACY_MARKUP).
+ * @param {{ legacy?: string[] }} [arg]
+ */
+export function proposeAutocomplete(arg = {}) {
+  const before = window.__parityBefore ?? new WeakSet();
+  const legacy = (el) =>
+    (arg.legacy ?? []).some((s) => {
+      try {
+        return !!el.closest(s) || !!el.querySelector(s);
+      } catch {
+        return false;
+      }
+    });
+  const UTIL = /\d|^([a-z]+-)?(d|m[trblxy]?|p[trblxy]?|w|h|col|row|flex|align|justify|text|is|has|js)(-|$)/;
+  const classes = (el) => [...el.classList].filter((c) => !UTIL.test(c));
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  const fresh = [...document.querySelectorAll('body *')].filter((e) => vis(e) && !before.has(e) && !legacy(e) && e.querySelectorAll('a[href], [role=option]').length >= 2);
+  const area = (e) => e.getBoundingClientRect().width * e.getBoundingClientRect().height;
+  const panel = fresh.filter((e) => !fresh.some((o) => o !== e && o.contains(e) && area(o) <= area(e) * 1.05)).sort((a, b) => area(b) - area(a))[0];
+  if (!panel) return null;
+  const sel = (el) => (el.id && !/\d{3,}/.test(el.id) ? `#${CSS.escape(el.id)}` : `${el.tagName.toLowerCase()}${classes(el).slice(0, 2).map((c) => `.${CSS.escape(c)}`).join('')}`);
+  const rows = [...panel.querySelectorAll('a[href], [role=option]')].filter(vis);
+  const rowSig = new Map();
+  for (const r of rows) {
+    const k = sel(r);
+    rowSig.set(k, (rowSig.get(k) ?? 0) + 1);
+  }
+  const row = [...rowSig.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  const head = [...panel.querySelectorAll('h1, h2, h3, h4, h5, h6, [class*=title], [class*=head]')].find((e) => vis(e) && e.textContent.trim() && !e.closest('a'));
+  // A section: the title's nearest ancestor that holds rows too.
+  let section = null;
+  for (let e = head?.parentElement; e && e !== panel; e = e.parentElement) if (e.querySelector('a[href], [role=option]')) { section = e; break; }
+  return { panel: sel(panel), row, title: head ? sel(head) : null, section: section ? sel(section) : null };
+}
+
+/** In the page (ours): the first of the candidate selectors that finds a visible element (inside `within` when given), open shadow roots seen into. */
+export function firstMatch(arg) {
+  const D = window.__parityDeep;
+  const qa = (scope, sel) => {
+    if (D) return D.all(scope, sel);
+    try {
+      return [...scope.querySelectorAll(sel)];
+    } catch {
+      return [];
+    }
+  };
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  for (const c of arg.candidates) {
+    const scope = arg.within ? qa(document, arg.within).find(vis) : document;
+    if (!scope) return null;
+    if (qa(scope, c).find(vis)) return c;
+  }
+  return null;
+}
+
+/** In the page (ours): whether the first visible element of `sel` has attribute `attr`. */
+export function hasAttr(arg) {
+  const D = window.__parityDeep;
+  const el = (D ? D.all(document, arg.sel) : [...document.querySelectorAll(arg.sel)]).find((e) => e.getBoundingClientRect().width > 0);
+  return !!el?.hasAttribute(arg.attr);
+}
+
+/** The last compound of a selector (`.list > .tile` -> `.tile`): where a 1:1 port has the same element under our root. */
+const lastStep = (s) => s.trim().split(/\s+(?:>\s*)?/).pop();
+const LISTING = ':is(lbx-search, lbx-plp)';
+const OVERLAY = '[data-lbx="ac-overlay"]';
+/** Our marker for a role, scoped to the listing or the autocomplete overlay. */
+const ourMarker = (role) => `${/^ac-/.test(role) ? OVERLAY : LISTING} ${partMarker(role)}`;
+
+/** Path of a URL (decoded, no trailing slash), for pairing by link. */
+const pathOf = (v) => {
+  try {
+    let p = new URL(String(v), 'https://x.invalid/').pathname;
+    try {
+      p = decodeURI(p);
+    } catch {}
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * Their product ids against the catalog records our page received: the
+ * attribute and the catalog field that hold the same values (`field`
+ * pairing), else their links against the records' URLs (`url`), else null.
+ * @param {{ candidates: { attr: string, values: string[] }[] }} ids @param {(string | null)[]} links @param {any[]} hits
+ */
+export const pairingOf = (ids, links, hits) => {
+  const first = (v) => (Array.isArray(v) ? v[0] : v);
+  let best = null;
+  for (const c of ids.candidates) {
+    const vs = new Set(c.values.map(String));
+    const fields = new Map();
+    for (const h of hits)
+      for (const [k, v] of Object.entries(h ?? {})) {
+        const x = first(v);
+        if ((typeof x === 'string' || typeof x === 'number') && vs.has(String(x))) fields.set(k, (fields.get(k) ?? 0) + 1);
+      }
+    for (const [field, n] of fields) if (!best || n > best.n || (n === best.n && field === '@id')) best = { pair: 'field', attr: c.attr, field, n };
+  }
+  if (best) return best;
+  const paths = new Set(links.filter(Boolean).map(pathOf));
+  let n = 0;
+  for (const h of hits) if (paths.has(pathOf(first(h?.url) ?? first(h?.web_url) ?? ''))) n++;
+  return n ? { pair: 'url', attr: 'href', field: 'web_url', n } : null;
+};
+
+/**
+ * The pages `--init` drafts: the given paths, else the fixtures' category page,
+ * a search, an empty search and the autocomplete. With `theirPlp` (their own
+ * search is disabled: empty, or a previous Luigi's Box generation not to
+ * copy) the search page is ours against that category listing of theirs,
+ * and their empty search is not drafted (it is no design of theirs).
+ * @param {{ paths?: string[], category?: string | null, query?: string | null, theirPlp?: string | null, ourSearch?: string | null }} o
+ * @returns {Record<string, string | { theirs: string, ours: string }>}
+ */
+export const initPages = ({ paths = [], category = null, query = null, theirPlp = null, ourSearch = null }) => {
+  const search = ourSearch ?? `/search?q=${encodeURIComponent(query ?? 'a')}`;
+  const out = paths.length
+    ? Object.fromEntries(paths.map((p, i) => [`page${i + 1}`, p]))
+    : theirPlp
+      ? { category: category ?? theirPlp, autocomplete: '/' }
+      : { category, search: query ? `/search?q=${encodeURIComponent(query)}` : null, empty: '/search?q=zzqxvwj', autocomplete: '/' };
+  if (theirPlp) out.search = { theirs: theirPlp, ours: search };
+  return Object.fromEntries(Object.entries(out).filter(([, p]) => p));
+};
+
+/**
+ * Loads their pages and ours, proposes the map. A page is a path (both
+ * sides), or `{ theirs, ours }`: ours drafted against another page of theirs
+ * (our search against their category listing, `--their-plp`).
+ * `block`: script URLs (regular expressions' sources) blocked on both sides: every Luigi's Box script by
+ * default (map.mjs BLOCK_LUIGIS), and the vendors' `--block` adds.
+ * @param {{ driver: any, host: string, pages: Record<string, string | { theirs: string, ours: string }>, query: string, input: string | null, log: (s: string) => void, block?: string[] }} o
+ */
+export const initMap = async ({ driver, host, pages, query, input, log, block = BLOCK_LUIGIS }) => {
+  const blocked = block.map((x) => new RegExp(x));
+  const draft = {
+    draft: true,
+    notes: ['A draft from `yarn luma parity --init`: confirm every pick in "confirm" on both sides (the HTML report shows the crops), then remove "draft", "confirm" and "notes". docs/PARITY.md.'],
+    confirm: /** @type {string[]} */ ([]),
+    host,
+    viewports: [390, 1024, 1440],
+    hide: [],
+    products: /** @type {any} */ ({ type: 'product' }),
+    pages: /** @type {Record<string, any>} */ ({}),
+    components: /** @type {Record<string, any>} */ ({}),
+  };
+  const confirm = (s) => {
+    if (!draft.confirm.includes(s)) draft.confirm.push(s);
+  };
+  const open = async (side, path, onHits, o = {}) => {
+    await driver.wait?.(side);
+    const page = await driver.page(side, { width: 1440, device: {} });
+    // A previous Luigi's Box generation's scripts and the vendors': their widgets are never drafted as theirs.
+    if (blocked.length) await page.route((u) => blocked.some((re) => re.test(u.href)), (r) => (r.request().resourceType() === 'script' ? r.abort('blockedbyclient') : r.fallback()));
+    await page.setViewportSize({ width: 1440, height: 900 });
+    await page.addInitScript(deepInit);
+    if (o.align) await page.addInitScript(alignInit, o.align);
+    if (onHits)
+      page.on('response', async (res) => {
+        const m = /\/discovery\/v1\/(search|collections)\?/.exec(res.url());
+        if (!m) return;
+        try {
+          const body = JSON.parse(res.request().postData() ?? '{}');
+          const j = await res.json();
+          onHits({ type: body.type ?? null, surface: new URL(res.url()).searchParams.get('surface_id'), endpoint: m[1], hits: j.hits ?? [] });
+        } catch {}
+      });
+    await page.goto(new URL(path, driver.origin).href, { waitUntil: 'load', timeout: 60000 });
+    await page.waitForTimeout(2500);
+    await page.evaluate(stabilize, { roots: [], hide: [] });
+    return page;
+  };
+  /** A component of the draft: merged into one of the same selector on another page, else its own (named after the page). */
+  const add = (cn, name, comp) => {
+    const same = draft.components[cn];
+    if (same && JSON.stringify({ ...same, pages: [] }) === JSON.stringify({ ...comp, pages: [] })) {
+      same.pages.push(name);
+      return cn;
+    }
+    const key = same ? `${cn}${name[0].toUpperCase()}${name.slice(1)}` : cn;
+    draft.components[key] = same ? { role: kebab(cn), ...comp } : comp;
+    return key;
+  };
+  let pairing = null;
+  /** Per page: their ids, links, heading and titles, our path: the pairing's check (below). */
+  const proposals = {};
+  /** Pages compared against another page of theirs whose ids no record of our page matched: paired at the end, by the pairing found. */
+  const pending = [];
+  for (const [name, at] of Object.entries(pages)) {
+    const path = typeof at === 'string' ? at : at.theirs;
+    const oursPath = typeof at === 'string' ? at : at.ours;
+    const cross = path !== oursPath;
+    log(`--init: ${name} ${cross ? `ours ${oursPath} against theirs ${path}` : path}`);
+    if (name === 'autocomplete') {
+      const t = await open('theirs', path);
+      const inSel =
+        input ??
+        (await t.evaluate(() => {
+          const i = [...document.querySelectorAll('input[type=search], input[name=q], input[name=query], input[type=text]')].find((e) => e.getBoundingClientRect().width > 0);
+          return i ? (i.id ? `input#${CSS.escape(i.id)}` : `input[name="${i.name}"]`) : null;
+        }));
+      if (!inSel) {
+        draft.notes.push('autocomplete: no search input found');
+        await t.close();
+        continue;
+      }
+      await t.evaluate(markVisible);
+      const loc = t.locator(inSel).first();
+      await loc.focus();
+      await loc.fill('');
+      await loc.pressSequentially(query, { delay: 60 });
+      await t.waitForTimeout(2500);
+      const ac = await t.evaluate(proposeAutocomplete, { legacy: [...LEGACY_MARKUP] });
+      await t.close();
+      if (!ac) {
+        draft.notes.push('autocomplete: no panel appeared after typing (their dropdown may need a click, or a longer wait)');
+        continue;
+      }
+      const o = await open('ours', path);
+      const oi = o.locator(inSel).first();
+      await oi.focus();
+      await oi.fill('');
+      await oi.pressSequentially(query, { delay: 60 });
+      await o.waitForTimeout(2500);
+      const ours = {};
+      for (const role of ['ac-panel', 'ac-section', 'ac-row']) ours[role] = await o.evaluate(firstMatch, { candidates: [ourMarker(role)] });
+      await o.close();
+      draft.pages.autocomplete = { path, type: { input: inSel, text: query }, ready: { theirs: ac.panel, ours: ours['ac-panel'] ?? OVERLAY } };
+      draft.components.acPanel = { pages: ['autocomplete'], theirs: ac.panel, ours: ourMarker('ac-panel') };
+      if (ac.section) draft.components.acSection = { pages: ['autocomplete'], theirs: `${ac.panel} ${ac.section}`, ours: ourMarker('ac-section'), ...(ac.title ? { parts: { acTitle: { theirs: ac.title } } } : {}) };
+      if (ac.row) draft.components.acRow = { pages: ['autocomplete'], each: { sample: 4 }, theirs: `${ac.panel} ${ac.row}`, ours: ourMarker('ac-row'), text: 'exact' };
+      confirm('components.acPanel, acSection, acRow: guessed from what appeared after typing; ids for the rows (pages.autocomplete.ids) are not proposed');
+      for (const role of ['ac-panel', 'ac-section', 'ac-row']) if (!ours[role]) confirm(`components.${role === 'ac-panel' ? 'acPanel' : role === 'ac-section' ? 'acSection' : 'acRow'}.ours: ${ourMarker(role)} not found on our page`);
+      continue;
+    }
+    const t = await open('theirs', path);
+    const p = await t.evaluate(proposeTheirs, { empty: name === 'empty', legacy: [...LEGACY_MARKUP] });
+    // Their category's name and their titles: the queries their products are asked for with (pairing.mjs).
+    const hints = p.ids ? await t.evaluate(theirHints, { selector: p.ids.selector }) : null;
+    proposals[name] = { ids: p.ids, links: p.links ?? [], hints, oursPath, cross };
+    await t.close();
+    draft.notes.push(...p.notes.map((n) => `${name}: ${n}`));
+    draft.pages[name] = cross ? { theirs: { path }, ours: { path: oursPath } } : { path };
+    // Their ids: on their side of the page (another page of theirs: "theirs": { "path", "ids" }).
+    const idsAt = cross ? draft.pages[name].theirs : draft.pages[name];
+    const received = [];
+    const o = await open('ours', oursPath, (r) => received.push(r));
+    // Their products against the catalog records our page received: the pairing, by evidence.
+    if (p.ids) {
+      // The request whose records their products are (not the category lookup's, not a recommender's).
+      let found = null;
+      let req = null;
+      for (const r of received) {
+        const f = pairingOf(p.ids, p.links ?? [], r.hits);
+        if (f && (!found || f.n > found.n)) [found, req] = [f, r];
+      }
+      if (req?.type) draft.products.type = req.type;
+      if (req?.surface && req.endpoint === 'collections') draft.products.surface ??= req.surface;
+      if (found && (!pairing || found.n > pairing.n)) pairing = found;
+      idsAt.ids = found?.pair === 'url' ? { selector: p.ids.selector, child: 'a[href]' } : { selector: p.ids.selector, ...(found ? { attr: found.attr } : p.ids.candidates[0] ? { attr: p.ids.candidates[0].attr } : { child: 'a[href]', attr: 'href' }) };
+      // Our search page received our query's records, not their category's: the pairing another page finds is this one's too.
+      if (!found && cross) pending.push({ name, ids: p.ids });
+      else if (!found) confirm(`pages.${name}.ids: none of their tiles' ids (${p.ids.candidates.map((c) => c.attr).join(', ') || 'no id attribute'}) nor links matched a catalog record our page received: set products.attr and products.field (the catalog field with their values), or products.pair "url"`);
+      draft.pages[name].ready = { theirs: p.ids.selector, ours: ourMarker('tile') };
+    } else if (cross) {
+      // No tiles on their page: nothing to pair (the map then needs "ids", or "ids": false to compare by structure).
+      idsAt.ids = false;
+      confirm(`pages.${name}.theirs.ids: no product tiles found on their ${path}: point "ids" at their tiles, or keep "ids": false (compared by structure only)`);
+    }
+    if (cross) draft.notes.push(`${name}: our ${oursPath} is drafted against their ${path} (their own search disabled: their category listing is the design source; docs/PARITY.md)`);
+    for (const [cn, c] of Object.entries(p.components)) {
+      const role = cn === 'grid' ? 'list' : kebab(cn);
+      const marker = ourMarker(role);
+      const port = `${LISTING} ${lastStep(c.theirs)}`;
+      const oursRoot = await o.evaluate(firstMatch, { candidates: [marker, port] });
+      const comp = { pages: [name], theirs: c.theirs, ours: oursRoot ?? marker };
+      const lows = [];
+      if (!oursRoot) lows.push(`ours: ${marker} not on our page (put data-lbx-part="${role}" on the integration's element)`);
+      else if (oursRoot === port) lows.push(`ours: by their selector (${port}), no data-lbx-part="${role}" marker`);
+      if (c.low?.['.']) lows.push(`theirs: ${c.low['.']}`);
+      if (cn === 'tile') {
+        const key = c.keyCandidates.find((k) => k === pairing?.attr) ?? c.keyCandidates[0];
+        const oursHas = key && oursRoot ? await o.evaluate(hasAttr, { sel: oursRoot, attr: key }) : false;
+        // Keyed when both sides carry it; else by position (our listing shows their products in their order).
+        comp.each = { ...(oursHas ? { key } : {}), sample: 4 };
+      }
+      if (cn === 'grid') comp.grid = { item: { theirs: c.item, ours: partMarker('tile') } };
+      if (c.parts) {
+        comp.parts = {};
+        for (const [pn, spec] of Object.entries(c.parts)) {
+          // A part with parts of its own (a range filter's slider and inputs): { theirs, parts }.
+          const rel = typeof spec === 'string' ? spec : spec.theirs;
+          const pm = partMarker(pn);
+          const ranged = typeof spec === 'object' && Object.keys(spec.parts ?? {}).some((k) => k in RANGE_PARTS);
+          const ours = oursRoot ? await o.evaluate(firstMatch, { candidates: ranged ? [pm, RANGE_GROUP, rel] : [pm, rel], within: oursRoot }) : null;
+          // The marker is ours by default: only their selector is written then.
+          comp.parts[pn] = ours === pm || ours === RANGE_GROUP || !ours ? { theirs: rel } : rel;
+          if (!ours) lows.push(`parts.${pn}: not found in ours (${pm}, or ${rel})`);
+          else if (ours === rel && rel !== pm) lows.push(`parts.${pn}: ours by their selector, no ${pm} marker`);
+          if (c.low?.[pn]) lows.push(`parts.${pn}: theirs ${rel} is ${c.low[pn]}`);
+          const sub = typeof spec === 'object' ? spec.parts : null;
+          const ia = c.interact?.[pn] ?? null;
+          if (!sub && !ia) continue;
+          const at = typeof comp.parts[pn] === 'string' ? { theirs: rel, ours: rel } : comp.parts[pn];
+          if (sub) {
+            at.parts = {};
+            const inOurs = oursRoot && ours ? `${oursRoot} ${ours}` : null;
+            for (const [sn, srel] of Object.entries(sub)) {
+              const sm = partMarker(RANGE_PARTS[sn] ?? sn);
+              const found = inOurs ? await o.evaluate(firstMatch, { candidates: [sm, srel], within: inOurs }) : null;
+              at.parts[sn] = found && found !== sm ? srel : { theirs: srel };
+              if (!found) lows.push(`parts.${pn}.parts.${sn}: their ${sn} (${srel}) is not in ours (${sm}): a run finds it missing, CRITICAL, until our template renders it`);
+            }
+          }
+          if (ia) {
+            at.interact = ia;
+            lows.push(`parts.${pn}.interact: a real ${ia.action} on their live site: confirm the element, "watch" (the counter or state it changes${ia.watch ? `; drafted: ${ia.watch}` : ''}) and "safe" (a POST to a cart, a compare list or a wishlist is recorded, never sent, unless "safe": true)`);
+          }
+          comp.parts[pn] = at;
+        }
+      }
+      if (c.interact?.root) {
+        comp.interact = c.interact.root;
+        lows.push(`interact: a real ${c.interact.root.action} on their live site: confirm it, and "watch" what it changes`);
+      }
+      if (['count', 'sort', 'pagination', 'empty', 'facets'].includes(cn)) comp.text = 'shape';
+      const key = add(cn, name, comp);
+      for (const l of lows) confirm(`components.${key}.${l}`);
+    }
+    await o.close();
+  }
+  for (const { name, ids } of pending) {
+    const at = draft.pages[name].theirs;
+    const c = pairing?.pair === 'field' ? ids.candidates.find((x) => x.attr === pairing.attr) : null;
+    if (pairing?.pair === 'url') at.ids = { selector: ids.selector, child: 'a[href]' };
+    else if (c) at.ids = { selector: ids.selector, attr: c.attr };
+    else confirm(`pages.${name}.theirs.ids: their tiles' ids (${ids.candidates.map((x) => x.attr).join(', ') || 'no id attribute'}) matched no catalog record (our ${draft.pages[name].ours.path} shows our query's products, not theirs; another page, e.g. their category page on both sides, gives the evidence): set products.attr and products.field, or products.pair "url"`);
+  }
+  if (pairing) Object.assign(draft.products, pairing.pair === 'url' ? { pair: 'url' } : { attr: pairing.attr, field: pairing.field });
+  else if (Object.values(draft.pages).some((pg) => pg.ids || pg.theirs?.ids)) Object.assign(draft.products, { field: '@id' });
+  // The pairing checked as a run makes it: their products by id, with the queries a run asks with (pairing.mjs).
+  for (const [name, pr] of Object.entries(proposals)) {
+    const at = pr.cross ? draft.pages[name]?.theirs : draft.pages[name];
+    if (!pr.ids || !at?.ids) continue;
+    const byUrl = draft.products.pair === 'url';
+    const attr = at.ids.attr ?? draft.products.attr;
+    const ids = (byUrl ? pr.links.filter(Boolean) : (pr.ids.candidates.find((c) => c.attr === attr)?.values ?? [])).slice(0, 60);
+    const field = byUrl ? (draft.products.field ?? 'web_url') : draft.products.field;
+    if (!ids.length || !field) continue;
+    const queries = queryCandidates({ oursPath: pr.oursPath, cross: pr.cross, heading: pr.hints?.heading ?? null, titles: pr.hints?.titles ?? [] });
+    const o = await open('ours', pr.oursPath, null, { align: { ids, field, type: draft.products.type, surface: draft.products.surface, pair: byUrl ? 'url' : 'field', queries } });
+    const al = await o.evaluate(() => window.__parity?.aligned ?? []);
+    await o.close();
+    const failed = pairingFailure(ids, al, { selector: pr.ids.selector, type: draft.products.type });
+    if (failed) {
+      confirm(`pages.${name}: pairing failed: ${failed.why}`);
+      continue;
+    }
+    const best = al.reduce((a, b) => (b.found > a.found ? b : a));
+    // A query that found them and that the page does not give itself (our path's q): drafted as the page's, asked first.
+    const own = queryOfPath(pr.oursPath).toLowerCase();
+    const need = (best.queries ?? []).filter((q) => q.found > 0 && q.query && q.query.toLowerCase() !== own).map((q) => q.query);
+    if (need.length) draft.pages[name].query = need.length === 1 ? need[0] : need;
+    if (best.found < ids.length) draft.notes.push(`${name}: ${ids.length - best.found} of their ${ids.length} products not found by the API (asked with ${formatQueries(best.queries)}): not in the catalog, or another query finds them (pages.${name}.query)`);
+  }
+  for (const pg of Object.values(draft.pages)) for (const at of [pg, pg.theirs]) if (at?.ids?.attr && at.ids.attr === draft.products.attr) delete at.ids.attr;
+  // The mandatory components their pages did not show: map them, or exclude them with a reason.
+  const have = new Set();
+  for (const [cn, c] of Object.entries(draft.components)) {
+    const r = kebab(c.role ?? cn);
+    have.add(r);
+    if (r === 'facets') for (const pn of Object.keys(c.parts ?? {})) have.add(kebab(pn));
+    if (r === 'tile') for (const pn of Object.keys(c.parts ?? {})) have.add(`tile.${kebab(pn)}`);
+  }
+  const missing = MANDATORY.filter((m) => !have.has(m));
+  if (missing.length) confirm(`not found on their pages: ${missing.join(', ')}. Map each (another page, a state), or list it in "excluded" with a reason`);
+  draft.notes.push(`Part names Luma's built-in templates mark (data-lbx-part): ${PARTS.join(', ')}.`);
+  return draft;
+};