@luigisbox/luma 0.0.0-stage → 0.2.0

package/docs/PARITY.md

@@ -0,0 +1,946 @@
+# Parity: does the integration look exactly like the site it replaces?
+
+`yarn luma parity` compares a client site's own search and category UI with the
+Luma integration that replaces it, component by component, and puts a number
+on the difference. The aim is a 1:1 port that nobody can tell from the
+original. The method: computed values from the live DOM, whole, never
+sampled from a screenshot. Pixels are a second signal.
+
+## Usage
+
+In the integration repository, with the one `luma` script (README, "Tools for an
+integration repository"):
+
+```bash
+yarn luma parity --init                 # a draft map: integration/parity.draft.json, to confirm
+yarn luma parity --init --their-plp /shoes     # their search disabled: our search drafted against their category listing
+yarn luma parity --record --headed      # the live site once into parity/recording/
+yarn luma parity                        # replays the recording: offline, the same numbers every run
+yarn luma parity --target 98            # the same; exit 0 only when the port has converged
+yarn luma parity --live --headed        # the live site, nothing recorded
+yarn luma parity --only tile,grid --viewports 390,1440 --all
+```
+
+| Option | |
+|---|---|
+| (default) | replay the recording (`--archive`, default `parity/recording`): offline, deterministic |
+| `--target <n>` | the template score that ends the loop (default 98, "The convergence loop") |
+| `--record` | the live site, recorded into the archive (replaces it; with `--only`, adds to it) |
+| `--live` | the live site, nothing recorded |
+| `--init [file]` | a draft map from the site's pages (default `integration/parity.draft.json`; never overwrites the map) |
+| `--their-plp <path>`, `--our-search <path>` | with `--init`: their own search is disabled; our search page (default `/search?q=<fixtures.query>`, `luma.config.mjs`) is drafted against this category listing of theirs ("When their own search is disabled") |
+| `--map <file>` | the map (default `integration/parity.json`) |
+| `--only <names>` | components to compare |
+| `--viewports <list>` | widths (default: the map's, 390, 1024, 1440) |
+| `--out <dir>` | the report folder: `index.html`, `report.json`, the crops (default `parity-report`) |
+| `--json <file>` | the JSON report there too (its folder made when it does not exist) |
+| `--all` | every difference in the terminal (default: the first 12 per component and width) |
+| `--headed` | show the browser |
+| `--profile <dir>` | a Chrome profile you use on the site (runs headed; `yarn luma chrome` keeps one per host, `~/.lbx-chrome/<host>`); copied first, since Chrome locks a profile in use |
+| `--dev [url\|port]` | the dev server (`yarn dev`) instead of a build: its port (`--dev 5173`), its URL (`--dev http://localhost:3000`; a URL with a path is the entry itself), default `https://localhost:8069` |
+| `--no-build` | the `dist/` as it is |
+| `--block <patterns>` | vendor scripts blocked on both sides (comma-separated: a host, `cdn.vendor.com`, its subdomains too; or a regular expression on the URL); `--init` also blocks every `*.luigisbox.{tech,com,ai}` script |
+| `--host <name>`, `--site-dir <dir>` | the storefront (default: the map's `host`, `LBX_HOST`); the integration repository |
+
+Exit code: 0 converged (below), 1 not yet, 2 nothing compared or the run
+broke. A bot challenge (HTTP 429, a challenge page) stops the run and says so.
+It is never worked around: run it on the client's own site with their
+knowledge, or ask them to allowlist the runner.
+
+## The convergence loop
+
+An integrating agent (or a person) ports the site and loops on one command
+until it exits 0:
+
+```bash
+yarn luma parity --record --headed      # once, and again when the site or the map's pages change
+yarn luma parity --target 98            # read the top of the output, fix, run again
+```
+
+**Converged** (exit 0) means all of:
+
+1. the **template score** is at or over `--target` (default 98);
+2. no CRITICAL or MAJOR **template** difference is left (MINOR ones may stay);
+3. every mandatory component is mapped or excluded ("Coverage");
+4. their products paired with ours on every page with ids (a failed pairing
+   is CRITICAL and named first: "Pairing their products with ours");
+5. no component's template score is under its threshold (the map's
+   `thresholds`: `components.<name>`, else `score`, default 90).
+
+The top of the terminal output is all an agent needs, in this order:
+
+- the verdict (`CONVERGED` / `NOT CONVERGED`, the template and overall
+  scores, why not);
+- **TEMPLATE DIFFERENCES (yours to fix), by weight**: CRITICAL and MAJOR
+  first, then by the weight they take off the score (the severity's weight x
+  the instances and viewports they show on). Each one: the component and
+  part, the property, the viewports, the **selectors** on both sides, theirs
+  and ours whole, and **fix**: the integration file and what to change there
+  (`parity/hints.mjs`, from our side's selector: a style goes in the
+  stylesheet with a rule for that class; a missing part, a text or the order
+  in the template that renders it; when the integration has none, Luma's
+  built-in template to copy into the integration under the same name);
+- **DATA DIFFERENCES (for the client)**: what the catalog or the API owns,
+  with the catalog's value as evidence. Not the agent's to fix: report them;
+- **DECIDED**: the differences a recorded product decision keeps ("Product
+  decisions"), each with the decision; they count as passed in the template
+  score;
+- **COVERAGE**: every mandatory component, mapped by what, excluded why, or
+  MISSING.
+
+Then the scorecard and the details per component and viewport, as before.
+`report.json` holds the same: `verdict`, `todo` (the template differences,
+ranked, each with `selector` and `fix`), `data`, `decided`, `coverage`, `results`,
+`aligned` (per page and width: their ids, the queries tried, what each found).
+
+Severities: CRITICAL a missing or extra element, a text, a column count at
+any viewport (a grid's, or a tile's own: "Phone widths"), a failed pairing, a
+state step ours cannot take, a widget of theirs missing outside our
+components, the space around our listing off by more than 100 px from their
+listing page's, an interactive element that does something on theirs and
+nothing on ours or that errs on ours, a control only ours has that does
+nothing ("Behaviour"), a sub-control of a part theirs has and ours lacks
+("Parts of parts"), a frame of their listing on a reload of ours ("The
+hold") (a CRITICAL difference weighs 5); MAJOR any other property out of
+tolerance, the space between siblings off by more than 2 px, a block of
+theirs moved or resized, a layout shift ours adds, the space around our
+listing off beyond `collateral.gap`, an element of theirs under our listing
+that renders nothing yet takes more than 100 px, an interaction's outcome
+that differs (another URL, request, product id, watched state), an edge
+their components share that ours breaks ("Alignment") (1); MINOR what a shopper
+hardly sees: a box off by at most 1 px, a colour within ΔE 5, `cursor`,
+`transition`, a sibling gap off by at most 2 px, the pixel share (1; the
+pixel share 2).
+
+## Who owns a difference: the template or the data
+
+Every difference has an owner (`parity/owner.mjs`), `template` (ours to fix)
+or `data` (the client's). It is **data** when it follows from the product
+data or the API, not from our markup or CSS:
+
+- a text that differs because the paired product's catalog values differ:
+  ours shows a catalog value of the product as it is (its `@title`, its
+  price), theirs shows another value that is no catalog value of that
+  product. The evidence is in the finding (`evidence`: the field and the
+  catalog's value). Theirs showing another field (a brand where we show the
+  title), the same value formatted otherwise (`€1,199.50` vs `1 199,50 €`) or
+  ours' value with more around it is the template's;
+- on an instance whose text is the data's, its boxes and its pixel share (a
+  longer title is a taller box);
+- their product missing from the catalog (unpaired: the API did not find it
+  by `products.field`): one data difference per product, which counts as a
+  0 instance in the overall score;
+- what the map declares the API cannot supply, `"dataGaps"`, each with its
+  reason:
+
+```json
+"dataGaps": {
+  "facetCounts": "the API returns no facet value counts",
+  "empty": "the search is fuzzy: an empty result cannot occur",
+  "acSections": "the channel has no query suggestions",
+  "tile.badge": "the catalog has no badge field"
+}
+```
+
+| Gap | Its differences |
+|---|---|
+| `facetCounts` | in facet components and parts: a text that differs only by its count (`Red (12)` vs `Red`), a missing part named like a count |
+| `empty` | every difference of the empty state (`empty`, `ac-empty`) |
+| `acSections` | autocomplete sections and their titles, and the panel's height and pixels |
+| `<component>`, `<component>.<part>` | every difference of that component or part |
+
+Everything else is **template**: geometry, computed styles, fonts,
+structure, missing parts, order. The **template score** counts the data's
+differences as passed checks; the **overall score** counts everything. Both
+are reported per component and viewport and overall. The text attribution
+needs the products paired (`products`, `pages.<name>.ids`) and the tile's
+role (a component named `tile`, `ours` the tile marker, or `"role": "tile"`;
+autocomplete rows: `ac-row`).
+
+## Coverage: the mandatory components
+
+`parity/map.mjs` `MANDATORY`. The map covers each one, or lists it in
+`"excluded"` with a reason; `yarn luma parity` prints the coverage, and does not
+converge while one is neither.
+
+| | |
+|---|---|
+| `tile` | the product tile, with its parts `tile.image`, `tile.title`, `tile.price`, `tile.old-price`, `tile.badge` |
+| `grid` | the tiles' list (columns per row, gaps) |
+| `facets`, `facet-group`, `facet-title`, `facet-value` | the facet container, a group, its title, a value |
+| `sort`, `count` | the sort control, the result count |
+| `pagination` | "show more" (`more` covers it). Luma has no numbered pager: their "show more", or their pager's next-page control, is compared with ours; a numbered pager of theirs is otherwise `"excluded"` with that reason |
+| `empty` | the empty state (`ac-empty` covers it too) |
+| `ac-panel`, `ac-section`, `ac-row` | the autocomplete panel, a section (`ac-title` covers it), a row |
+
+A component covers the mandatory one of its role: its `"role"`, else its name
+kebab-cased (`facetGroup` is `facet-group`), else the marker its `ours`
+selector names (`[data-lbx-part~="tile"]`). A part covers its role too (a
+`facets` component's `facetGroup` part); a tile's parts cover `tile.<part>`
+(`oldPrice` is `old-price`).
+
+```json
+"excluded": {
+  "tile.badge": "their tiles show no badge",
+  "ac-section": "their autocomplete is one flat list"
+}
+```
+
+### Product decisions
+
+An exclusion can carry the product decision behind it, with its reason: an
+object instead of the reason string (`reason` defaults to the `decision`;
+`by` and `date` are kept as they are). The coverage prints it beside the
+reason.
+
+```json
+"excluded": {
+  "tile.badge": { "reason": "their tiles show no badge", "decision": "no badges on the new tiles", "by": "design review", "date": "2026-09-30" },
+  "tile.title color": { "reason": "our brand colour", "decision": "keep ours" },
+  "collateral.div.promo-strip": { "decision": "the strip goes with the old search" }
+}
+```
+
+With a `decision`, an entry may also name what the map compares: a mapped
+component (`"tile"`), a part (`"tile.title"`), either with a property
+(`"tile.title color"`), or `"collateral"` and a collateral block
+(`"collateral.<block path>"`, as the report names it). Its differences are
+then **decided**: neither the template's nor the data's, listed under
+DECIDED (`report.json` `decided`) with the decision, and counted as passed in
+the template score, so a deliberate deviation does not block convergence. A
+plain reason string still only excludes a mandatory component; a name that is
+neither is an error.
+
+## How it is deterministic
+
+A plain screenshot diff of their page and ours measures data, not design: our
+results are other products. So:
+
+1. **The same products.** On their page the tool reads their product ids
+   (`pages.<name>.ids`: an attribute of their tiles, or a child's, e.g. a
+   `meta[itemprop=url]`). On ours, Luma's product request goes out as it is
+   (total, guid, cursor: the facets and "show more" stay the real query's),
+   further requests fetch exactly their products by id (`products.field`,
+   through a collections `surface` when given, then the search endpoint with
+   a query that finds them, never an empty one; never our page's scope or
+   filters, so they are found on our search page as on our category page),
+   and Luma gets those hits in their order (`parity/probe.mjs` `alignInit`, a
+   `fetch` wrapper in the page). Their ids are paired with our hits as
+   `products.pair` says (below, "Pairing their products with ours"), whatever
+   fields the build requests. Tiles and autocomplete rows are paired by key
+   (`each.key`) or by position. Products the API cannot find are listed in
+   the report; a pairing that finds none of them is CRITICAL.
+2. **Element correspondence.** The map pairs their selectors with ours, per
+   component and part. Luma's built-in templates mark their parts with
+   `data-lbx-part` (`tile`, `image`, `title`, `price`, `list`, `count`, `sort`,
+   `pagination`, `more`, `facets`, `facet-group`, `facet-title`, `facet-value`,
+   `empty`, `ac-panel`, `ac-section`, `ac-title`, `ac-row`, `ac-all`,
+   `ac-empty`). A part with no selector of ours defaults to its marker. An
+   integration's own templates mark theirs too ("Markers on site-specific
+   markup", below).
+   Selectors see into **open shadow roots**, on both sides: Luma's autocomplete
+   renders in the shadow root of `[data-lbx="ac-overlay"]` (`dom: 'light'` is
+   the opt-out), and a shop's header can be a web component. A descendant or
+   child combinator crosses from a shadow root to its host, so
+   `[data-lbx="ac-overlay"] [data-lbx-part~="ac-row"]` is the overlay's rows,
+   and a marker alone (`[data-lbx-part~="ac-row"]`) finds them too; a part's
+   selector finds it in its root's shadow trees. Boxes, computed styles, the
+   rendered font and the visible text (the flat tree: shadow content and what
+   slots show) are read there as in the light DOM, in the composed tree's
+   order (an element, its shadow tree, its light children), so a run is as
+   repeatable as without. `hide` reaches into open shadow roots too. Closed
+   shadow roots stay closed (`parity/probe.mjs` `deepInit`).
+3. **Property by property**, per element (`parity/compare.mjs`): presence (a
+   missing or extra element is CRITICAL), the box relative to the component,
+   the font actually rendered (CDP), the visible text (exact, or `shape` for
+   counts, where every number is alike), and about 70 computed longhands:
+   typography, colours by CIEDE2000 with alpha apart, borders, radii, shadows
+   layer by layer, spacing, layout, transforms, transitions. The parts' order
+   is compared too, and so are grids: columns per row (CRITICAL), gaps, item
+   width and padding, at every viewport; and the space between consecutive
+   siblings of a repeated part or component ("The space between siblings").
+   Then a pixel diff of the two crops (pixelmatch, anti-aliasing ignored, the
+   size difference counted). Outside our components, their page as without
+   us ("The collateral check").
+4. **Stability.** A fixed viewport and DPR 1 (a phone width as a phone:
+   "Phone widths"), the map's locale and timezone,
+   a light colour scheme, `Math.random` seeded, service workers blocked. The
+   map's `hide` regions (a consent modal) are hidden, never clicked. Images in
+   measured roots are loaded eagerly and decoded, fonts are loaded, CSS
+   animations and transitions are finished (their `transition` value is still
+   measured), the network is quiet, and the layout is the same on two reads.
+   Every component is measured before anything scrolls, then the collateral
+   blocks. Crops follow, with animations off, the caret hidden and the map's
+   `mask` painted over. Hover comes last. Each state is a fresh pair of pages,
+   its steps taken in order on each side, settled the same way ("States").
+5. **Repeatable.** `--record` stores what the browser received (pages,
+   assets, API answers) in `parity/recording/`: `index.json` (request key ->
+   status, headers, body hash) and `bodies/` (content-addressed). The key is
+   the method, the URL without volatile params (`_`, `v`, `ts`, …,
+   `archive.ignore`) and a POST body's hash. Replay answers from it. A GET
+   with no exact match gets the same path with the most equal params, and
+   anything else is aborted and counted (a site's beacons, mostly). Luigi's Box
+   auth is never recorded: replay answers it with a fixed token. Cookies and
+   auth headers are never stored. Two replays of one recording give identical
+   `results` in the JSON. An API request the recording lacks
+   (the build or the map asks for other data) is reported: re-record.
+
+## The map (`integration/parity.json`)
+
+JSON only, committed with the integration, read and never written by the tool.
+The full shape is in `parity/map.mjs`.
+
+```json
+{
+  "host": "www.shop.example",
+  "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": ["#consent-modal"],
+  "phone": 767,
+  "collateral": { "ignore": [".rotating-banner"], "cls": 0.02 },
+  "products": { "attr": "data-product-id", "field": "id", "type": "product", "surface": "lbs_collection_main" },
+  "pages": {
+    "category": { "path": "/shoes", "ids": ".listing .tile", "query": "shoe",
+                  "ready": { "theirs": ".listing .tile", "ours": "lbx-plp .tile" },
+                  "storage": { "theirs": { "localStorage": { "listingView": "grid" } } },
+                  "states": [
+                    { "name": "drawer-open", "viewport": 390, "steps": [
+                        { "click": { "theirs": ".filters-toggle", "ours": "lbx-plp .filters-toggle" } },
+                        { "wait-for": { "theirs": ".filters-drawer", "ours": "lbx-plp [data-lbx-part~=\"facets\"]" } } ] },
+                    { "name": "tile-hover", "components": ["tile"], "steps": [ { "hover": { "theirs": ".listing .tile .tile__image", "ours": "lbx-plp [data-lbx-part~=\"image\"]" } } ] }
+                  ] },
+    "autocomplete": { "path": "/", "type": { "input": "input[name=q]", "text": "shoe" },
+                      "ids": { "selector": ".ac-row", "child": "meta[itemprop=url]", "attr": "content", "field": "id" } }
+  },
+  "components": {
+    "tile": { "pages": ["category"], "theirs": ".listing .tile", "ours": "lbx-plp [data-lbx-list] .tile",
+              "each": { "key": "data-product-id", "sample": 4 }, "states": ["hover"],
+              "parts": { "title": ".tile__title", "price": { "theirs": ".price", "ours": "[data-lbx-part~=price]" } } },
+    "grid": { "pages": ["category"], "theirs": ".listing", "ours": "lbx-plp [data-lbx-list]", "grid": { "item": ".tile" } },
+    "count": { "pages": ["category"], "theirs": ".result-count", "ours": "lbx-plp .lbx-s__count", "text": "shape" }
+  }
+}
+```
+
+- A selector is a string (both sides), `{ "theirs": …, "ours": … }`, and each
+  of those a string or `{ "<page>": …, "default": … }`.
+- `each`: a repeated component (tiles, rows). `sample` instances are compared,
+  chosen so that every part theirs shows appears at least once.
+- `text`: `exact` (default for repeated components), `shape` (default for the
+  others) or `false`. `ignore`: properties or groups (`font`, `colour`,
+  `border`, `radius`, `shadow`, `spacing`, `layout`, `motion`, `box`, `text`).
+- `block`: URL patterns aborted per side. The defaults: on ours, Luigi's Box
+  scripts of the site (its previous-generation widgets, the platform's
+  loader); on theirs, the platform's loader only (their previous-generation
+  widgets are their UI).
+- `products.pair`: how their ids meet our hits (next section).
+- `pages.<name>.path`: both sides' page. `"theirs": { "path" }` and
+  `"ours": { "path" }` give a side its own (the shared `path` stays the
+  default of the other): our search page against their category listing
+  ("When their own search is disabled", below).
+- `pages.<name>.query` (a string, or a list): the query their products are
+  asked for with, first ("Pairing their products with ours"). `--init`
+  drafts it when a run needs one.
+- `pages.<name>.storage`: `localStorage` / `sessionStorage` keys set before
+  every load, both sides' or per side (`"theirs"`, `"ours"`): a view mode their
+  page reads ("Phone widths").
+- `pages.<name>.states`: scripted states, measured as the page is ("States").
+- `phone`: the widest viewport measured as a phone (default 767; `false`:
+  never). `collateral`: the collateral check's `ignore` (selectors outside our
+  components that differ by nature: a rotating banner), `cls` (the layout
+  shift ours may add, default 0.02) and `gap` (the px the space around our
+  listing may differ from their listing page's, default 4: "The layout around
+  the listing"); `false` turns it off.
+- `role`: which mandatory component a component is when its name does not
+  say it ("Coverage"). `excluded` (with product decisions), `dataGaps`: above.
+- A part's `parts` (its sub-controls: "Parts of parts") and `interact`, a
+  component's `interact`, the map's `behaviour` ("Behaviour"); `alignment`
+  and `search.field` ("Alignment"); `hold` (the map's, or a page's: "The
+  hold").
+
+### `--init`: a draft from their page
+
+`yarn luma parity --init` loads their pages and ours and writes a draft map
+(`integration/parity.draft.json`, never the map itself):
+
+- **their side, by structure**, not by class names alone: the product tile
+  is the element repeated as siblings with an image and a link, most with a
+  price (wrappers around it skipped). Its parts by role, over the first tiles
+  (one tile's old price, another's badge): the largest image (with its frame
+  when the frame is only the image), the largest price-like text as the
+  price, a crossed-out one as the old price, a heading (else an element named
+  title or name, else the longest link text) as the title, a short label
+  named badge/flag/label (else one laid over the image) as the badge. The
+  facet container is the element whose children are groups of options
+  (checkboxes, `role=checkbox`, links with counts), with a group's title and
+  value as parts. The sort control is a select of sort orders (else an
+  element named sort, else one labelled "sort"); the count the shortest text
+  with a number of products; the pagination a pager, numbered links or a
+  "show more";
+- **our side, by the markers**: `:is(lbx-search, lbx-plp) [data-lbx-part~="<role>"]`
+  (the autocomplete's under `[data-lbx="ac-overlay"]`), checked on our page;
+  their selector only when a 1:1 port has it and no marker;
+- **the pairing, by evidence**: their tiles' id attributes (and links) are
+  matched against the catalog records our page received; the attribute and
+  the field that hold the same values become `products.attr` /
+  `products.field` (or `"pair": "url"`), with the request's `type` and
+  collections `surface`. Then the pairing is **checked as a run makes it**:
+  our page asks for their products by id with the run's queries ("Pairing
+  their products with ours"). A query that found them and that our page does
+  not give itself is drafted as `pages.<name>.query`; a pairing that finds
+  none is listed to confirm, with the queries tried;
+- **never previous-generation or vendor markup 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 while it drafts, and markup of a previous Luigi's Box
+  generation or a known search vendor (`map.mjs` `LEGACY_MARKUP`:
+  `#lbx-ac-element`, `.luigi-ac`, `[class*="luigisbox"]`, other search
+  vendors' widgets, …) is never picked, nor what holds it, even
+  when the page renders it server-side.
+
+Every pick it is not sure of is listed in `"confirm"` (a part ours lacks, a
+title taken from link text, a pairing that matched nothing or failed its
+check, the mandatory components not on their pages): confirm each, then
+remove `draft`, `confirm` and `notes`. A run on a draft says so in its notes.
+
+### Markers on site-specific markup
+
+An integration whose templates carry their own markup (a 1:1 port of the
+site's tile, facets, header) puts `data-lbx-part="<part>"` on the elements
+that are those parts, as Luma's built-in templates do:
+
+```ts
+html`<article class="product-card" data-lbx-part="tile">
+  <a href=${r.c.url}>${img(r, i)}<h3 class="product-card__name" data-lbx-part="title">${plain(r.c.title)}</h3></a>
+  <span class="product-card__price" data-lbx-part="price">${price(r.c.price)}</span>
+</article>`
+```
+
+Then the map names no selector of ours (every part's ours defaults to its
+marker), `--init` finds ours by the markers, coverage recognises the parts,
+and the fix hints find the template and the class the marker is on. The
+names are `map.mjs` `PARTS`; a value can hold several (`data-lbx-part="facet-value chip"`).
+
+## Pairing their products with ours
+
+On ours, `yarn luma parity` fetches the products their page shows (requests of its
+own, besides Luma's: below) and hands Luma those hits in their order. Each id
+read from their page (`pages.<name>.ids`) is paired with a hit in one of two
+ways (`products.pair`):
+
+| `products.pair` | their id | our hit's | the request for their products |
+|---|---|---|---|
+| `"field"` (default) | the value of `ids.attr` (`products.attr`) | `products.field` (`ids.field`), its first value when a list: `@id`, `lbx:group_id`, a SKU | `products.field` in their ids |
+| `"url"` | a link: `ids.attr` defaults to `href` (relative, absolute, another host, a trailing slash: all alike) | `url`, else `web_url`, else `products.field` | `products.field` (default `web_url`) in each id as read, its path and its absolute URL on the storefront |
+
+Pairing never depends on what the integration requests. When the build lists
+`return_fields` (`search.fields`, an autocomplete type's `fields`) without the
+pairing field, the extra request asks for it too, and the hits Luma gets have
+it removed again (unless the API returns it unasked: `@id`, `@type`,
+`@title`, or a field the build's own answer carries). Luma's own request goes
+out unchanged, so what renders is what the build renders. `report.json`
+`aligned` shows per request how it paired (`pair`), the field it added
+(`added`), how many were asked and found, and the ids not found.
+
+```json
+"products": { "attr": "data-group-id", "field": "lbx:group_id", "type": "product", "surface": "lbs_collection_main" }
+"products": { "pair": "url", "type": "product" }
+```
+
+With `"field"`, their attribute must hold the catalog's value exactly (use
+`ids.transform` `"path"` or `"absolute"` for links). Use `"url"` when their
+markup carries no catalog id, only links. One hit per id: with a group field,
+the first hit the API returns for a group is the one shown.
+
+### The queries their products are asked for with
+
+Their products are fetched by id **together with a reasonable query**: many
+channels answer the search endpoint's empty query with zero hits, and an id
+request with an empty query then paired nothing (the run compared structure
+only, and said nothing). The requests (`parity/probe.mjs` `alignInit`, the
+queries from `parity/pairing.mjs`):
+
+1. with a collections `surface` (or when the build's own request is a
+   collections one): by id alone, no query (collections take none);
+2. then the search endpoint, with each query in turn, at most 4: the map's
+   page query (`pages.<name>.query`, a string or a list), our page's own
+   query (its `q`, `query`, `search`, … param, or what the page types; not on
+   our search page against another page of theirs: our query is not their
+   products'), their category's name (their page's first `h1`, else the
+   breadcrumb's last item), the most frequent words of their tiles' titles
+   (numbers and stop words aside);
+3. each request asks only for the ids the ones before did not find, and they
+   stop when every one is found.
+
+The queries tried are reported: the terminal's PAGES section (`category:
+their 12 products by id, 12 paired, asked with "Running Shoes" 0/12,
+"shoe" 12/12`), the products not found with the queries they were asked
+with, and `report.json` `aligned` (per page and width `queries`, the
+candidates, and per request `queries`, each `{ endpoint, query, asked, found }`).
+`--init` checks the pairing it drafts the same way and drafts the query a
+run needs.
+
+**A pairing that still fails fails loudly.** When their page shows no ids,
+our build asks for no product of their type, or no request finds any of their
+products, the page's result `pairing` is a CRITICAL difference scoring 0, the
+verdict's first reason (`pairing failed on category at 390px: none of their
+12 products found by the API (tried "Running Shoes", "shoe"): set
+pages.<page>.query …`) and the first of the fix list, which points at the map.
+It never degrades to structure only in silence. Some of their products not
+found are the data's, as before (not in the catalog).
+
+## When their own search is disabled: our search against their category listing
+
+Many shops have their own search switched off: their search page is empty,
+or it is driven by a previous Luigi's Box generation, which is not the
+site's own design. The rule then: **our search results page converges on the design of
+their category listing (PLP)**: its tile, grid, facets, sort, count and
+pager. A page of the map compares our page against another page of theirs:
+
+```json
+"products": { "attr": "data-product-id", "field": "@id", "type": "product" },
+"pages": {
+  "search": {
+    "theirs": { "path": "/shoes", "ids": ".listing .tile" },
+    "ours": { "path": "/search?q=shoe" },
+    "ready": { "theirs": ".listing .tile", "ours": "lbx-search [data-lbx-part~=\"tile\"]" }
+  }
+}
+```
+
+- **A path per side.** `"theirs": { "path" }` and `"ours": { "path" }` sit next
+  to the shared `path`, which stays the default of both (`{ "path": "/shoes",
+  "ours": { "path": "/search?q=shoe" } }` is the same page). A component's
+  `pages` and per-page selectors name the page (`search`) as before.
+- **Their products, ours too.** Their ids are read on their page, as on any
+  page (`ids`, or `"theirs": { "ids" }`), and our search page shows exactly
+  those products in their order, so tiles compare product to product. The
+  requests for them ask for their ids, never our scope or filters, and with
+  their category's name or their titles' words, never our query (their
+  category's products need not match it; "Pairing their products with ours");
+  Luma's own request goes out as it is, so our count, facets and "show more"
+  are our query's.
+- **Texts by their shape.** A product's texts stay exact (it is the same
+  product). Every other text is compared by its shape, whatever the map says
+  (`text: "exact"` included): their `25 products` and our `30 products` are
+  alike, `30 results for "shoe"` is not (the wording is the template's:
+  word our search's count as their listing's, and its default sort). Facet
+  values are not compared as text (their category's values and our query's
+  are other result sets; so are a facet container's and a group's texts,
+  which hold them): their facets' structure and styles are. A text the map
+  turns off (`text: false`) stays off.
+- **Validation.** A page whose `theirs` path is another than ours must
+  declare `ids` on their side, so ours shows their products. `"ids": false`
+  compares it by structure only: tiles by position, their texts not
+  compared (another product's title is not a difference). A page with one
+  path and no ids works by structure, as always.
+- **The design source in the report.** Every page states which of their
+  pages it was compared against: the terminal's `PAGES` section (`search:
+  ours /search?q=shoe against theirs /shoes (another page of theirs, the
+  design source; …)`), every component's heading, `report.json` `pages` (per
+  page `theirs`, `ours`, `cross`, `paired`) and each result's `against`.
+- **`--init --their-plp <path>`** drafts the search page against that
+  listing (`--our-search <path>`, default `/search?q=<fixtures.query>`), and
+  their category listing on both sides beside it: our category page receives
+  their products, the evidence for the pairing (`products.attr`/`field`), the
+  search page's ids on their side. Their empty search is not drafted (it is
+  no design of theirs: map `empty` from another state, or exclude it).
+- **What surrounds the listing** (the heading and toolbar above it, the gap
+  to their footer below it) is their listing page's design too, not their
+  search page's: the collateral check compares the space around our listing
+  with their listing page's ("The layout around the listing"). Everything
+  else outside our components (their header, a widget removed, the layout
+  shift) is still compared with their search page without us.
+- **`--record`** records both pages, theirs and ours; the recording's
+  `index.json` `meta.pages` holds both paths per page (`{ "search": {
+  "theirs": "/shoes", "ours": "/search?q=shoe" } }`).
+
+Recordings made before the id request dropped our page's query, scope and filters
+(a map without a collections `surface`), or before it took queries, miss the
+new requests: re-record.
+
+## Phone widths
+
+A width up to the map's `phone` (default 767 px) is measured **as a phone**:
+its contexts are touch, `isMobile` (the page's meta viewport applies) and a
+phone's user agent (`engine.mjs` `deviceOf`), at DPR 1 as every width. Wider
+ones are a desktop window.
+
+Why: a page can lay out its grid by the device, not only the width. Measured
+as a narrow desktop window, 390 px can get two columns where a phone gets
+one; on a phone (a script reading the device, a server serving its
+phone markup, `pointer: coarse`) it is one. Measured as a phone, the
+difference is there. With `--profile` (one desktop context) the phone widths
+stay a narrow window, and the notes say so.
+
+A column count differing is **CRITICAL at any viewport, always**: a grid
+component's (`grid.columns`), and, when the page has no grid component, the
+tile's own (its instances' first row: `tile` `columns`). It is never the
+data's, whatever `dataGaps` says.
+
+A listing's view mode can come from storage (their grid/list toggle kept in
+`localStorage`): every storage key their page reads that looks like one
+(`view`, `mode`, `grid`, `list`, `layout`, `columns`, …) is in the notes
+(`category: their page reads localStorage "viewMode" (not set): …`), and
+`pages.<name>.storage` sets it before every load, per side, so both sides
+show the view a shopper's first visit shows (or the one to compare).
+
+## The space between siblings
+
+Each element's own box can match while the space between one and the next
+does not: facet groups squeezed together (a `.group + .group` margin theirs
+has, a parent's `gap`), a group's values, tiles in a column. For a part that
+repeats inside its component (a facet container's groups, a group's values)
+and for a repeated component's instances (`each`: tiles, rows), the
+consecutive siblings (the matches of one parent, in order) are measured too
+(`compare.mjs` `layoutOf`): stacked or side by side, the space between
+neighbours in a row (`sibling-column-gap`) and between rows
+(`sibling-row-gap`, the median gap). A gap up to 2 px off is MINOR, beyond it
+MAJOR; stacked against side by side MAJOR. The fix hint names the margin or
+the parent's gap. `ignore: ["spacing"]` (or `"siblings"`) leaves it out.
+
+## States
+
+A page as loaded is one state; the map can script others before measuring:
+a drawer open at 390, a facet group collapsed, the listing after a filter is
+applied, a tile hovered (an image gallery on hover):
+
+```json
+"states": [
+  { "name": "drawer-open", "viewport": 390, "steps": [
+      { "click": { "theirs": ".filters-toggle", "ours": "lbx-plp .filters-toggle" } },
+      { "wait-for": { "theirs": ".filters-drawer", "ours": "lbx-plp [data-lbx-part~=\"facets\"]" } } ] },
+  { "name": "group-collapsed", "steps": [ { "click": { "theirs": ".facet:first-child h4", "ours": "lbx-plp [data-lbx-part~=\"facet-title\"]" } } ] },
+  { "name": "after-apply", "steps": [
+      { "click": { "theirs": ".facet label", "ours": "lbx-plp [data-lbx-part~=\"facet-value\"]" } },
+      { "wait-for": { "theirs": ".active-filters", "ours": "lbx-plp .lbx-chips" } } ] },
+  { "name": "tile-hover", "components": ["tile"], "steps": [ { "scroll": { "y": 0 } }, { "hover": { "theirs": ".tile .tile__image", "ours": "lbx-plp [data-lbx-part~=\"image\"]" } } ] },
+  { "name": "typed", "steps": [ { "type": "input[name=q]", "text": "sho" }, { "press": "ArrowDown" }, { "press": "Escape", "on": "input[name=q]" } ] }
+]
+```
+
+- **Steps**, in order: `click`, `hover`, `wait-for` (visible), `scroll` (a
+  selector into view, or `{ "y": <px> }`), `type` (`"text"`, optional
+  `"delay"`), `press` (a key; `"on"` a selector, else the focused element).
+  A target is a selector both sides share, or `{ "theirs": …, "ours": … }`,
+  each side its own; a side without one skips the step (`"side": "theirs"`
+  takes a step on one side only).
+- `name` (letters, digits, `-`, `_`), `viewport` (a width or a list; default
+  every viewport), `components` (default: every component of the page).
+- **How it runs** (deterministic): per state and width a fresh page on each
+  side, loaded and settled as the page is; the steps taken in order, the
+  network quiet after each; then settled again (animations finished, the
+  layout the same on two reads), every component measured, its crops (the
+  state's hover steps taken again before each crop: a crop scrolls, the
+  pointer stays), the collateral check of the state. Results are named
+  `<component>@<state>` (`tile@drawer-open`; `collateral@drawer-open`), with
+  `state` in `report.json`. A hover inside a component is measured as the
+  component is: the hovered tile's parts as they show then (the gallery's
+  second image, a revealed button).
+- **A step that cannot be taken** (its element missing, a click that never
+  lands) ends the state's steps on that side and is CRITICAL (`state@<name>`,
+  `step <n>`: `click .filters-toggle failed on ours`): our template lacks the
+  toggle, or the map's selector is wrong. Its components are compared as far
+  as it got.
+- A component's own `"states": ["hover"]` (its first instance hovered) stays
+  as before.
+
+## The collateral check
+
+Everything outside our components must look like their page without us: no
+widget of theirs removed, no header moved, no block collapsed, no layout
+shift of ours. On each page and state, their page without us (their side as
+loaded; for our page against another page of theirs, their page at our path,
+loaded without us) is compared with ours, outside the regions of our
+components (`parity/probe.mjs` `blocksOf`, `compare.mjs` `compareCollateral`):
+
+- **The blocks.** From the body down, only into the ancestors of a region
+  (our components' roots, Luma's own elements, the map's `hide` and
+  `collateral.ignore`), every element beside them is a block: their header,
+  a breadcrumb, a sidebar, a banner, the footer. A block is named by its path
+  (tag, id, classes; Luma's `lbx-` classes aside; `:2` for the second alike
+  sibling): `header.site-header`, `div.content > aside.promo`.
+- **Presence**: a block of theirs missing in ours (hidden, removed) is
+  CRITICAL, and so is a direct child of one (`header.site-header > nav.menu`);
+  a block only in ours (outside our components) MAJOR. A container of theirs
+  that held their components (their listing's column) may be gone in ours
+  (ours replaced it): what was in it is not compared.
+- **Boxes**: a block's x, width and height (a collapsed block), and its y
+  when it lies above our components (their header, moved by an insert of
+  ours); below them a block moves with our components' height, which their
+  own checks compare. MAJOR beyond the px tolerance (MINOR up to 1 px).
+- **Pixels**: each block both sides show at one size, cropped and diffed
+  (masked by construction: our regions are no block). MINOR, a second
+  signal.
+- **Layout shift**: the shifts (the Layout Instability API, as CLS counts
+  them) of their elements above our components during the load, theirs
+  without us against ours: what our render moved after their page painted.
+  Ours more than `collateral.cls` (default 0.02) over theirs: MAJOR, with the
+  elements that moved. (Shifts below our components follow our listing's
+  height while it renders, which varies by timing: they are left out so a run
+  stays repeatable.)
+
+### The layout around the listing
+
+Their page without us can have the same hole as ours. Why: suppose a shop's
+own search is disabled and our listing sits in their search page's layout
+with an element of theirs right after it (say a `div.below-listing`) that is
+empty but kept tall by a `min-height` the theme keeps (and padding): a few
+hundred px of nothing between our grid and their footer. Their search page without
+us has the same empty element, so the check above reports nothing. So
+(`parity/probe.mjs` `aroundOf`, `compare.mjs` `compareAround`):
+
+- **The listing** is the union of the boxes our components' roots show (the
+  map's components on the page, and Luma's `lbx-search` / `lbx-plp`, with
+  their pager or "show more"); on their side, their components' roots. Map
+  their pagination (it is mandatory) so their listing ends where theirs does.
+- **The gaps.** Below: from the listing's bottom to the top of the next
+  element of theirs that renders something (its own text, an image or a
+  control, a background, a border, a shadow, a pseudo-element's content; not
+  `position: fixed`): the next block, else the footer. Above: from the
+  bottom of the nearest such element above it (the heading, a toolbar) to
+  its top. Nothing in our regions, nothing of Luma's, nothing in `hide` or
+  `collateral.ignore` counts.
+- **Against their listing page.** When a page's `theirs` path is another than
+  `ours` (our search against their category listing), the design source of
+  the layout around the listing is their listing page: each gap of ours is
+  compared with the same gap there. Off by more than `collateral.gap` (default
+  4 px) MAJOR, by more than 100 px CRITICAL, as `listing` `gap-below` /
+  `gap-above`. The hint names the element of ours that fills the gap, with
+  its spacing (`div.page > div.below-listing fills it on our page
+  (min-height: 200px; padding-top: 20px; padding-bottom: 20px; height:
+  240px): hide it there, or reset its min-height and padding`), else the
+  margin to change; `responsible` in `report.json` holds the same. A page
+  with one path has no other listing page: its gaps are not compared (their
+  page as loaded is the design, and its blocks are compared above).
+- **Empty space, on any page.** An element of theirs between our listing and
+  what follows it that renders nothing (no visible text, nothing in it that
+  paints) yet takes more than 100 px is MAJOR (`empty-space`, named by its
+  block path), with its `min-height`, padding and height in the hint. Not
+  when their reference page (their listing page, or on one path their page
+  as it is) has the same element as tall: then it is their design.
+- **In the report**, the collateral result's `layout` (both sides: the
+  listing's box, each gap and the element that bounds it, the empty
+  elements), every run; a product decision on one is `collateral.listing` or
+  `collateral.<block path>`.
+
+The result is the page's `collateral` component (its score counts in the
+template score), each difference with its fix hint (a style of ours that
+leaks, a script of ours moving or hiding their element). `"collateral":
+false` turns it off; `collateral.ignore` lists what differs by nature;
+`--only` runs it when `collateral` is named. A difference accepted by design
+is a decision (`excluded`: `"collateral.<block path>"`).
+
+## Behaviour: what an interactive element does
+
+An element can look identical and do nothing (e.g. a link that sends another
+product's id, such as `/wishlist/add?id=<id>`): a port can score at its
+target with it, since nothing visual shows it. So the map declares **interactions** per part (or on a
+component), and parity takes each one on both sides, for the same paired
+product, and compares what it did (`parity/behaviour.mjs`; the engine's
+`behaviourOn`, `act`).
+
+```json
+"components": {
+  "tile": { "theirs": ".listing .tile", "ours": "lbx-plp [data-lbx-part~=\"tile\"]", "each": { "key": "data-product-id" },
+            "parts": {
+              "compare": { "theirs": ".tile__compare", "ours": "[data-lbx-part~=\"compare\"]",
+                           "interact": { "watch": { "compare": ".header .compare-count" } } },
+              "addToCart": { "theirs": ".tile__cart", "interact": true },
+              "wishlist": { "theirs": ".tile__heart", "interact": { "action": "click", "safe": false, "watch": ".wishlist-count" } } } },
+  "sort": { "theirs": "select.sort", "interact": { "action": "select", "option": { "theirs": "Price: low to high", "ours": "Price ascending" } } },
+  "facets": { "theirs": ".filters", "parts": { "facetValue": { "theirs": ".filter label", "interact": "check" } } }
+},
+"behaviour": { "viewport": 1440, "scan": true }
+```
+
+- **`interact`**: `true` (a click), an action (`click`, `tap`, `check`,
+  `select`), `{ … }`, or a list of them. `watch`: a selector, a list, or
+  `{ "<name>": <selector> | { "theirs", "ours" } }`: the state read before
+  and after (how many match, the first one's text, its checked state:
+  a checkbox, `aria-checked`, `aria-pressed`; its value). `option`
+  (`select`): the option by its label or value, or its index (default the
+  first one not selected). `safe` (below). `viewport`: the widths it runs at
+  (default the map's `behaviour.viewport`, else the widest of the run; on a
+  phone width a click is a tap). `wait`: ms after the action (default 500).
+- **The same product.** The interaction acts in the instance that shows the
+  paired product (their first compared tile's key, on both sides), on the
+  part, on the control in it (a label's checkbox, a wrapper's select).
+- **The outcome**, recorded on each side in a fresh page of its own context
+  (its own cookies and storage, and its own recording scope): the
+  **navigation** (none; a reload; another page, by its path pattern; the
+  document it asked for first when it was redirected back: `reload via
+  /wishlist/add?id={id}`; a navigation on the page's own path by the params it
+  changed: `(this page) +brand`, a full load and an in-place update alike;
+  whether the page was loaded again is reported); the **requests** of the
+  action to the shop (its host and subdomains; Luma's API, trackers and
+  prefetches aside), by method and path pattern, with the product's ids in
+  the URL or the body; the **watches**; the target's own checked state; the
+  DOM changes without a navigation; what the page threw.
+- **Patterns and ids.** The product's ids are their key, the catalog
+  record's values, the ids on the instance (its data attributes), and each
+  one's last segment (`product/42` is `42` too). In a URL such a value is
+  `{id}`, another number `{n}`: `/wishlist/add?id={id}` against
+  `/wishlist/add?id={n}`. When both sides carry an id of the product, it must be
+  the same one.
+- **Severities.** An element that has an effect on theirs and none on ours,
+  or that errs on ours (missing, the action never lands, its request fails,
+  the page throws), is **CRITICAL** (`effect`, `error`). An effect is another
+  page, a watched state that changes, a request recorded instead of sent, or
+  DOM changes without a navigation: a reload that changes nothing watched is
+  none (e.g. a link that sends another product's id). An outcome that differs is **MAJOR**
+  (`navigation`, `request`, `watch-<name>`, `checked`). Theirs erring too
+  (their script throws in this browser) is not compared.
+- **Our controls without a counterpart** (`behaviour.scan`, default on; in
+  the components that declare interactions): the links, buttons, checkboxes,
+  radios and selects of our instance that are none of the mapped parts theirs
+  has, hold none and are in none, each clicked with nothing let through. One
+  that does nothing is **CRITICAL** (`<component>.extra dead`).
+- **Results**: the page's `behaviour` component (its score counts in the
+  template score), each difference named `<component>.<part>` with both
+  sides' selectors and both outcomes in words; `report.json` `interactions`
+  holds the outcomes. A decision is `"behaviour.tile.compare"` (with a
+  property: `"behaviour.tile.compare effect"`).
+
+### Safety: real actions on a live site
+
+- **Never let through**, whatever the map says: checkout, payment, login,
+  account and order pages (their path: `checkout`, `payment`, `pay`, `login`,
+  `signin`, `register`, `account`, `password`, `order`, and local words:
+  `kasse`, `pokladna`, `afrekenen`, …) and payment providers (Stripe, PayPal,
+  Adyen, Mollie, Klarna, GoPay, …): aborted, and an effect.
+- **`"safe": false`**: every request of the action is recorded, then aborted
+  (compared, never sent). **Unset** (the default): a POST (any method but
+  GET) to a cart, a compare list or a wishlist (`cart`, `basket`, `compare`,
+  `wishlist`, `favourites`, `winkelwagen`, `vergelijk`, `košík`, …) is only
+  recorded; the rest goes through. **`"safe": true`**: it goes through.
+- Our controls without a counterpart are probed with nothing let through.
+
+### What replays, what needs the live site
+
+Interactions are recorded like everything else (`--record`), each page under
+its own scope (`[<side>:<page>:<interaction>] <key>`, the n-th answer of one
+URL as `~n`: the listing before the click and after it), and replayed from
+there, so `yarn luma parity` repeats them offline, the same every run. A request
+recorded instead of sent never reaches the site in any mode. What needs the
+live site: an interaction's first recording (`--record`; `--live` takes it
+every run), a `"safe": true` action (it changes their shop, in a context of
+its own), and anything the shop answers by session state a recording cannot
+key (a cart rendered from a cookie on another URL). An action's request the
+recording lacks is aborted and noted (re-record). With `--profile` the
+interactions share its one context (noted).
+
+## Alignment: the edges components share
+
+Each component's box is compared relative to itself, so ours can match theirs
+element by element and still not line up. Why: alignment is a relation
+between components (a sort dropdown right-aligned with the product grid),
+which no comparison of one box shows (`parity/alignment.mjs`).
+
+- **From their page**, as loaded and in each state: the boxes of every
+  component (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; every pair of two components whose left, right, top or bottom
+  edges are equal within `alignment.px` (default 1), or that are centred on one
+  another: `sort.right = grid.right`, `toolbar.left = grid.left`.
+- **On ours** the same relations are required: one broken is **MAJOR**
+  (`alignment`, part `grid~sort`, prop `align-right`), naming both elements
+  and the offset (`grid.right is 40px right of sort.right`).
+- **The search field.** Their visible search field is the wrapper that
+  draws it (the outermost element close around the input with a border, a
+  background or a shadow), not the inset input: `search.field` (the input's
+  selector), else the page's typing input. On a page that types, our
+  autocomplete panel's left edge is required on their visible field's left
+  edge **even with no panel of theirs** (`ac-panel` excluded with a decision:
+  our house design still aligns with their field), unless their own panel
+  says otherwise. Luma aligns its dropdown with the visible field
+  (`autocomplete.alignTo`, `fieldOf` in `src/widgets/autocomplete/index.ts`).
+- `alignment: { "px": 1, "ignore": ["grid~sort align-right", "count~facets"] }`
+  (each pair named in alphabetical order) leaves relations out; `"alignment": false` turns it off; a decision is
+  `"alignment.grid~sort align-right"`.
+
+## Parts of parts
+
+A part theirs has can hold controls ours lacks. Why: a price filter can have
+a slider and two inputs on one side and only the inputs on the other; the
+part is on both sides, and comparing parts alone says no control is missing.
+
+- **Declared**: a part's own `parts`, flattened as `<part>.<sub-part>`, each
+  selector inside its parent's on its side; a sub-control theirs has and ours
+  lacks is a missing element, **CRITICAL**:
+
+```json
+"facets": { "theirs": ".filters", "parts": {
+  "priceFilter": { "theirs": ".filter--price", "parts": { "slider": ".ui-slider", "min": "input.min", "max": "input.max" } } } }
+```
+
+  Ours, when the map names none: a range filter (sub-parts `slider`, `min`,
+  `max`) is Luma's facet group that holds the range
+  (`[data-lbx-part~="facet-group"]:has([data-lbx-range])`) and its
+  `range-slider`, `range-min`, `range-max` markers
+  (`src/widgets/search/template-search-range-default.ts`, which the fix hint
+  names); any other sub-part its own marker.
+- **Always**: a part's controls by kind (a slider: `input[type=range]`,
+  `role=slider`, jQuery UI's `.ui-slider`, noUiSlider's `.noUi-target`, ion's
+  `.irs`, Luma's `range-slider`; text inputs; selects; checkboxes; radios;
+  buttons). A kind theirs has in a part and ours has none of is **CRITICAL**
+  (`controls`: `missing in ours: slider`). `ignore: ["controls"]` leaves it out.
+- **`--init`** drafts a slider (any of those) and its inputs as `parts` of
+  the filter (`rangeFilter`), and lists to confirm what ours lacks.
+
+## The hold: a reload shows no frame of theirs
+
+Why: with only the integration's build in the page and no early-hold
+snippet, every full page load would show their listing first, unlike
+production. So `yarn luma parity` (every mode: replay,
+`--record`, `--live`, `--dev`) and `yarn luma a11y` put Luma in the page as a
+customer installs it: the generic snippet (`snippet/early-hold.min.js`) first
+in `<head>`, then the build (`parity/hold.mjs`: an init script inserts it as
+`<head>`'s first child when the parser makes `<head>`, before their first
+script and the first paint; no HTML is rewritten, so a recording replays byte
+for byte).
+
+The check (`hold`, per page at its first width, pages that type aside): our
+page loaded once in a context of its own (the build stores its rules), then
+reloaded with every frame recorded (the technique of Luma's browser suites:
+a ResizeObserver on a 1 px probe whose width
+flips every frame, `probe.mjs` `framesInit`). A frame that painted their
+listing (their components' elements outside Luma's) is **CRITICAL**, with the
+frames in order (`frames: none > theirs > ours`) and the hint (the snippet
+missing, or rules that do not hide this route's listing). `"hold": false` (the
+map, or a page) turns it off; a decision is `"hold"`.
+
+## Reading the report
+
+The terminal prints the pages (each one's design source and how their
+products were asked for), the verdict, the template differences to fix, the
+data differences, the decided ones and the coverage first ("The convergence loop"), then a scorecard
+(components x viewports: the template score, `/overall` when the data's
+differences lower it), then per component and width every difference out of
+tolerance (`DATA` marks the data's). Each shows their value and ours, whole,
+and how many of the compared instances have it. The same difference on every
+tile is one finding. A score is 100 x (1 - the failed checks' weight / all
+checks' weight): a property weighs 1, a missing element, a text or a column
+count 5, the pixel share 2; the template score leaves the data's differences
+out. States are rows of their own (`tile@drawer-open`), and so are the
+collateral check (`collateral`), a failed pairing (`pairing`) and a state's
+steps that failed (`state@<name>`). `report.json` holds the same and the alignment. `index.html` adds the
+crops side by side, with the diff image.
+
+## Where it lives
+
+| | |
+|---|---|
+| `parity/run.mjs`, `args.mjs` | the command: options (`args.mjs`), build, browser, the driver (routes, the bundle, the recording), the integration's files for the hints |
+| `parity/engine.mjs` | per page and width (a phone width as a phone: `deviceOf`): theirs, then ours with their products; measure, pair (with the catalog's records; a failed pairing CRITICAL), the collateral blocks, crop, compare; the alignment (`alignItems`); the hold check (`holdCheck`: a reload's frames); the interactions (`behaviourOn`, `act`: each side in a context of its own, the safety route) and our controls without a counterpart; then every state (its steps per side, measured again); `conclude` (verdict, fix list, data list, decided, coverage) |
+| `parity/probe.mjs` | in the page: alignment (by id, with queries; the catalog's records shown), settling, ids, measuring (with consecutive siblings), their heading and titles, storage (set, and the keys read), layout shifts, the collateral blocks, the layout around the listing (`aroundOf`: the gaps, what fills them, empty space), a part's controls, the boxes the alignment compares (`edgesOf`, their visible search field), the frames of a reload (`framesInit`), an interaction's target, watches and DOM changes (`targetOf`, `readWatches`, `mutationsInit`), our controls without a counterpart (`strayControls`) |
+| `parity/behaviour.mjs` | an interaction's outcome (patterns, the product's ids, the effect), theirs against ours, our controls without a counterpart, the safety rules (`NEVER`, `UNSAFE`, `fateOf`), the hold's result (pure) |
+| `parity/alignment.mjs` | the edges their components share, required of ours (pure) |
+| `parity/hold.mjs` | Luma in a page as a customer installs it: the early-hold snippet first in `<head>`, then the build (`yarn luma parity`, `yarn luma a11y`) |
+| `parity/pairing.mjs` | the id requests' queries, the pairing's failure (pure) |
+| `parity/compare.mjs` | the comparison, severities, scores (template and overall), sibling layout, the collateral check, the pairing's and the states' results, the ranked findings, the verdict (pure) |
+| `parity/owner.mjs` | who owns a difference: the template, the data, or a recorded product decision (pure) |
+| `parity/hints.mjs` | where to fix a template difference: the integration file, from our side's selector (pure) |
+| `parity/map.mjs` | the map (states and their steps, storage, queries, phone, collateral, decisions), roles, `MANDATORY` and the coverage, `GAPS`, `BLOCK_LUIGIS`, `LEGACY_MARKUP` |
+| `parity/archive.mjs`, `pixels.mjs`, `report.mjs`, `init.mjs` | record/replay (an interaction's page under its own scope), the pixel diff, the reports, `--init` |