@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/report.mjs

@@ -0,0 +1,236 @@
+// The reports of `yarn luma parity`: the terminal's (a scorecard, then per
+// component and viewport the differences out of tolerance, theirs against
+// ours, whole values), the HTML page (the same, with the crops side by side
+// and the diff image) and the JSON. Pure functions (writeDeep aside), unit-tested.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { formatQueries } from './pairing.mjs';
+
+/** Writes a report file, its folder made first (`--json out/parity.json` with no out/ yet). @param {string} file @param {string} text */
+export const writeDeep = (file, text) => {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, text);
+};
+
+const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const show = (v) => (typeof v === 'string' ? (v === '' ? '""' : v) : JSON.stringify(v));
+
+/** The run as the JSON report holds it: `results` alone decides (two runs of one recording give the same `results`). */
+export const toJson = (run, meta = {}) => ({
+  meta,
+  verdict: run.verdict,
+  todo: run.todo ?? [],
+  data: run.data ?? [],
+  decided: run.decided ?? [],
+  coverage: run.coverage ?? null,
+  pages: run.pages ?? [],
+  results: run.results,
+  aligned: run.aligned,
+  notes: run.notes,
+  stopped: run.stopped ?? null,
+});
+
+const SEV = { critical: 'CRITICAL', major: 'MAJOR', minor: 'minor' };
+
+/**
+ * Per page, which of their pages it was compared against (the design
+ * source): the same page, or another (our search against their category
+ * listing), and whether their products were paired with ours.
+ * @param {{ page: string, theirs: string, ours: string, cross: boolean, paired: boolean }[]} pages
+ */
+export const formatPages = (pages = []) =>
+  pages.map((p) =>
+    p.cross
+      ? `${p.page}: ours ${p.ours} against theirs ${p.theirs} (another page of theirs, the design source; ${p.paired ? 'their products paired with ours, the other texts by shape' : 'not paired: by structure only'})`
+      : `${p.page}: ${p.ours} on both sides${p.paired ? '' : ' (not paired)'}`,
+  );
+/**
+ * Per page, how their products were asked for (the queries tried, each with
+ * what it found: parity/pairing.mjs), from its first viewport.
+ * @param {{ page: string, ids: number, requests: { found: number, asked: number, queries?: any[] }[] }[]} aligned
+ */
+export const formatPairing = (aligned = []) => {
+  const seen = new Set();
+  const out = [];
+  for (const a of aligned ?? []) {
+    if (seen.has(a.page)) continue;
+    seen.add(a.page);
+    const best = (a.requests ?? []).reduce((x, y) => (!x || y.found > x.found ? y : x), null);
+    out.push(best ? `${a.page}: their ${a.ids} products by id, ${best.found} paired${best.queries?.length ? `, asked with ${formatQueries(best.queries)}` : ''}` : `${a.page}: their ${a.ids} products, no request of ours to pair them with`);
+  }
+  return out;
+};
+const at = (f) => `${f.viewports.map((v) => `${v}px`).join(', ')}`;
+
+/**
+ * The top of the terminal report: the verdict, then the template's
+ * differences ranked (each with its selectors, both values and where to fix
+ * it), the data's for the client, the coverage. An agent fixes from this
+ * alone and runs again until it says CONVERGED.
+ * @param {any} run @param {{ color?: boolean, top?: number }} opts
+ */
+export const formatVerdict = (run, opts = {}) => {
+  const c = (code, s) => (opts.color ? `\x1b[${code}m${s}\x1b[0m` : s);
+  const v = run.verdict;
+  const out = [];
+  const cov = run.coverage;
+  const covLine = cov ? `coverage ${cov.items.filter((i) => i.status === 'mapped').length} mapped, ${cov.items.filter((i) => i.status === 'excluded').length} excluded, ${cov.missing.length} missing of ${cov.items.length}` : '';
+  const scores = v.templateScore == null ? 'nothing measured' : `template ${v.templateScore.toFixed(1)} (target ${v.target}), overall ${v.overall.toFixed(1)}`;
+  out.push(v.converged ? c('32;1', `CONVERGED: ${scores}; ${covLine}`) : c('31;1', `NOT CONVERGED: ${scores}; ${v.blocking ?? 0} CRITICAL/MAJOR template differences; ${covLine}`));
+  for (const r of v.converged ? [] : (v.reasons ?? [])) out.push(`  - ${r}`);
+  const todo = run.todo ?? [];
+  const blocking = todo.filter((f) => f.severity !== 'minor');
+  const minor = todo.filter((f) => f.severity === 'minor');
+  const shownMinor = opts.top ? minor.slice(0, opts.top) : minor;
+  if (todo.length) {
+    out.push('', c('1', `TEMPLATE DIFFERENCES (yours to fix), by weight: ${blocking.length} CRITICAL/MAJOR, ${minor.length} minor`));
+    [...blocking, ...shownMinor].forEach((f, i) => {
+      const sev = f.severity === 'critical' ? c('31', SEV[f.severity]) : f.severity === 'major' ? c('33', SEV[f.severity]) : SEV[f.severity];
+      out.push(`${String(i + 1).padStart(3)}. ${sev} ${f.component}${f.part === 'root' ? '' : `.${f.part}`} ${f.prop}${f.also ? ` (and ${f.also.join(', ')}: currentColor)` : ''}: ${f.delta} (on ${f.page} at ${at(f)}; ${f.count} instance${f.count > 1 ? 's' : ''}, weight ${f.total})`);
+      if (f.selector) out.push(`       selector: theirs ${f.selector.theirs ?? '-'} | ours ${f.selector.ours ?? '-'}`);
+      out.push(`       theirs: ${show(f.theirs)}`);
+      out.push(`       ours:   ${show(f.ours)}`);
+      if (f.fix?.hint) out.push(`       fix:    ${f.fix.hint}`);
+    });
+    if (shownMinor.length < minor.length) out.push(`     … ${minor.length - shownMinor.length} more minor (--all, or report.json "todo")`);
+  }
+  const data = run.data ?? [];
+  if (data.length) {
+    out.push('', c('1', `DATA DIFFERENCES (the catalog's or the API's, for the client): ${data.length}`));
+    for (const f of opts.top ? data.slice(0, opts.top * 2) : data) {
+      const ev = f.evidence ? `; the catalog's ${f.evidence.field}: ${JSON.stringify(f.evidence.catalog)}` : '';
+      out.push(`  - ${f.component}${f.part === 'root' ? '' : `.${f.part}`} ${f.prop} (on ${f.page} at ${at(f)}): theirs ${show(f.theirs)}, ours ${show(f.ours)}${ev}${f.why && !f.evidence ? `; ${f.why}` : ''}`);
+    }
+    if (opts.top && data.length > opts.top * 2) out.push(`  … ${data.length - opts.top * 2} more (--all, or report.json "data")`);
+  }
+  const decided = run.decided ?? [];
+  if (decided.length) {
+    out.push('', c('1', `DECIDED (recorded product decisions, "excluded" with a "decision"; not the template's): ${decided.length}`));
+    for (const f of opts.top ? decided.slice(0, opts.top) : decided) out.push(`  - ${f.component}${f.part === 'root' ? '' : `.${f.part}`} ${f.prop} (on ${f.page} at ${at(f)}): theirs ${show(f.theirs)}, ours ${show(f.ours)}; ${f.why ?? ''}${f.decision ? ` [${f.decision}]` : ''}`);
+  }
+  if (cov) {
+    out.push('', c('1', `COVERAGE (mandatory components, docs/PARITY.md): ${covLine}`));
+    for (const i of cov.items) out.push(`  ${i.status === 'missing' ? c('31', 'MISSING ') : i.status === 'excluded' ? 'excluded' : 'mapped  '} ${i.id.padEnd(16)} ${i.status === 'mapped' ? i.by : i.status === 'excluded' ? `${i.reason}${i.decision ? ` (decision: ${[i.decision.decision, i.decision.by, i.decision.date].filter(Boolean).join(', ')})` : ''}` : 'map it (a component, or a part of one), or list it in "excluded" with a reason'}`);
+  }
+  return out.join('\n');
+};
+
+/** Components x viewports: the score of each. */
+export const scorecard = (results) => {
+  const widths = [...new Set(results.map((r) => r.viewport))].sort((a, b) => a - b);
+  const rows = new Map();
+  for (const r of results) {
+    const k = `${r.component} (${r.page})`;
+    if (!rows.has(k)) rows.set(k, {});
+    rows.get(k)[r.viewport] = r;
+  }
+  // `scores`: the overall score; `template`: the template's (the data's differences count as passed).
+  return { widths, rows: [...rows.entries()].map(([name, by]) => ({ name, scores: widths.map((w) => by[w]?.score ?? null), template: widths.map((w) => by[w]?.templateScore ?? by[w]?.score ?? null) })) };
+};
+
+/**
+ * @param {{ results: any[], verdict: any, aligned: any[], notes: string[], stopped?: string | null }} run
+ * @param {{ color?: boolean, top?: number, title?: string, meta?: string[], thresholds?: any }} opts
+ */
+export const formatText = (run, opts = {}) => {
+  const c = (code, s) => (opts.color ? `\x1b[${code}m${s}\x1b[0m` : s);
+  const out = [];
+  out.push(c('1', opts.title ?? 'yarn luma parity'));
+  for (const m of opts.meta ?? []) out.push(`  ${m}`);
+  const pages = formatPages(run.pages);
+  if (pages.length) out.push('', c('1', 'PAGES (ours, and the page of theirs it is compared against)'), ...pages.map((p) => `  ${p}`));
+  out.push(...formatPairing(run.aligned).map((p) => `  ${p}`));
+  if (run.stopped) out.push(c('31', `STOPPED: ${run.stopped}`));
+  out.push('', formatVerdict(run, opts), '', c('1', 'DETAILS (every component and viewport; template and overall scores)'));
+  const { widths, rows } = scorecard(run.results);
+  if (rows.length) {
+    const w0 = Math.max(9, ...rows.map((r) => r.name.length));
+    const cell = (t, o) => (t == null ? '-' : t === o || o == null ? t.toFixed(1) : `${t.toFixed(1)}/${o.toFixed(1)}`);
+    out.push('', `${'component'.padEnd(w0)}  ${widths.map((w) => `${w}px`.padStart(12)).join('')}   (the template score; /overall when the data's differences lower it)`);
+    for (const r of rows) out.push(`${r.name.padEnd(w0)}  ${r.template.map((t, i) => cell(t, r.scores[i]).padStart(12)).join('')}`);
+  }
+  for (const r of run.results) {
+    const th = opts.thresholds?.components?.[r.component] ?? opts.thresholds?.score ?? 0;
+    const ts = r.templateScore ?? r.score;
+    const pg = (run.pages ?? []).find((x) => x.page === r.page);
+    const head = `${r.component} on ${r.page}${pg?.cross ? ` (against their ${pg.theirs})` : ''} at ${r.viewport}px: ${r.score == null ? 'not found on either side' : ts === r.score ? r.score.toFixed(1) : `template ${ts.toFixed(1)}, overall ${r.score.toFixed(1)}`}`;
+    const found = r.found ? ` (theirs ${r.found.theirs}, ours ${r.found.ours}, compared ${r.instances.length})` : '';
+    out.push('', `${ts != null && ts < th ? c('31', head) : c('1', head)}${found}`);
+    if (!r.instances.length) out.push('  nothing to compare: the component is not on one of the pages');
+    const list = opts.top ? r.diffs.slice(0, opts.top) : r.diffs;
+    for (const d of list) {
+      const sev = `${d.owner === 'data' ? 'DATA ' : ''}${d.severity === 'critical' ? c('31', 'CRITICAL ') : d.severity === 'minor' ? 'minor ' : ''}`;
+      const n = r.instances.length > 1 ? ` (${d.count} of ${r.instances.length})` : '';
+      out.push(`  ${sev}${d.part} ${d.prop}: ${d.delta}${n}`);
+      out.push(`    theirs: ${show(d.theirs)}`);
+      out.push(`    ours:   ${show(d.ours)}`);
+    }
+    if (opts.top && r.diffs.length > opts.top) out.push(`  … ${r.diffs.length - opts.top} more (--all, or the HTML/JSON report)`);
+  }
+  for (const a of run.aligned ?? [])
+    for (const q of a.requests ?? [])
+      if (q.missing?.length) out.push('', c('33', `${a.page} ${a.viewport}px: ${q.missing.length} of ${q.asked} of their products not found by the API (${q.endpoint}${q.queries?.length ? `; asked with ${formatQueries(q.queries)}` : ''}): ${q.missing.join(', ')}`));
+  if (run.notes?.length) out.push('', ...run.notes.map((n) => c('33', `note: ${n}`)));
+  const v = run.verdict;
+  const conv = v.converged == null ? '' : v.converged ? c('32', '; CONVERGED') : c('31', '; NOT CONVERGED (the top of this report says what is left)');
+  out.push('', v.overall == null ? 'Nothing was measured.' : `${v.templateScore != null ? `Template ${v.templateScore.toFixed(1)} (target ${v.target}), overall` : 'Overall'} ${v.overall.toFixed(1)}; ${v.failing.length ? c('31', `${v.failing.length} under threshold: ${v.failing.map((f) => `${f.component}@${f.viewport} ${f.score} < ${f.threshold}`).join(', ')}`) : c('32', 'every component at or over its threshold')}${conv}`);
+  return out.join('\n');
+};
+
+/** The HTML report: scorecard, then per component and viewport the differences and the crops (theirs, ours, diff). */
+export const formatHtml = (run, opts = {}) => {
+  const { widths, rows } = scorecard(run.results);
+  const cls = (s, th) => (s == null ? '' : s >= th ? 'ok' : 'bad');
+  const th = (comp) => opts.thresholds?.components?.[comp] ?? opts.thresholds?.score ?? 0;
+  const sections = run.results
+    .map((r) => {
+      const diffs = r.diffs
+        .map((d) => `<tr class="${d.severity}"><td>${esc(d.owner ?? 'template')}</td><td>${esc(d.part)}</td><td>${esc(d.prop)}</td><td><code>${esc(show(d.theirs))}</code></td><td><code>${esc(show(d.ours))}</code></td><td>${esc(d.delta)}</td><td>${d.count}/${r.instances.length}</td></tr>`)
+        .join('');
+      const crops = r.instances
+        .filter((i) => i.pixels?.images)
+        .map((i) => `<figure><figcaption>${esc(i.key)} · ${i.score == null ? '-' : i.score.toFixed(1)} · ${(i.pixels.ratio * 100).toFixed(2)}% pixels differ</figcaption><div class="crops"><img src="${esc(i.pixels.images.theirs)}" alt="theirs"><img src="${esc(i.pixels.images.ours)}" alt="ours"><img src="${esc(i.pixels.images.diff)}" alt="diff"></div></figure>`)
+        .join('');
+      const ts = r.templateScore ?? r.score;
+      return `<section><h2 class="${cls(ts, th(r.component))}">${esc(r.component)} on ${esc(r.page)}${r.against ? ` (theirs ${esc(r.against)})` : ''} at ${r.viewport}px: ${r.score == null ? 'not found on either side' : `template ${ts.toFixed(1)}, overall ${r.score.toFixed(1)}`}</h2>
+${diffs ? `<table><thead><tr><th>owner</th><th>part</th><th>property</th><th>theirs</th><th>ours</th><th>difference</th><th>instances</th></tr></thead><tbody>${diffs}</tbody></table>` : '<p class="ok">No difference out of tolerance.</p>'}
+${crops ? `<p class="legend">theirs · ours · diff</p>${crops}` : ''}</section>`;
+    })
+    .join('\n');
+  const card = `<table class="card"><thead><tr><th>component</th>${widths.map((w) => `<th>${w}px</th>`).join('')}</tr></thead><tbody>${rows
+    .map((r) => `<tr><td>${esc(r.name)}</td>${r.template.map((s, i) => `<td class="${cls(s, th(r.name.replace(/ \(.*$/, '')))}">${s == null ? '-' : s.toFixed(1)}${r.scores[i] != null && r.scores[i] !== s ? ` <small>/ ${r.scores[i].toFixed(1)}</small>` : ''}</td>`).join('')}</tr>`)
+    .join('')}</tbody></table>`;
+  const v = run.verdict;
+  const todo = (run.todo ?? [])
+    .map((f, i) => `<tr class="${f.severity}"><td>${i + 1}</td><td>${esc(f.severity)}</td><td>${esc(f.component)}${f.part === 'root' ? '' : `.${esc(f.part)}`}</td><td>${esc(f.prop)}</td><td><code>${esc(f.selector?.theirs ?? '')}</code><br><code>${esc(f.selector?.ours ?? '')}</code></td><td><code>${esc(show(f.theirs))}</code></td><td><code>${esc(show(f.ours))}</code></td><td>${esc(f.fix?.hint ?? '')}</td><td>${f.viewports.join(', ')}</td><td>${f.total}</td></tr>`)
+    .join('');
+  const data = (run.data ?? []).map((f) => `<tr><td>${esc(f.component)}${f.part === 'root' ? '' : `.${esc(f.part)}`}</td><td>${esc(f.prop)}</td><td><code>${esc(show(f.theirs))}</code></td><td><code>${esc(show(f.ours))}</code></td><td>${esc(f.evidence ? `the catalog's ${f.evidence.field}: ${JSON.stringify(f.evidence.catalog)}` : (f.why ?? ''))}</td><td>${f.viewports.join(', ')}</td></tr>`).join('');
+  const cov = run.coverage ? run.coverage.items.map((i) => `<tr class="${i.status === 'missing' ? 'critical' : ''}"><td>${esc(i.id)}</td><td>${esc(i.status)}</td><td>${esc(i.by ?? i.reason ?? 'map it, or list it in "excluded" with a reason')}</td></tr>`).join('') : '';
+  const top = `<p><strong class="${v.converged ? 'ok' : 'bad'}">${v.converged ? 'Converged' : 'Not converged'}</strong> · template ${v.templateScore == null ? '-' : v.templateScore.toFixed(1)} (target ${v.target ?? '-'}) · overall ${v.overall == null ? '-' : v.overall.toFixed(1)}</p>${(v.reasons ?? []).length && !v.converged ? `<ul>${v.reasons.map((x) => `<li>${esc(x)}</li>`).join('')}</ul>` : ''}
+${todo ? `<h2>Template differences (to fix), by weight</h2><table><thead><tr><th>#</th><th>severity</th><th>where</th><th>property</th><th>selector (theirs, ours)</th><th>theirs</th><th>ours</th><th>fix</th><th>viewports</th><th>weight</th></tr></thead><tbody>${todo}</tbody></table>` : ''}
+${data ? `<h2>Data differences (for the client)</h2><table><thead><tr><th>where</th><th>property</th><th>theirs</th><th>ours</th><th>evidence</th><th>viewports</th></tr></thead><tbody>${data}</tbody></table>` : ''}
+${cov ? `<h2>Coverage</h2><table><tbody>${cov}</tbody></table>` : ''}`;
+  const notes = [...(run.stopped ? [`STOPPED: ${run.stopped}`] : []), ...(run.notes ?? [])].map((n) => `<li>${esc(n)}</li>`).join('');
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Parity report</title>
+<style>
+:root { --bg: #fff; --fg: #1d1d1f; --muted: #6b6b70; --line: #e3e3e8; --ok: #0a7a3a; --bad: #b3261e; --crit: #fdecea; }
+@media (prefers-color-scheme: dark) { :root { --bg: #161618; --fg: #ececf0; --muted: #a0a0a8; --line: #33333a; --ok: #5fd08a; --bad: #ff7b72; --crit: #3a1d1b; } }
+body { background: var(--bg); color: var(--fg); font: 14px/1.45 system-ui, sans-serif; margin: 0 auto; padding: 16px; max-width: 1400px; }
+h1 { font-size: 20px; } h2 { font-size: 16px; margin-top: 32px; } .ok { color: var(--ok); } .bad { color: var(--bad); }
+table { border-collapse: collapse; width: 100%; margin: 8px 0; } th, td { border-bottom: 1px solid var(--line); padding: 4px 8px; text-align: left; vertical-align: top; }
+td code { white-space: pre-wrap; word-break: break-all; } tr.critical td { background: var(--crit); } .card td:not(:first-child), .card th:not(:first-child) { text-align: right; }
+.meta, .legend, figcaption { color: var(--muted); } .crops { display: flex; gap: 8px; align-items: flex-start; overflow-x: auto; } .crops img { border: 1px solid var(--line); max-width: 32%; height: auto; }
+figure { margin: 12px 0; }
+</style></head><body>
+<h1>${esc(opts.title ?? 'Parity report')}</h1>
+<p class="meta">${(opts.meta ?? []).map(esc).join('<br>')}</p>
+${(run.pages ?? []).length ? `<h2>Pages (ours, and the page of theirs it is compared against)</h2><ul>${formatPages(run.pages).map((p) => `<li>${esc(p)}</li>`).join('')}</ul>` : ''}
+${top}
+<h2>Scores</h2>
+<p><strong>Overall ${run.verdict.overall == null ? '-' : run.verdict.overall.toFixed(1)}</strong>${run.verdict.failing.length ? ` · <span class="bad">${run.verdict.failing.length} under threshold</span>` : ' · <span class="ok">at or over every threshold</span>'}</p>
+${card}
+${notes ? `<ul>${notes}</ul>` : ''}
+${sections}
+</body></html>
+`;
+};

package/parity/run.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// yarn luma parity: does the integration look exactly like the site it replaces?
+// Run from the integration repository (Luma as the @luigisbox/luma package, or
+// an older luma/ submodule):
+//
+//   yarn luma parity     (the integration's one `luma` script: bin/luma.mjs)
+//   yarn luma parity --record      the live site once into parity/recording/ (pages, assets, API answers)
+//   yarn luma parity               replays the recording: offline, the same numbers every run
+//   yarn luma parity --live        the live site, nothing recorded
+//   yarn luma parity --init        a draft map (integration/parity.draft.json) to confirm
+//
+// For every page and viewport of the map (integration/parity.json,
+// parity/map.mjs), their page and ours (the same page with the build in it,
+// its listing showing the products theirs shows), every mapped component
+// measured property by property and as pixels (parity/engine.mjs), every
+// difference the template's or the data's (parity/owner.mjs). The terminal's
+// top section is the verdict and the template's differences ranked, each
+// with where to fix it: an agent loops on `yarn luma parity --target <n>` until it
+// converges. Exit code: 0 converged (the template score at or over --target,
+// default 98; no CRITICAL or MAJOR template difference; every mandatory
+// component mapped or excluded), 1 not yet, 2 nothing could be compared (or
+// the run broke). docs/PARITY.md.
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, extname, join, normalize as normPath, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LUMA = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const { USAGE, devBundle, parseArgs } = await import('./args.mjs');
+const { TARGET } = await import('./compare.mjs');
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (parsed.error) die(`${parsed.error}\n\n${USAGE}`);
+const opt = parsed.opt;
+
+function die(msg, code = 2) {
+  console.error(msg);
+  process.exit(code);
+}
+
+const SITE_DIR = [opt.siteDir, process.env.LBX_SITE_DIR, process.cwd(), dirname(LUMA)].filter(Boolean).map((d) => resolve(d)).find((d) => existsSync(join(d, 'integration')));
+if (!SITE_DIR) die('No integration found: run yarn luma parity in the integration repository (the folder with integration/), or pass --site-dir.');
+process.env.LBX_SITE_DIR = SITE_DIR;
+
+for (const dep of ['playwright-core', 'pixelmatch', 'pngjs']) {
+  try {
+    await import(dep);
+  } catch {
+    die(`Luma's dependencies are not installed (${dep} is missing): run \`yarn install\`.`);
+  }
+}
+const { chromium } = await import('playwright-core');
+const { BLOCK_LUIGIS, BLOCK_OURS, BLOCK_THEIRS, normalize, recordedPages } = await import('./map.mjs');
+const { Archive } = await import('./archive.mjs');
+const { SNIPPET, holdInit } = await import('./hold.mjs');
+const { runParity } = await import('./engine.mjs');
+const { formatHtml, formatText, toJson, writeDeep } = await import('./report.mjs');
+
+const MAP_FILE = resolve(SITE_DIR, opt.map || 'integration/parity.json');
+let rawMap = null;
+if (existsSync(MAP_FILE)) {
+  try {
+    rawMap = JSON.parse(readFileSync(MAP_FILE, 'utf8'));
+  } catch (e) {
+    die(`${relative(process.cwd(), MAP_FILE)} is not JSON: ${e.message}`);
+  }
+} else if (opt.init == null) die(`No map at ${relative(process.cwd(), MAP_FILE)}: propose one with yarn luma parity --init (docs/PARITY.md).`);
+
+const HOST = opt.host || process.env.LBX_HOST || rawMap?.host;
+if (!HOST) die('No storefront host: "host" in the map, LBX_HOST or --host.');
+const ORIGIN = `https://${HOST}`;
+const ARCHIVE = resolve(SITE_DIR, opt.archive || 'parity/recording');
+const DIST = join(SITE_DIR, 'dist');
+// The dev server (--dev [url|port]): its origin and the integration's entry on it.
+const DEV = opt.dev ? devBundle(opt.dev) : null;
+const BUNDLE_PATH = '/__lbx/parity/';
+const BUNDLE = DEV ? DEV.bundle : `${ORIGIN}${BUNDLE_PATH}luma-integration.js`;
+
+if (!opt.dev && opt.build) {
+  process.stderr.write(`building ${relative(process.cwd(), SITE_DIR) || '.'} (yarn build)… `);
+  try {
+    execFileSync('yarn', ['build'], { cwd: SITE_DIR, stdio: ['ignore', 'pipe', 'pipe'] });
+    process.stderr.write('done\n');
+  } catch (e) {
+    process.stderr.write('failed\n');
+    die(`yarn build failed:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+  }
+}
+if (!opt.dev && !existsSync(join(DIST, 'luma-integration.js'))) die(`${DIST}/luma-integration.js is missing: run yarn build (or drop --no-build).`);
+
+// ------------------------------------------------------------------ the map
+
+let map;
+if (rawMap) {
+  const { map: m, errors } = normalize(rawMap);
+  if (errors.length) die(`${relative(process.cwd(), MAP_FILE)}:\n${errors.map((e) => `  ${e}`).join('\n')}`);
+  map = m;
+  if (opt.viewports) map.viewports = opt.viewports;
+}
+
+// ------------------------------------------------------------------ browser and driver
+
+const TYPES = { '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.map': 'application/json', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
+const mode = opt.init != null && opt.mode === 'replay' && !existsSync(join(ARCHIVE, 'index.json')) ? 'live' : opt.mode;
+const archive = mode === 'live' ? null : new Archive(ARCHIVE, { mode: mode === 'record' ? 'record' : 'replay', merge: opt.only.length > 0, ignore: map?.archive.ignore ?? undefined, skip: (u) => u.startsWith(`${ORIGIN}${BUNDLE_PATH}`) || (!!DEV && u.startsWith(`${DEV.origin}/`)) });
+const locale = map?.locale ?? rawMap?.locale ?? 'en-US';
+const timezoneId = map?.timezone ?? rawMap?.timezone ?? 'UTC';
+const ctxOpts = { viewport: { width: 1440, height: map?.height ?? 900 }, deviceScaleFactor: 1, locale, timezoneId, serviceWorkers: 'block', ignoreHTTPSErrors: !!opt.dev, colorScheme: 'light', reducedMotion: 'no-preference' };
+
+let browser = null;
+let persistent = null;
+let profileCopy = '';
+if (opt.profile) {
+  const src = resolve(opt.profile.replace(/^~(?=\/)/, process.env.HOME ?? '~'));
+  if (!existsSync(src)) die(`--profile ${src}: no such folder (yarn luma chrome keeps one per host under ~/.lbx-chrome/<host>)`);
+  profileCopy = mkdtempSync(join(tmpdir(), 'lbx-parity-profile-'));
+  cpSync(src, profileCopy, { recursive: true, filter: (p) => !/Singleton(Lock|Socket|Cookie)$|\/(Cache|Code Cache|GPUCache|Service Worker)(\/|$)/.test(p) });
+  // Chrome itself (the profile is Chrome's), its real keychain (the profile's cookies are encrypted with it),
+  // always headed (args.mjs: a profile is for a session a person sees).
+  persistent = await chromium.launchPersistentContext(profileCopy, { ...ctxOpts, channel: 'chrome', headless: !opt.headed, ignoreDefaultArgs: ['--use-mock-keychain'] });
+} else {
+  const o = { headless: !opt.headed };
+  for (const t of [...(process.env.LBX_CHROMIUM_PATH ? [{ ...o, executablePath: process.env.LBX_CHROMIUM_PATH }] : []), { ...o, channel: 'chromium' }, { ...o, channel: 'chrome' }]) {
+    try {
+      browser = await chromium.launch(t);
+      break;
+    } catch {}
+  }
+  if (!browser) die('No Chromium to run: install Chrome, or `yarn playwright-core install chromium`, or set LBX_CHROMIUM_PATH.');
+}
+const contexts = {};
+// One context per side and device (a phone width: isMobile, touch, a phone's user agent: engine.mjs deviceOf).
+// A --profile is one context, a desktop's: its phone widths are a narrow desktop window (said in the notes).
+const context = async (side, device = {}) => persistent ?? (contexts[`${side} ${JSON.stringify(device)}`] ??= await browser.newContext({ ...ctxOpts, ...device }));
+let profilePhone = false;
+let profileShared = false;
+
+// The map's blocks (default: Luigi's Box scripts on ours, the platform's loader on theirs), and --block's vendor scripts on both.
+const blocks = (side) => [...(map?.block?.[side] ?? (side === 'ours' ? BLOCK_OURS : BLOCK_THEIRS)), ...opt.block].map((s) => new RegExp(s));
+let lastLoad = 0;
+const driver = {
+  origin: ORIGIN,
+  /** Live: their site's pages at least gapMs apart (both sides load their page). */
+  wait: async () => {
+    if (mode === 'replay') return;
+    const gap = map?.gapMs ?? 2000;
+    const w = lastLoad + gap - Date.now();
+    if (w > 0) await new Promise((r) => setTimeout(r, w));
+    lastLoad = Date.now();
+  },
+  /**
+   * A fresh page on a side. `o.isolated`: in a context of its own (its own cookies and storage: an
+   * interaction's actions never reach the other pages), closed with the page; `o.scope`: its requests
+   * recorded and replayed under that scope (archive.mjs). Ours: Luma as a customer installs it, the
+   * early-hold snippet first in <head>, then the build (parity/hold.mjs; `o.snippet: false` leaves the
+   * snippet out).
+   */
+  page: async (side, o = {}) => {
+    if (persistent && o.device?.isMobile) profilePhone = true;
+    const own = o.isolated && !persistent ? await browser.newContext({ ...ctxOpts, ...(o.device ?? {}) }) : null;
+    if (o.isolated && persistent) profileShared = true;
+    const ctx = own ?? (await context(side, o.device ?? {}));
+    const page = await ctx.newPage();
+    if (own) page.once('close', () => own.close().catch(() => {}));
+    if (archive && o.scope) archive.scope(page, o.scope);
+    if (archive) await archive.attach(page);
+    const bl = blocks(side);
+    if (bl.length) await page.route((u) => bl.some((re) => re.test(u.href)), (r) => r.abort('blockedbyclient'));
+    if (side === 'ours') {
+      await page.route(`${ORIGIN}${BUNDLE_PATH}**`, (route) => {
+        const url = new URL(route.request().url());
+        const file = normPath(join(DIST, decodeURIComponent(url.pathname.slice(BUNDLE_PATH.length))));
+        if (!file.startsWith(DIST) || !existsSync(file) || !statSync(file).isFile()) return route.fulfill({ status: 404, body: '' });
+        return route.fulfill({ status: 200, body: readFileSync(file), headers: { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' } });
+      });
+      // As a customer installs it: the early-hold snippet first in <head>, then the build (docs/PARITY.md, "The hold").
+      await page.addInitScript(holdInit, { origin: ORIGIN, bundle: BUNDLE, snippet: o.snippet === false ? '' : SNIPPET });
+    }
+    return page;
+  },
+};
+
+const close = async () => {
+  await archive?.flush();
+  await persistent?.close().catch(() => {});
+  await browser?.close().catch(() => {});
+  if (profileCopy) rmSync(profileCopy, { recursive: true, force: true });
+};
+
+// ------------------------------------------------------------------ --init
+
+if (opt.init != null) {
+  const { initMap, initPages } = await import('./init.mjs');
+  const { loadConfig } = await import('../bin/config.mjs');
+  const F = (await loadConfig(SITE_DIR)).fixtures;
+  const pages = initPages({ paths: opt.paths, category: F.category ?? null, query: F.query ?? null, theirPlp: opt.theirPlp || null, ourSearch: opt.ourSearch || null });
+  const draft = await initMap({ driver, host: HOST, pages: Object.fromEntries(Object.entries(pages).filter(([, p]) => p)), query: F.query ?? 'a', input: F.input ?? rawMap?.input ?? null, block: [...BLOCK_LUIGIS, ...opt.block], log: (s) => process.stderr.write(`${s}\n`) }).finally(close);
+  const file = resolve(SITE_DIR, opt.init || 'integration/parity.draft.json');
+  if (file === MAP_FILE) die(`--init never overwrites the map (${relative(process.cwd(), MAP_FILE)}): give it another file.`);
+  writeDeep(file, `${JSON.stringify(draft, null, 2)}\n`);
+  console.log(`Draft map: ${relative(process.cwd(), file)}\nConfirm every selector (the guesses are listed in "confirm"), then move it to ${relative(process.cwd(), MAP_FILE)}.`);
+  process.exit(0);
+}
+
+// ------------------------------------------------------------------ the run
+
+/**
+ * For the fix hints (parity/hints.mjs): the integration's templates and
+ * styles (integration/**: *.ts, *.css), and Luma's built-in templates
+ * (src/…: the classes of the elements its markers name).
+ */
+function integrationFiles() {
+  const out = [];
+  const walk = (base, dir, keep) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(base, p, keep);
+      else if (keep(e.name)) out.push({ path: relative(base, p).split('\\').join('/'), text: readFileSync(p, 'utf8') });
+    }
+  };
+  walk(SITE_DIR, join(SITE_DIR, 'integration'), (n) => /\.(ts|css)$/.test(n));
+  walk(LUMA, join(LUMA, 'src/widgets'), (n) => /^template-.*\.ts$/.test(n));
+  walk(LUMA, join(LUMA, 'src/core'), (n) => n === 'image-tags.ts');
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+const OUT = resolve(opt.out);
+rmSync(OUT, { recursive: true, force: true });
+let run;
+try {
+  run = await runParity({ map, driver, out: OUT, only: opt.only, target: opt.target, files: integrationFiles(), log: (s) => process.stderr.write(`  ${s}\n`) });
+} catch (e) {
+  await close();
+  die(`the run broke: ${e.stack ?? e}`);
+}
+// Both paths of every page: ours, and the page of theirs it is compared against.
+await archive?.save({ host: HOST, recorded: new Date().toISOString(), viewports: map.viewports, pages: recordedPages(map) });
+await close();
+
+const recorded = archive?.meta?.recorded;
+if (profileShared) run.notes.push('--profile is one context: the interactions and the hold check ran in it (cookies and storage shared with the other pages); run without --profile for contexts of their own');
+if (profilePhone) run.notes.push('--profile is one desktop context: the phone widths were measured as a narrow desktop window, not as a phone (no touch, no phone user agent); run without --profile for a phone\'s layout');
+const meta = [
+  `${SITE_DIR} on ${ORIGIN}`,
+  mode === 'replay' ? `replay of ${relative(process.cwd(), ARCHIVE) || ARCHIVE}${recorded ? ` (recorded ${recorded.slice(0, 16).replace('T', ' ')})` : ''}` : mode === 'record' ? `live, recorded into ${relative(process.cwd(), ARCHIVE)}` : 'live, nothing recorded',
+  `viewports ${map.viewports.join(', ')} x ${map.height}, DPR 1, ${locale}, ${timezoneId}; build: ${DEV ? DEV.bundle : 'dist/'}`,
+];
+if (archive && mode === 'replay' && archive.stats.missed.length) {
+  const api = archive.stats.missed.filter((k) => /luigisbox\.ai\/discovery\//.test(k));
+  run.notes.push(`${archive.stats.missed.length} requests not in the recording were aborted (the site's analytics and beacons are expected here)`);
+  if (api.length) run.notes.push(`${api.length} API requests not in the recording: the build (or the map's ids) asks for other data than when it was recorded; re-record (yarn luma parity --record): ${api.slice(0, 3).join(' | ')}`);
+}
+const textOpts = { color: process.stdout.isTTY && !process.env.NO_COLOR, top: opt.all ? 0 : 12, title: `yarn luma parity: ${HOST}`, meta, thresholds: map.thresholds };
+console.log(formatText(run, textOpts));
+const json = toJson(run, { host: HOST, mode, viewports: map.viewports, target: opt.target, archive: archive ? { served: archive.stats.served, fuzzy: archive.stats.fuzzy, missed: archive.stats.missed.length } : null });
+writeFileSync(join(OUT, 'report.json'), `${JSON.stringify(json, null, 1)}\n`);
+writeFileSync(join(OUT, 'index.html'), formatHtml(run, { ...textOpts, color: false }));
+// --json <file>: its folder made first.
+if (opt.json) writeDeep(resolve(opt.json), `${JSON.stringify(json, null, 1)}\n`);
+console.log(`\nReport: ${relative(process.cwd(), join(OUT, 'index.html'))} (JSON: ${relative(process.cwd(), join(OUT, 'report.json'))})`);
+if (run.stopped) console.log("A bot challenge stopped the run; it is never worked around: run it on the client's own site with their knowledge, or ask them to allowlist the runner.");
+if (run.verdict.exitCode === 1) console.log(`Not converged: fix the template differences at the top (report.json "todo", in order), map or exclude what coverage lists, then run yarn luma parity${opt.target !== TARGET ? ` --target ${opt.target}` : ''} again. The data differences ("data") are the client's.`);
+process.exit(run.stopped && !run.results.length ? 2 : run.verdict.exitCode);

package/snippet/early-hold.js

@@ -0,0 +1,64 @@
+/*
+ * Luigi's Box early hold: the inline snippet a site puts first in <head>, next
+ * to the async LBX loader. Identical for every client (no ids, no rules): the
+ * rules come from localStorage, written by the bundle on earlier page views
+ * (src/core/early-rules.ts). Without them it does nothing.
+ *
+ * On a URL a stored route matches, before first paint: one <style> with that
+ * route's CSS (hides the host's listing, shows a loading bar), removed after
+ * the stored timeout unless the bundle claims it first (window.__lbx.early:
+ * claim(routeId) then drop()). window.__lbx is Luma's one global: the snippet
+ * makes it when it holds, the bundle adds its own to it (src/main.ts).
+ *
+ * Never blocks, never throws, makes no request. ES5 on purpose.
+ * Customers paste the minified form, snippet/early-hold.min.js (generated from
+ * this file, documented in README.md).
+ * Pasted copies stay on clients' pages: keep it backwards compatible.
+ */
+(function () {
+  try {
+    if (window.__lbx && window.__lbx.early) return;
+    var r = JSON.parse(localStorage.getItem('lbx:early') || 'null');
+    if (!r || r.v !== 1 || !(r.exp > Date.now())) return;
+    // Moved or injected late: never hide what the visitor has already seen.
+    if (performance.getEntriesByName && performance.getEntriesByName('first-contentful-paint').length) return;
+    var u = new URL(location.href);
+    for (var i = 0; i < r.routes.length; i++) {
+      var x = r.routes[i];
+      if (!new RegExp(x.path).test(u.pathname)) continue;
+      var ok = true;
+      for (var j = 0; x.need && j < x.need.length; j++) if (!(u.searchParams.get(x.need[j]) || '').trim()) ok = false;
+      if (ok && x.allow) {
+        var a = new RegExp(x.allow);
+        u.searchParams.forEach(function (v, n) {
+          if (v && !a.test(n)) ok = false;
+        });
+      }
+      if (!ok) continue;
+      var s = document.createElement('style');
+      var me = document.currentScript;
+      if (me && me.nonce) s.nonce = me.nonce;
+      s.setAttribute('data-lbx', 'early');
+      s.textContent = x.css;
+      (document.head || document.documentElement).appendChild(s);
+      var drop = function () {
+        clearTimeout(t);
+        if (s.parentNode) s.parentNode.removeChild(s);
+      };
+      var t = setTimeout(drop, r.ms || 1500);
+      var L = (window.__lbx = window.__lbx || {});
+      L.early = {
+        t: performance.now(),
+        route: x.id,
+        snippet: 1,
+        claim: function (id) {
+          if (!s.parentNode || id !== x.id) return false;
+          clearTimeout(t);
+          return true;
+        },
+        drop: drop,
+      };
+      return;
+    }
+  } catch (e) {}
+})();

package/snippet/early-hold.min.js

@@ -0,0 +1 @@
+"use strict";(function(){try{if(window.__lbx&&window.__lbx.early)return;var n=JSON.parse(localStorage.getItem("lbx:early")||"null");if(!n||n.v!==1||!(n.exp>Date.now())||performance.getEntriesByName&&performance.getEntriesByName("first-contentful-paint").length)return;for(var o=new URL(location.href),i=0;i<n.routes.length;i++){var e=n.routes[i];if(new RegExp(e.path).test(o.pathname)){for(var r=!0,l=0;e.need&&l<e.need.length;l++)(o.searchParams.get(e.need[l])||"").trim()||(r=!1);if(r&&e.allow){var d=new RegExp(e.allow);o.searchParams.forEach(function(a,p){a&&!d.test(p)&&(r=!1)})}if(r){var t=document.createElement("style"),c=document.currentScript;c&&c.nonce&&(t.nonce=c.nonce),t.setAttribute("data-lbx","early"),t.textContent=e.css,(document.head||document.documentElement).appendChild(t);var f=function(){clearTimeout(u),t.parentNode&&t.parentNode.removeChild(t)},u=setTimeout(f,n.ms||1500),m=window.__lbx=window.__lbx||{};m.early={t:performance.now(),route:e.id,snippet:1,claim:function(a){return!t.parentNode||a!==e.id?!1:(clearTimeout(u),!0)},drop:f};return}}}}catch(a){}})();