@decocms/parity 0.33.33 → 0.33.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/cli.js +924 -40
  2. package/package.json +1 -1
package/dist/cli.js CHANGED
@@ -38685,6 +38685,7 @@ async function newContext(browser, opts) {
38685
38685
  const baseContext = VIEWPORT_PRESETS[opts.viewport];
38686
38686
  const ctx = await browser.newContext({
38687
38687
  ...baseContext,
38688
+ ...opts.viewportSize ? { viewport: opts.viewportSize, screen: opts.viewportSize } : {},
38688
38689
  ...opts.deviceScaleFactor != null ? { deviceScaleFactor: opts.deviceScaleFactor } : {},
38689
38690
  recordHar: opts.harPath ? { path: opts.harPath, mode: "full", content: "omit" } : undefined,
38690
38691
  bypassCSP: true,
@@ -53394,6 +53395,9 @@ function diffScreenshots(prodPath, candPath, heatmapPath, opts = {}) {
53394
53395
  return {
53395
53396
  width,
53396
53397
  height,
53398
+ prodSize: [prod.width, prod.height],
53399
+ candSize: [cand.width, cand.height],
53400
+ cropped: prod.width !== cand.width || prod.height !== cand.height,
53397
53401
  diffPixels,
53398
53402
  totalPixels,
53399
53403
  pctDiff,
@@ -62694,12 +62698,12 @@ import { writeFile } from "node:fs/promises";
62694
62698
 
62695
62699
  // src/engine/capture-utils.ts
62696
62700
  import { PNG as PNG3 } from "pngjs";
62697
- function cropPngBuffer(srcBuffer, box) {
62701
+ function cropPngBuffer(srcBuffer, box, scale = 1) {
62698
62702
  const src = PNG3.sync.read(srcBuffer);
62699
- const x = Math.max(0, Math.floor(box.x));
62700
- const y = Math.max(0, Math.floor(box.y));
62701
- const w = Math.max(0, Math.min(Math.ceil(box.width), src.width - x));
62702
- const h = Math.max(0, Math.min(Math.ceil(box.height), src.height - y));
62703
+ const x = Math.max(0, Math.floor(box.x * scale));
62704
+ const y = Math.max(0, Math.floor(box.y * scale));
62705
+ const w = Math.max(0, Math.min(Math.ceil(box.width * scale), src.width - x));
62706
+ const h = Math.max(0, Math.min(Math.ceil(box.height * scale), src.height - y));
62703
62707
  if (w === 0 || h === 0) {
62704
62708
  throw new Error(`cropPngBuffer: bounding box has zero area after clamp (box=${JSON.stringify(box)} src=${src.width}x${src.height})`);
62705
62709
  }
@@ -62917,7 +62921,8 @@ async function captureSectionScreenshot(page, selector, outPath, preCapturedFull
62917
62921
  if (!box || box.width <= 0 || box.height <= 0) {
62918
62922
  return `seletor '${selector}' não tem boundingBox visível`;
62919
62923
  }
62920
- const cropped = cropPngBuffer(fullPng, box);
62924
+ const dpr = await page.evaluate(() => window.devicePixelRatio).catch(() => 1);
62925
+ const cropped = cropPngBuffer(fullPng, box, dpr);
62921
62926
  await writeFile(outPath, cropped);
62922
62927
  return null;
62923
62928
  } catch (err) {
@@ -74202,8 +74207,873 @@ async function mcpCommand(opts) {
74202
74207
  return 0;
74203
74208
  }
74204
74209
 
74205
- // src/commands/states.ts
74210
+ // src/commands/heatmap.ts
74211
+ import { mkdirSync as mkdirSync19 } from "node:fs";
74212
+ import { resolve as resolve12 } from "node:path";
74206
74213
  import chalk30 from "chalk";
74214
+
74215
+ // src/diff/hotspot-findings.ts
74216
+ var TYPOGRAPHY_PROPS = /^(font-family|font-weight|font-size|font-style|line-height|letter-spacing|text-transform)$/;
74217
+ var COLOR_PROPS = /^(color|background-color|border-color|fill|stroke)$/;
74218
+ var SPACING_PROPS = /^(margin|padding|gap|row-gap|column-gap)/;
74219
+ var SIZE_PROPS = /^(rect\.(width|height)|width|height)$/;
74220
+ var POSITION_PROPS = /^rect\.(offsetX|offsetY)$/;
74221
+ var IMAGE_TAGS = new Set(["img", "picture", "svg", "video", "canvas"]);
74222
+ function rankNodes(a, b) {
74223
+ const aExplains = a.deltas.length > 0;
74224
+ const bExplains = b.deltas.length > 0;
74225
+ if (aExplains !== bExplains)
74226
+ return aExplains ? -1 : 1;
74227
+ return a.rect.width * a.rect.height - b.rect.width * b.rect.height;
74228
+ }
74229
+ function intersects(rect, box) {
74230
+ return rect.x < box.x + box.width && rect.x + rect.width > box.x && rect.y < box.y + box.height && rect.y + rect.height > box.y;
74231
+ }
74232
+ function attributeHotspots(args) {
74233
+ const max = args.maxNodesPerHotspot ?? 3;
74234
+ const deltasByKey = new Map;
74235
+ for (const d of args.deltas) {
74236
+ const list = deltasByKey.get(d.key);
74237
+ if (list)
74238
+ list.push(d);
74239
+ else
74240
+ deltasByKey.set(d.key, [d]);
74241
+ }
74242
+ return args.hotspots.map((hotspot, i) => {
74243
+ const candidates = args.nodes.filter((n) => intersects(n.rect, hotspot)).map((n) => ({
74244
+ key: n.key,
74245
+ label: n.label,
74246
+ tag: n.tag,
74247
+ rect: n.rect,
74248
+ deltas: deltasByKey.get(n.key) ?? []
74249
+ })).sort(rankNodes).slice(0, max);
74250
+ const { type, because } = classify2(candidates, args.imageHostDelta ?? []);
74251
+ return {
74252
+ type,
74253
+ hotspot,
74254
+ nodes: candidates,
74255
+ truncated: args.truncated,
74256
+ summary: describe2(type, hotspot, candidates, args.imageHostDelta ?? [], because)
74257
+ };
74258
+ });
74259
+ }
74260
+ function classify2(nodes, imageHostDelta) {
74261
+ const deltas = nodes.flatMap((n) => n.deltas);
74262
+ const byKind = [
74263
+ ["offset", POSITION_PROPS],
74264
+ ["typography", TYPOGRAPHY_PROPS],
74265
+ ["color", COLOR_PROPS],
74266
+ ["size", SIZE_PROPS],
74267
+ ["spacing", SPACING_PROPS]
74268
+ ];
74269
+ for (const [type, re] of byKind) {
74270
+ const because = deltas.find((d) => re.test(d.prop));
74271
+ if (because)
74272
+ return { type, because };
74273
+ }
74274
+ if (imageHostDelta.length > 0 && nodes.some((n) => IMAGE_TAGS.has(n.tag))) {
74275
+ return { type: "image-source", because: null };
74276
+ }
74277
+ if (deltas[0])
74278
+ return { type: "unattributed", because: deltas[0] };
74279
+ return { type: "unattributed", because: null };
74280
+ }
74281
+ function nodeName(n) {
74282
+ if (!n.label)
74283
+ return n.key;
74284
+ return n.label === n.key ? n.label : `${n.label} (${n.key})`;
74285
+ }
74286
+ function describe2(type, hotspot, nodes, imageHostDelta, because) {
74287
+ const where = `at ${hotspot.x},${hotspot.y} — ${hotspot.width}×${hotspot.height}`;
74288
+ const owner = because ? nodes.find((n) => n.deltas.includes(because)) : undefined;
74289
+ const who = owner ? nodeName(owner) : nodes[0] ? nodeName(nodes[0]) : null;
74290
+ if (type === "offset" && because?.deltaPx != null) {
74291
+ const px = Math.abs(because.deltaPx);
74292
+ const horizontal = because.prop === "rect.offsetX";
74293
+ const dir = because.deltaPx < 0 ? horizontal ? "left" : "up" : horizontal ? "right" : "down";
74294
+ return `${who ?? "Content"} sits ${px}px further ${dir} than prod (${because.prop}: ${because.prod} → ${because.cand}) ${where}.`;
74295
+ }
74296
+ if (type === "image-source") {
74297
+ return `${who ?? "An image"} ${where} differs and the two sides serve images from different hosts (${imageHostDelta.join(", ")}) — recompression alone moves pixels, so this cannot reach zero until both use the same provider.`;
74298
+ }
74299
+ const delta = because;
74300
+ if (delta) {
74301
+ const arrow = `${delta.prop}: ${delta.prod} → ${delta.cand}`;
74302
+ const px = delta.deltaPx != null ? ` (${delta.deltaPx > 0 ? "+" : ""}${delta.deltaPx}px)` : "";
74303
+ return `${who} ${where}: ${arrow}${px}.`;
74304
+ }
74305
+ if (who) {
74306
+ return `${who} ${where} renders differently, but no box-tree delta explains it — check the computed styles and the CSS source for this node.`;
74307
+ }
74308
+ return `Difference ${where} could not be attributed to any element in the box tree — the subtree may be truncated, or the difference may sit outside it.`;
74309
+ }
74310
+
74311
+ // src/diff/noise-mask.ts
74312
+ import { readFileSync as readFileSync36, writeFileSync as writeFileSync31 } from "node:fs";
74313
+ import { PNG as PNG5 } from "pngjs";
74314
+ var DEFAULT_DILATE = 2;
74315
+ var MAX_MASK_COVERAGE = 0.2;
74316
+ function buildNoiseMask(firstPng, secondPng, dilate = DEFAULT_DILATE) {
74317
+ const a = PNG5.sync.read(readFileSync36(firstPng));
74318
+ const b = PNG5.sync.read(readFileSync36(secondPng));
74319
+ if (a.width !== b.width || a.height !== b.height)
74320
+ return null;
74321
+ const { width, height } = a;
74322
+ const raw = new Uint8Array(width * height);
74323
+ for (let i = 0, p = 0;i < a.data.length; i += 4, p++) {
74324
+ if (a.data[i] !== b.data[i] || a.data[i + 1] !== b.data[i + 1] || a.data[i + 2] !== b.data[i + 2] || a.data[i + 3] !== b.data[i + 3]) {
74325
+ raw[p] = 1;
74326
+ }
74327
+ }
74328
+ const data = dilate > 0 ? dilateMask(raw, width, height, dilate) : raw;
74329
+ let masked = 0;
74330
+ for (let p = 0;p < data.length; p++)
74331
+ if (data[p])
74332
+ masked++;
74333
+ const total = width * height;
74334
+ return { data, width, height, masked, coverage: total > 0 ? masked / total : 0 };
74335
+ }
74336
+ function dilateMask(src, width, height, radius) {
74337
+ const pass = (input, horizontal) => {
74338
+ const out = new Uint8Array(input.length);
74339
+ const outer = horizontal ? height : width;
74340
+ const inner = horizontal ? width : height;
74341
+ for (let o = 0;o < outer; o++) {
74342
+ for (let i = 0;i < inner; i++) {
74343
+ const idx = horizontal ? o * width + i : i * width + o;
74344
+ if (!input[idx])
74345
+ continue;
74346
+ const from = Math.max(0, i - radius);
74347
+ const to = Math.min(inner - 1, i + radius);
74348
+ for (let k = from;k <= to; k++) {
74349
+ out[horizontal ? o * width + k : k * width + o] = 1;
74350
+ }
74351
+ }
74352
+ }
74353
+ return out;
74354
+ };
74355
+ return pass(pass(src, true), false);
74356
+ }
74357
+ function applyMask(pngPath, mask, outPath) {
74358
+ const png = PNG5.sync.read(readFileSync36(pngPath));
74359
+ if (png.width !== mask.width || png.height !== mask.height) {
74360
+ throw new Error(`applyMask: image is ${png.width}x${png.height} but the mask is ${mask.width}x${mask.height}`);
74361
+ }
74362
+ for (let p = 0;p < mask.data.length; p++) {
74363
+ if (!mask.data[p])
74364
+ continue;
74365
+ const i = p * 4;
74366
+ png.data[i] = 0;
74367
+ png.data[i + 1] = 0;
74368
+ png.data[i + 2] = 0;
74369
+ png.data[i + 3] = 255;
74370
+ }
74371
+ writeFileSync31(outPath, PNG5.sync.write(png));
74372
+ }
74373
+
74374
+ // src/report/qa-comment.ts
74375
+ import { execFile } from "node:child_process";
74376
+ import { readFile } from "node:fs/promises";
74377
+ import { basename as basename4 } from "node:path";
74378
+ import { promisify } from "node:util";
74379
+ var exec = promisify(execFile);
74380
+ var QA_COMMENT_MARKER = "<!-- parity-qa -->";
74381
+ async function postQaComment(args) {
74382
+ const repoArgs = args.repo ? ["--repo", args.repo] : [];
74383
+ const uploads = new Map;
74384
+ const repositoryId = await ghRepositoryId(repoArgs, args.cwd);
74385
+ if (repositoryId) {
74386
+ for (const path of imagePathsToUpload(args.report)) {
74387
+ const url = await uploadAttachment(path, repositoryId, args.cwd);
74388
+ if (url)
74389
+ uploads.set(path, url);
74390
+ }
74391
+ }
74392
+ const body = buildQaComment(args.report, uploads);
74393
+ const existing = await findOwnComment(args.pr, repoArgs, args.cwd);
74394
+ if (existing) {
74395
+ await exec("gh", ["api", "--method", "PATCH", existing, "-f", `body=${body}`], {
74396
+ cwd: args.cwd,
74397
+ maxBuffer: 10 * 1024 * 1024
74398
+ });
74399
+ return;
74400
+ }
74401
+ await exec("gh", ["pr", "comment", args.pr, ...repoArgs, "--body", body], {
74402
+ cwd: args.cwd,
74403
+ maxBuffer: 10 * 1024 * 1024
74404
+ });
74405
+ }
74406
+ function imagePathsToUpload(report) {
74407
+ return report.viewports.filter((v) => v.verdict === "differs" && v.heatmapPath).map((v) => v.heatmapPath);
74408
+ }
74409
+ async function ghRepositoryId(repoArgs, cwd) {
74410
+ try {
74411
+ const target = repoArgs.length > 0 ? repoArgs[1] : "{owner}/{repo}";
74412
+ const { stdout } = await exec("gh", ["api", `repos/${target}`, "--jq", ".id"], { cwd });
74413
+ const id = Number.parseInt(stdout.trim(), 10);
74414
+ return Number.isFinite(id) ? id : null;
74415
+ } catch {
74416
+ return null;
74417
+ }
74418
+ }
74419
+ async function uploadAttachment(path, repositoryId, cwd) {
74420
+ try {
74421
+ const token = await githubToken(cwd);
74422
+ if (!token)
74423
+ return null;
74424
+ const bytes = await readFile(path);
74425
+ const qs = new URLSearchParams({
74426
+ name: basename4(path),
74427
+ content_type: "image/png",
74428
+ repository_id: String(repositoryId)
74429
+ });
74430
+ const res = await fetch(`https://uploads.github.com/user-attachments/assets?${qs}`, {
74431
+ method: "POST",
74432
+ headers: {
74433
+ Authorization: `Bearer ${token}`,
74434
+ Accept: "application/json",
74435
+ "Content-Type": "image/png"
74436
+ },
74437
+ body: new Uint8Array(bytes)
74438
+ });
74439
+ if (!res.ok)
74440
+ return null;
74441
+ const json = await res.json();
74442
+ const url = json.href ?? json.url;
74443
+ if (!url)
74444
+ return null;
74445
+ const head = await fetch(url, {
74446
+ method: "HEAD",
74447
+ headers: { Authorization: `Bearer ${token}` },
74448
+ redirect: "manual"
74449
+ });
74450
+ return head.ok ? url : null;
74451
+ } catch {
74452
+ return null;
74453
+ }
74454
+ }
74455
+ async function githubToken(cwd) {
74456
+ const fromEnv = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
74457
+ if (fromEnv)
74458
+ return fromEnv;
74459
+ try {
74460
+ return (await exec("gh", ["auth", "token"], { cwd })).stdout.trim() || null;
74461
+ } catch {
74462
+ return null;
74463
+ }
74464
+ }
74465
+ async function findOwnComment(pr, repoArgs, cwd) {
74466
+ try {
74467
+ const { stdout } = await exec("gh", ["pr", "view", pr, ...repoArgs, "--json", "comments"], {
74468
+ cwd,
74469
+ maxBuffer: 10 * 1024 * 1024
74470
+ });
74471
+ const parsed = JSON.parse(stdout);
74472
+ const mine = (parsed.comments ?? []).filter((c) => c.body?.includes(QA_COMMENT_MARKER));
74473
+ const last = mine[mine.length - 1];
74474
+ if (!last?.url)
74475
+ return null;
74476
+ const m = /github\.com\/([^/]+)\/([^/]+)\/pull\/\d+#issuecomment-(\d+)/.exec(last.url);
74477
+ if (!m)
74478
+ return null;
74479
+ return `repos/${m[1]}/${m[2]}/issues/comments/${m[3]}`;
74480
+ } catch {
74481
+ return null;
74482
+ }
74483
+ }
74484
+ var HEADLINE = {
74485
+ identical: "✓ approved",
74486
+ differs: "✗ rejected",
74487
+ inconclusive: "? inconclusive"
74488
+ };
74489
+ function buildQaComment(report, uploads) {
74490
+ const failing = report.viewports.filter((v) => v.verdict !== "identical");
74491
+ const lines = [
74492
+ QA_COMMENT_MARKER,
74493
+ `## Parity QA — ${HEADLINE[report.verdict]}`,
74494
+ "",
74495
+ `Zero-tolerance pixel gate · ${report.mode} mode · ${report.viewports.length} viewports · ${failing.length} not clean.`,
74496
+ ""
74497
+ ];
74498
+ if (report.reason)
74499
+ lines.push(`> ${report.reason}`, "");
74500
+ for (const v of report.viewports) {
74501
+ lines.push(...viewportBlock(v, uploads));
74502
+ }
74503
+ if (report.verdict !== "identical") {
74504
+ lines.push("**To approve, every viewport must reach 0 differing pixels.** An `inconclusive` viewport is not a pass — it means nothing was compared there.");
74505
+ }
74506
+ return lines.join(`
74507
+ `);
74508
+ }
74509
+ function viewportBlock(v, uploads) {
74510
+ if (v.verdict === "identical")
74511
+ return [`### ${v.label} — clean`, ""];
74512
+ const head = v.verdict === "differs" ? `### ${v.label} — ${(v.diffPixels ?? 0).toLocaleString("en-US")} differing pixels` : `### ${v.label} — not compared`;
74513
+ const out = [head, ""];
74514
+ if (v.reason)
74515
+ out.push(v.reason, "");
74516
+ const uploaded = v.heatmapPath ? uploads.get(v.heatmapPath) : undefined;
74517
+ if (uploaded)
74518
+ out.push(`![diff](${uploaded})`, "");
74519
+ else if (v.heatmapPath && v.verdict === "differs") {
74520
+ out.push(`_Diff image could not be uploaded; it is on the runner at_ \`${v.heatmapPath}\``, "");
74521
+ }
74522
+ if (v.findings.length > 0) {
74523
+ for (const f of v.findings.slice(0, 5))
74524
+ out.push(`- **${f.type}** — ${f.summary}`);
74525
+ if (v.findings.some((f) => f.truncated)) {
74526
+ out.push("- _The box tree hit its size cap, so an unattributed region above is not proof that no element sits there._");
74527
+ }
74528
+ } else {
74529
+ for (const h of v.hotspots.slice(0, 5)) {
74530
+ out.push(`- Hotspot at ${h.x},${h.y} — ${h.width}×${h.height} (${h.pixelCount} px).`);
74531
+ }
74532
+ }
74533
+ const hosts = hostsOnlyOnOneSide(v);
74534
+ if (hosts.onlyProd.length > 0 || hosts.onlyCand.length > 0) {
74535
+ const where = [
74536
+ hosts.onlyProd.length ? `prod only: ${hosts.onlyProd.join(", ")}` : null,
74537
+ hosts.onlyCand.length ? `cand only: ${hosts.onlyCand.join(", ")}` : null
74538
+ ].filter(Boolean).join("; ");
74539
+ out.push(`- Images come from different hosts (${where}). Pixel parity is unreachable until both sides use the same image provider.`);
74540
+ }
74541
+ out.push("");
74542
+ return out;
74543
+ }
74544
+ function hostsOnlyOnOneSide(v) {
74545
+ return imageHostDelta(v.prod.imageHosts, v.cand.imageHosts);
74546
+ }
74547
+
74548
+ // src/commands/heatmap.ts
74549
+ var DEFAULT_VIEWPORTS = "mobile,tablet,1024x768,desktop,1920x1080,2560x1440";
74550
+ var MOBILE_UA_MAX_WIDTH = 767;
74551
+ function parseViewports2(raw) {
74552
+ const entries = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
74553
+ if (entries.length === 0)
74554
+ return "--viewports is empty";
74555
+ const specs = [];
74556
+ for (const entry of entries) {
74557
+ const named = parseViewport3(entry);
74558
+ if (named) {
74559
+ specs.push({ label: entry, viewport: named, size: null });
74560
+ continue;
74561
+ }
74562
+ const m = /^(\d{2,5})x(\d{2,5})$/.exec(entry);
74563
+ if (!m) {
74564
+ return `invalid viewport: '${entry}' (use mobile|tablet|desktop or <width>x<height>)`;
74565
+ }
74566
+ const width = Number(m[1]);
74567
+ const height = Number(m[2]);
74568
+ specs.push({
74569
+ label: entry,
74570
+ viewport: width <= MOBILE_UA_MAX_WIDTH ? "mobile" : "desktop",
74571
+ size: { width, height }
74572
+ });
74573
+ }
74574
+ return specs;
74575
+ }
74576
+ function aggregateVerdict(results) {
74577
+ if (results.length === 0) {
74578
+ return { verdict: "inconclusive", reason: "no viewport was compared" };
74579
+ }
74580
+ const differing = results.filter((r) => r.verdict === "differs");
74581
+ if (differing.length > 0) {
74582
+ const total = differing.reduce((sum, r) => sum + (r.diffPixels ?? 0), 0);
74583
+ return {
74584
+ verdict: "differs",
74585
+ reason: `${differing.length}/${results.length} viewports differ (${total} pixels in total): ${differing.map((r) => r.label).join(", ")}`
74586
+ };
74587
+ }
74588
+ const unread = results.filter((r) => r.verdict === "inconclusive");
74589
+ if (unread.length > 0) {
74590
+ return {
74591
+ verdict: "inconclusive",
74592
+ reason: `${unread.length}/${results.length} viewports could not be compared: ${unread.map((r) => `${r.label} (${r.reason ?? "no reason given"})`).join("; ")}`
74593
+ };
74594
+ }
74595
+ return { verdict: "identical" };
74596
+ }
74597
+ var EXIT_IDENTICAL = 0;
74598
+ var EXIT_DIFFERS = 1;
74599
+ var EXIT_INCONCLUSIVE = 2;
74600
+ function exitCodeFor(verdict) {
74601
+ if (verdict === "identical")
74602
+ return EXIT_IDENTICAL;
74603
+ if (verdict === "differs")
74604
+ return EXIT_DIFFERS;
74605
+ return EXIT_INCONCLUSIVE;
74606
+ }
74607
+ async function heatmapCommand(opts) {
74608
+ const specs = parseViewports2(opts.viewports);
74609
+ if (typeof specs === "string") {
74610
+ console.error(chalk30.red(specs));
74611
+ return EXIT_INCONCLUSIVE;
74612
+ }
74613
+ const waitMs = Number.parseInt(opts.wait, 10);
74614
+ if (!Number.isFinite(waitMs) || waitMs < 0) {
74615
+ console.error(chalk30.red(`--wait inválido: ${opts.wait}`));
74616
+ return EXIT_INCONCLUSIVE;
74617
+ }
74618
+ if (!isValidUrl5(opts.prod) || !isValidUrl5(opts.cand)) {
74619
+ console.error(chalk30.red("--prod ou --cand inválido"));
74620
+ return EXIT_INCONCLUSIVE;
74621
+ }
74622
+ const selector = opts.selector?.trim() || null;
74623
+ const candSelector = opts.candSelector?.trim() || selector;
74624
+ const mode = selector ? "section" : "page";
74625
+ mkdirSync19(opts.outDir, { recursive: true });
74626
+ const prefix = `heatmap-${hashSelector(`${opts.prod}|${opts.cand}|${selector ?? "page"}`)}`;
74627
+ const browser = await launchBrowser({ headless: true });
74628
+ const results = [];
74629
+ try {
74630
+ for (const spec of specs) {
74631
+ results.push(await compareViewportSafely(browser, {
74632
+ spec,
74633
+ prodUrl: opts.prod,
74634
+ candUrl: opts.cand,
74635
+ selector,
74636
+ candSelector,
74637
+ waitMs,
74638
+ outDir: opts.outDir,
74639
+ prefix
74640
+ }));
74641
+ }
74642
+ } finally {
74643
+ await browser.close().catch(() => {
74644
+ return;
74645
+ });
74646
+ }
74647
+ const { verdict, reason } = aggregateVerdict(results);
74648
+ const report = {
74649
+ verdict,
74650
+ reason,
74651
+ mode,
74652
+ prodUrl: opts.prod,
74653
+ candUrl: opts.cand,
74654
+ viewports: results
74655
+ };
74656
+ if (opts.pr) {
74657
+ await postQaComment({ report, pr: opts.pr, repo: opts.repo }).catch((err) => {
74658
+ console.error(chalk30.yellow(` aviso: não foi possível publicar no PR — ${err.message}`));
74659
+ });
74660
+ }
74661
+ if (opts.json)
74662
+ console.log(JSON.stringify(report));
74663
+ else
74664
+ printReport(report);
74665
+ return exitCodeFor(verdict);
74666
+ }
74667
+ async function compareViewport(browser, args) {
74668
+ const { spec } = args;
74669
+ const paths = artifactPaths(args.outDir, args.prefix, spec.label);
74670
+ const [prod, cand] = await Promise.all([
74671
+ captureSide(browser, {
74672
+ spec,
74673
+ url: args.prodUrl,
74674
+ selector: args.selector,
74675
+ waitMs: args.waitMs,
74676
+ outPath: paths.prod,
74677
+ repeatPath: paths.prodRepeat
74678
+ }),
74679
+ captureSide(browser, {
74680
+ spec,
74681
+ url: args.candUrl,
74682
+ selector: args.candSelector,
74683
+ waitMs: args.waitMs,
74684
+ outPath: paths.cand,
74685
+ repeatPath: null
74686
+ })
74687
+ ]);
74688
+ return judgePair({
74689
+ spec,
74690
+ paths,
74691
+ prod: prod.side,
74692
+ cand: cand.side,
74693
+ prodRepeatScreenshot: prod.repeatScreenshot,
74694
+ prodRepeatError: prod.repeatError,
74695
+ prodBoxTree: prod.boxTree,
74696
+ candBoxTree: cand.boxTree
74697
+ });
74698
+ }
74699
+ async function compareViewportSafely(browser, args) {
74700
+ try {
74701
+ return await compareViewport(browser, args);
74702
+ } catch (err) {
74703
+ return {
74704
+ ...emptyResult2(args.spec),
74705
+ verdict: "inconclusive",
74706
+ reason: `viewport failed to run: ${err.message}`
74707
+ };
74708
+ }
74709
+ }
74710
+ function emptyResult2(spec) {
74711
+ const blank = {
74712
+ selector: null,
74713
+ matches: null,
74714
+ rect: null,
74715
+ screenshot: null,
74716
+ imageHosts: [],
74717
+ devicePixelRatio: 1,
74718
+ fontsStatus: "unknown"
74719
+ };
74720
+ return {
74721
+ label: spec.label,
74722
+ width: spec.size?.width ?? null,
74723
+ height: spec.size?.height ?? null,
74724
+ prod: blank,
74725
+ cand: blank,
74726
+ size: { prod: null, cand: null, matched: false },
74727
+ diffPixels: null,
74728
+ pctDiff: null,
74729
+ noiseFloorPixels: null,
74730
+ maskedCoverage: null,
74731
+ boundingBox: null,
74732
+ hotspots: [],
74733
+ findings: [],
74734
+ heatmapPath: null
74735
+ };
74736
+ }
74737
+ function artifactPaths(outDir, prefix, label) {
74738
+ const at = (suffix) => resolve12(outDir, `${prefix}-${label}-${suffix}.png`);
74739
+ return {
74740
+ prod: at("prod"),
74741
+ prodRepeat: at("prod-repeat"),
74742
+ cand: at("cand"),
74743
+ diff: at("diff"),
74744
+ noise: at("noise"),
74745
+ prodMasked: at("prod-masked"),
74746
+ candMasked: at("cand-masked")
74747
+ };
74748
+ }
74749
+ function judgePair(args) {
74750
+ const { spec, paths, prod, cand } = args;
74751
+ const base = {
74752
+ label: spec.label,
74753
+ width: spec.size?.width ?? null,
74754
+ height: spec.size?.height ?? null,
74755
+ prod,
74756
+ cand,
74757
+ size: { prod: null, cand: null, matched: false },
74758
+ diffPixels: null,
74759
+ pctDiff: null,
74760
+ noiseFloorPixels: null,
74761
+ maskedCoverage: null,
74762
+ boundingBox: null,
74763
+ hotspots: [],
74764
+ findings: [],
74765
+ heatmapPath: null
74766
+ };
74767
+ const blocked = firstBlocker(prod, cand);
74768
+ if (blocked)
74769
+ return { ...base, verdict: "inconclusive", reason: blocked };
74770
+ if (!args.prodRepeatScreenshot) {
74771
+ return {
74772
+ ...base,
74773
+ verdict: "inconclusive",
74774
+ reason: `prod's second capture is missing, so its noise floor is unknown and zero cannot be demanded${args.prodRepeatError ? ` (${args.prodRepeatError})` : ""}`
74775
+ };
74776
+ }
74777
+ let noiseFloorPixels;
74778
+ let maskedCoverage;
74779
+ let comparePaths;
74780
+ try {
74781
+ const mask = buildNoiseMask(prod.screenshot, args.prodRepeatScreenshot);
74782
+ if (!mask) {
74783
+ return {
74784
+ ...base,
74785
+ verdict: "inconclusive",
74786
+ reason: "prod is not a stable size across two captures — the page was still growing"
74787
+ };
74788
+ }
74789
+ noiseFloorPixels = mask.masked;
74790
+ maskedCoverage = mask.coverage;
74791
+ if (mask.coverage > MAX_MASK_COVERAGE) {
74792
+ return {
74793
+ ...base,
74794
+ noiseFloorPixels,
74795
+ maskedCoverage,
74796
+ verdict: "inconclusive",
74797
+ reason: `prod could not reproduce ${(mask.coverage * 100).toFixed(1)}% of the frame across two captures (${mask.masked} px) — too much of the page is in motion to hold the candidate to anything (noise heatmap: ${paths.noise})`
74798
+ };
74799
+ }
74800
+ if (mask.masked > 0) {
74801
+ applyMask(prod.screenshot, mask, paths.prodMasked);
74802
+ applyMask(cand.screenshot, mask, paths.candMasked);
74803
+ comparePaths = { prod: paths.prodMasked, cand: paths.candMasked };
74804
+ } else {
74805
+ comparePaths = { prod: prod.screenshot, cand: cand.screenshot };
74806
+ }
74807
+ } catch (err) {
74808
+ return {
74809
+ ...base,
74810
+ verdict: "inconclusive",
74811
+ reason: `prod's self-check failed: ${err.message}`
74812
+ };
74813
+ }
74814
+ let diff;
74815
+ try {
74816
+ diff = diffScreenshots(comparePaths.prod, comparePaths.cand, paths.diff, {
74817
+ threshold: 0,
74818
+ maxPctDiff: 0
74819
+ });
74820
+ } catch (err) {
74821
+ return {
74822
+ ...base,
74823
+ noiseFloorPixels,
74824
+ maskedCoverage,
74825
+ verdict: "inconclusive",
74826
+ reason: `could not compare the screenshots: ${err.message}`
74827
+ };
74828
+ }
74829
+ const size = { prod: diff.prodSize, cand: diff.candSize, matched: !diff.cropped };
74830
+ if (diff.cropped) {
74831
+ return {
74832
+ ...base,
74833
+ size,
74834
+ noiseFloorPixels,
74835
+ maskedCoverage,
74836
+ heatmapPath: paths.diff,
74837
+ verdict: "inconclusive",
74838
+ reason: `different dimensions (prod ${fmtSize(diff.prodSize)}, cand ${fmtSize(diff.candSize)}) — the comparison would only look at the intersection`
74839
+ };
74840
+ }
74841
+ const analysis = analyzeHeatmapRegions(paths.diff, { minComponentPixels: 1 });
74842
+ return {
74843
+ ...base,
74844
+ size,
74845
+ noiseFloorPixels,
74846
+ maskedCoverage,
74847
+ diffPixels: diff.diffPixels,
74848
+ pctDiff: diff.pctDiff,
74849
+ boundingBox: analysis.boundingBox,
74850
+ hotspots: analysis.hotspots,
74851
+ findings: explainHotspots(analysis.hotspots, prod, cand, paths, args.prodBoxTree, args.candBoxTree),
74852
+ heatmapPath: paths.diff,
74853
+ verdict: diff.diffPixels === 0 ? "identical" : "differs",
74854
+ reason: diff.diffPixels === 0 ? undefined : `${diff.diffPixels} differing pixels in ${analysis.hotspots.length} region(s)`
74855
+ };
74856
+ }
74857
+ function explainHotspots(hotspots, prod, cand, paths, prodBoxTree, candBoxTree) {
74858
+ if (hotspots.length === 0)
74859
+ return [];
74860
+ const p = prodBoxTree;
74861
+ const c = candBoxTree;
74862
+ const paired = p?.found && c?.found ? diffBoxTrees(p.nodes, c.nodes, { truncated: p.truncated || c.truncated }) : null;
74863
+ return attributeHotspots({
74864
+ hotspots,
74865
+ nodes: p?.found ? p.nodes : [],
74866
+ deltas: paired?.deltas ?? [],
74867
+ truncated: paired?.truncated ?? true,
74868
+ imageHostDelta: hostsOnOneSideOnly(prod.imageHosts, cand.imageHosts)
74869
+ });
74870
+ }
74871
+ function firstBlocker(prod, cand) {
74872
+ for (const [name, side] of [
74873
+ ["prod", prod],
74874
+ ["cand", cand]
74875
+ ]) {
74876
+ if (side.error)
74877
+ return `${name}: ${side.error}`;
74878
+ if (side.matches !== null && side.matches !== 1) {
74879
+ return `${name}: selector '${side.selector}' matched ${side.matches} elements (must match exactly 1) — \`parity locate\` resolves which node each side means`;
74880
+ }
74881
+ if (!side.screenshot)
74882
+ return `${name}: no screenshot was produced`;
74883
+ }
74884
+ if (prod.devicePixelRatio !== cand.devicePixelRatio) {
74885
+ return `different deviceScaleFactor (prod ${prod.devicePixelRatio}x, cand ${cand.devicePixelRatio}x) — the same screen rasterised at different densities never matches pixel for pixel`;
74886
+ }
74887
+ for (const [name, side] of [
74888
+ ["prod", prod],
74889
+ ["cand", cand]
74890
+ ]) {
74891
+ if (side.fontsStatus !== "loaded") {
74892
+ return `${name}: fonts were still loading (document.fonts.status = "${side.fontsStatus}")`;
74893
+ }
74894
+ }
74895
+ return null;
74896
+ }
74897
+ async function captureSide(browser, args) {
74898
+ const side = {
74899
+ selector: args.selector,
74900
+ matches: null,
74901
+ rect: null,
74902
+ screenshot: null,
74903
+ imageHosts: [],
74904
+ devicePixelRatio: 1,
74905
+ fontsStatus: "unknown"
74906
+ };
74907
+ let repeatScreenshot = null;
74908
+ let repeatError;
74909
+ let boxTree;
74910
+ const ctx = await newContext(browser, {
74911
+ viewport: args.spec.viewport,
74912
+ viewportSize: args.spec.size ?? undefined,
74913
+ deviceScaleFactor: 1
74914
+ });
74915
+ const page = await ctx.newPage();
74916
+ try {
74917
+ await page.goto(args.url, { waitUntil: "domcontentloaded", timeout: 30000 });
74918
+ await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => {
74919
+ return;
74920
+ });
74921
+ if (args.waitMs > 0)
74922
+ await page.waitForTimeout(args.waitMs);
74923
+ await reloadIfOptionalFonts(page, args.waitMs);
74924
+ await waitForLayoutStable(page);
74925
+ await Promise.race([
74926
+ stabilizeCarousels(page).catch(() => {
74927
+ return;
74928
+ }),
74929
+ new Promise((r) => setTimeout(r, 3000))
74930
+ ]);
74931
+ const scrollBudget = 30000;
74932
+ await Promise.race([
74933
+ scrollFullPage(page, scrollBudget).catch(() => {
74934
+ return;
74935
+ }),
74936
+ new Promise((r) => setTimeout(r, scrollBudget + 2000))
74937
+ ]);
74938
+ await Promise.race([
74939
+ waitForSkeletonsToResolve(page, 5000).catch(() => {
74940
+ return;
74941
+ }),
74942
+ new Promise((r) => setTimeout(r, 5000))
74943
+ ]);
74944
+ side.devicePixelRatio = await page.evaluate(() => window.devicePixelRatio);
74945
+ side.fontsStatus = await page.evaluate(() => document.fonts?.status ?? "unknown");
74946
+ if (args.selector) {
74947
+ const loc = page.locator(args.selector);
74948
+ side.matches = await loc.count();
74949
+ if (side.matches !== 1)
74950
+ return { side, repeatScreenshot };
74951
+ side.rect = await loc.first().boundingBox({ timeout: 3000 });
74952
+ const err = await captureSectionScreenshot(page, args.selector, args.outPath);
74953
+ if (err)
74954
+ side.error = err;
74955
+ else
74956
+ side.screenshot = args.outPath;
74957
+ } else {
74958
+ await page.screenshot({ path: args.outPath, fullPage: true, animations: "disabled" });
74959
+ side.screenshot = args.outPath;
74960
+ }
74961
+ boxTree = await readBoxTree(page, args.selector ?? "body").catch(() => {
74962
+ return;
74963
+ });
74964
+ side.imageHosts = await readImageHosts(page, args.selector);
74965
+ if (args.repeatPath && side.screenshot) {
74966
+ await page.waitForTimeout(600);
74967
+ if (args.selector) {
74968
+ const err = await captureSectionScreenshot(page, args.selector, args.repeatPath);
74969
+ if (err)
74970
+ repeatError = err;
74971
+ else
74972
+ repeatScreenshot = args.repeatPath;
74973
+ } else {
74974
+ await page.screenshot({ path: args.repeatPath, fullPage: true, animations: "disabled" });
74975
+ repeatScreenshot = args.repeatPath;
74976
+ }
74977
+ }
74978
+ } catch (err) {
74979
+ side.error = err.message;
74980
+ repeatError ??= err.message;
74981
+ } finally {
74982
+ await page.close().catch(() => {
74983
+ return;
74984
+ });
74985
+ await ctx.close().catch(() => {
74986
+ return;
74987
+ });
74988
+ }
74989
+ return { side, repeatScreenshot, repeatError, boxTree };
74990
+ }
74991
+ async function readImageHosts(page, selector) {
74992
+ return page.evaluate((sel) => {
74993
+ const root = sel ? document.querySelector(sel) : document.body;
74994
+ if (!root)
74995
+ return [];
74996
+ const hosts = new Set;
74997
+ for (const img of Array.from(root.querySelectorAll("img"))) {
74998
+ const urls = [img.getAttribute("src"), ...(img.getAttribute("srcset") ?? "").split(",")];
74999
+ for (const raw of urls) {
75000
+ const url = raw?.trim().split(/\s+/)[0];
75001
+ if (!url)
75002
+ continue;
75003
+ try {
75004
+ hosts.add(new URL(url, document.baseURI).host);
75005
+ } catch {}
75006
+ }
75007
+ }
75008
+ return Array.from(hosts).sort();
75009
+ }, selector).catch(() => []);
75010
+ }
75011
+ function hostsOnOneSideOnly(prod, cand) {
75012
+ const d = imageHostDelta(prod, cand);
75013
+ return [...d.onlyProd, ...d.onlyCand];
75014
+ }
75015
+ function fmtSize(size) {
75016
+ return `${size[0]}×${size[1]}`;
75017
+ }
75018
+ function isValidUrl5(s) {
75019
+ try {
75020
+ new URL(s);
75021
+ return true;
75022
+ } catch {
75023
+ return false;
75024
+ }
75025
+ }
75026
+ var MARK = {
75027
+ identical: chalk30.green("✓"),
75028
+ differs: chalk30.red("✗"),
75029
+ inconclusive: chalk30.yellow("?")
75030
+ };
75031
+ function printReport(report) {
75032
+ console.log("");
75033
+ console.log(chalk30.bold(` parity heatmap — ${report.mode}`));
75034
+ console.log(chalk30.dim(` prod: ${report.prodUrl}`));
75035
+ console.log(chalk30.dim(` cand: ${report.candUrl}`));
75036
+ console.log("");
75037
+ for (const v of report.viewports) {
75038
+ const detail = v.verdict === "identical" ? chalk30.dim("0 pixels") : v.reason ?? chalk30.dim("no detail");
75039
+ console.log(` ${MARK[v.verdict]} ${v.label.padEnd(12)} ${detail}`);
75040
+ if (v.maskedCoverage != null && v.maskedCoverage > 0) {
75041
+ console.log(chalk30.dim(` ${(v.maskedCoverage * 100).toFixed(1)}% of the frame excluded: prod does not reproduce those pixels`));
75042
+ }
75043
+ for (const f of v.findings.slice(0, 5)) {
75044
+ console.log(chalk30.dim(` [${f.type}] ${f.summary}`));
75045
+ }
75046
+ if (v.heatmapPath && v.verdict === "differs") {
75047
+ console.log(chalk30.dim(` ${v.heatmapPath}`));
75048
+ }
75049
+ const hosts = imageHostDelta(v.prod.imageHosts, v.cand.imageHosts);
75050
+ if (hosts.onlyProd.length > 0 || hosts.onlyCand.length > 0) {
75051
+ console.log(chalk30.yellow(` image hosts diverge — ${formatHostDelta(hosts)}`));
75052
+ }
75053
+ }
75054
+ console.log("");
75055
+ console.log(` ${MARK[report.verdict]} ${chalk30.bold(report.verdict)}${report.reason ? ` — ${report.reason}` : ""}`);
75056
+ console.log("");
75057
+ }
75058
+ function imageHostDelta(prod, cand) {
75059
+ const inProd = new Set(prod);
75060
+ const inCand = new Set(cand);
75061
+ return {
75062
+ onlyProd: prod.filter((h) => !inCand.has(h)).sort(),
75063
+ onlyCand: cand.filter((h) => !inProd.has(h)).sort()
75064
+ };
75065
+ }
75066
+ function formatHostDelta(d) {
75067
+ const parts = [];
75068
+ if (d.onlyProd.length)
75069
+ parts.push(`prod only: ${d.onlyProd.join(", ")}`);
75070
+ if (d.onlyCand.length)
75071
+ parts.push(`cand only: ${d.onlyCand.join(", ")}`);
75072
+ return parts.join(" · ");
75073
+ }
75074
+
75075
+ // src/commands/states.ts
75076
+ import chalk31 from "chalk";
74207
75077
  var HOVERABLE = "a,button,summary,[role='button'],[role='menuitem'],label";
74208
75078
  var SETTLE_RETRY_FACTOR = 4;
74209
75079
  async function readStateEffects(page, opts) {
@@ -74424,7 +75294,7 @@ function statesVerdict(counts) {
74424
75294
  async function statesCommand(opts) {
74425
75295
  const viewport = parseViewport3(opts.viewport);
74426
75296
  if (!viewport) {
74427
- console.error(chalk30.red(`--viewport inválido: ${opts.viewport}`));
75297
+ console.error(chalk31.red(`--viewport inválido: ${opts.viewport}`));
74428
75298
  return 2;
74429
75299
  }
74430
75300
  const waitMs = Number.parseInt(opts.wait, 10) || 0;
@@ -74433,12 +75303,12 @@ async function statesCommand(opts) {
74433
75303
  const prodSelector = opts.prodSelector?.trim() || opts.selector?.trim();
74434
75304
  const candSelector = opts.candSelector?.trim() || opts.selector?.trim();
74435
75305
  if (!prodSelector || !candSelector) {
74436
- console.error(chalk30.red(" informe --selector (ambos os lados) ou --prod-selector e --cand-selector"));
75306
+ console.error(chalk31.red(" informe --selector (ambos os lados) ou --prod-selector e --cand-selector"));
74437
75307
  return 2;
74438
75308
  }
74439
75309
  const { aliases, note: aliasNote } = resolveAliases(opts.planDir);
74440
75310
  if (aliasNote)
74441
- console.log(chalk30.dim(` ${aliasNote}`));
75311
+ console.log(chalk31.dim(` ${aliasNote}`));
74442
75312
  const browser = await launchBrowser({ headless: true });
74443
75313
  try {
74444
75314
  const [prodSide, candSide] = await Promise.all([
@@ -74461,7 +75331,7 @@ async function statesCommand(opts) {
74461
75331
  ]);
74462
75332
  if (prodSide.baseError || candSide.baseError) {
74463
75333
  const which = prodSide.baseError ? `prod: ${prodSide.baseError}` : `cand: ${candSide.baseError}`;
74464
- console.error(chalk30.red(` não foi possível ler o componente — ${which}`));
75334
+ console.error(chalk31.red(` não foi possível ler o componente — ${which}`));
74465
75335
  return 2;
74466
75336
  }
74467
75337
  const motion = prodSide.motion.found && candSide.motion.found ? diffMotion(prodSide.motion, candSide.motion, {
@@ -74498,58 +75368,58 @@ async function statesCommand(opts) {
74498
75368
  ]) {
74499
75369
  const caveat = data.settle && formatSettleCaveat(name, data.settle);
74500
75370
  if (caveat)
74501
- console.log(chalk30.yellow(` ${caveat}`));
75371
+ console.log(chalk31.yellow(` ${caveat}`));
74502
75372
  }
74503
75373
  console.log("");
74504
- console.log(chalk30.bold(" Declared motion"));
75374
+ console.log(chalk31.bold(" Declared motion"));
74505
75375
  if (!motion) {
74506
75376
  const err = prodSide.motion.found ? candSide.motion : prodSide.motion;
74507
- console.log(chalk30.yellow(` não foi possível comparar — ${"error" in err ? err.error : "?"}`));
75377
+ console.log(chalk31.yellow(` não foi possível comparar — ${"error" in err ? err.error : "?"}`));
74508
75378
  } else {
74509
75379
  for (const line of formatMotionDiff(motion).split(`
74510
75380
  `))
74511
75381
  console.log(` ${line}`);
74512
75382
  }
74513
75383
  console.log("");
74514
- console.log(chalk30.bold(` Hover effects (${prodSide.effects.length} prod / ${candSide.effects.length} cand)`));
75384
+ console.log(chalk31.bold(` Hover effects (${prodSide.effects.length} prod / ${candSide.effects.length} cand)`));
74515
75385
  const nothing = effects.lost.length === 0 && effects.changed.length === 0 && effects.added.length === 0 && effects.unpaired.length === 0;
74516
75386
  if (nothing && !exercised) {
74517
- console.log(chalk30.yellow(" INCONCLUSIVE — no hover changed anything on either side, so nothing was exercised. Check the selector holds an interactive element."));
75387
+ console.log(chalk31.yellow(" INCONCLUSIVE — no hover changed anything on either side, so nothing was exercised. Check the selector holds an interactive element."));
74518
75388
  } else if (nothing) {
74519
75389
  console.log(" clean — every hover that changes something in prod changes the same in cand");
74520
75390
  }
74521
75391
  for (const e of effects.lost) {
74522
- console.log(chalk30.red(` LOST ${e.target}${e.label ? ` (${e.label})` : ""} — prod moves [${e.properties.join(", ")}]; cand's element was hovered and moved nothing`));
75392
+ console.log(chalk31.red(` LOST ${e.target}${e.label ? ` (${e.label})` : ""} — prod moves [${e.properties.join(", ")}]; cand's element was hovered and moved nothing`));
74523
75393
  }
74524
75394
  for (const { prod, extra, notComparable, onElement } of effects.changed) {
74525
75395
  console.log(` DIFFERS ${prod.target}${prod.label ? ` (${prod.label})` : ""}`);
74526
75396
  if (onElement.length) {
74527
- console.log(chalk30.yellow(` prod also moves [${onElement.join(", ")}] on the element itself`));
75397
+ console.log(chalk31.yellow(` prod also moves [${onElement.join(", ")}] on the element itself`));
74528
75398
  }
74529
75399
  if (extra.length)
74530
75400
  console.log(` cand also moves [${extra.join(", ")}]`);
74531
75401
  if (notComparable.length) {
74532
- console.log(chalk30.dim(` not comparable: [${notComparable.join(", ")}] — prod's hover renumbered ${prod.renumberedNodes} of the changed paths, so these were read on elements that are not the same ones before and after. Bench the component, or pick a selector whose subtree the hover does not restructure.`));
75402
+ console.log(chalk31.dim(` not comparable: [${notComparable.join(", ")}] — prod's hover renumbered ${prod.renumberedNodes} of the changed paths, so these were read on elements that are not the same ones before and after. Bench the component, or pick a selector whose subtree the hover does not restructure.`));
74533
75403
  }
74534
75404
  if (onElement.length === 0 && extra.length === 0) {
74535
- console.log(chalk30.dim(" nothing comparable differs."));
75405
+ console.log(chalk31.dim(" nothing comparable differs."));
74536
75406
  }
74537
75407
  }
74538
75408
  for (const e of effects.unpaired) {
74539
- console.log(chalk30.dim(` UNPAIRED ${e.target}${e.label ? ` (${e.label})` : ""} — prod moves [${e.properties.join(", ")}]; no matching element found on the cand side (not a defect — the port may have changed the element, or it is outside --selector)`));
75409
+ console.log(chalk31.dim(` UNPAIRED ${e.target}${e.label ? ` (${e.label})` : ""} — prod moves [${e.properties.join(", ")}]; no matching element found on the cand side (not a defect — the port may have changed the element, or it is outside --selector)`));
74540
75410
  }
74541
75411
  for (const e of effects.added) {
74542
75412
  console.log(` ADDED ${e.target} — cand moves [${e.properties.join(", ")}]; prod does not`);
74543
75413
  }
74544
75414
  if (effects.unpaired.length > 0 && effects.lost.length === 0 && effects.changed.length === 0) {
74545
75415
  console.log("");
74546
- console.log(chalk30.yellow(` ${effects.unpaired.length} prod effect(s) had no counterpart and NOTHING paired. That is a pairing failure, not a set of defects — check --selector contains the same component on both sides, and that ported roots carry data-section.`));
75416
+ console.log(chalk31.yellow(` ${effects.unpaired.length} prod effect(s) had no counterpart and NOTHING paired. That is a pairing failure, not a set of defects — check --selector contains the same component on both sides, and that ported roots carry data-section.`));
74547
75417
  }
74548
75418
  if (prodSide.ambient > 0 || candSide.ambient > 0) {
74549
- console.log(chalk30.dim(` ${prodSide.ambient} prod / ${candSide.ambient} cand node+property pair(s) were moving with no interaction (carousel, autoplaying video, anything on a timer) and were subtracted. A large count means --selector contains something animating on its own; narrow it.`));
75419
+ console.log(chalk31.dim(` ${prodSide.ambient} prod / ${candSide.ambient} cand node+property pair(s) were moving with no interaction (carousel, autoplaying video, anything on a timer) and were subtracted. A large count means --selector contains something animating on its own; narrow it.`));
74550
75420
  }
74551
75421
  if (prodSide.truncated || candSide.truncated) {
74552
- console.log(chalk30.dim(" TRUNCATED — element cap hit; absence of a finding is not proof"));
75422
+ console.log(chalk31.dim(" TRUNCATED — element cap hit; absence of a finding is not proof"));
74553
75423
  }
74554
75424
  return inconclusive || effects.lost.length > 0 || (motion?.findings.length ?? 0) > 0 ? 1 : 0;
74555
75425
  } finally {
@@ -74560,7 +75430,7 @@ async function statesCommand(opts) {
74560
75430
  }
74561
75431
 
74562
75432
  // src/commands/variance.ts
74563
- import chalk31 from "chalk";
75433
+ import chalk32 from "chalk";
74564
75434
 
74565
75435
  // src/diff/variance.ts
74566
75436
  var uniq2 = (xs) => [...new Set(xs)];
@@ -74664,7 +75534,7 @@ function formatVariance(report, opts = {}) {
74664
75534
  // src/commands/variance.ts
74665
75535
  function varianceCommand(opts) {
74666
75536
  if (opts.runIds.length < 2) {
74667
- console.error(chalk31.red(" informe pelo menos 2 runs: parity variance <runIdA> <runIdB> [...]"));
75537
+ console.error(chalk32.red(" informe pelo menos 2 runs: parity variance <runIdA> <runIdB> [...]"));
74668
75538
  return 2;
74669
75539
  }
74670
75540
  const budget = Number.parseFloat(opts.scoreBudget ?? "1");
@@ -74673,7 +75543,7 @@ function varianceCommand(opts) {
74673
75543
  try {
74674
75544
  runs.push(loadRun(opts.output, id));
74675
75545
  } catch (err) {
74676
- console.error(chalk31.red(` ✖ ${err.message}`));
75546
+ console.error(chalk32.red(` ✖ ${err.message}`));
74677
75547
  return 2;
74678
75548
  }
74679
75549
  }
@@ -74682,7 +75552,7 @@ function varianceCommand(opts) {
74682
75552
  console.log(JSON.stringify({ ...report, stable: isStable(report, budget), scoreBudget: budget }));
74683
75553
  } else {
74684
75554
  console.log("");
74685
- console.log(chalk31.bold(" Score variance"));
75555
+ console.log(chalk32.bold(" Score variance"));
74686
75556
  for (const line of formatVariance(report, { scoreBudget: budget }).split(`
74687
75557
  `)) {
74688
75558
  console.log(` ${line}`);
@@ -74694,10 +75564,10 @@ function varianceCommand(opts) {
74694
75564
  }
74695
75565
 
74696
75566
  // src/commands/vitals.ts
74697
- import { existsSync as existsSync31, readFileSync as readFileSync36, writeFileSync as writeFileSync31 } from "node:fs";
75567
+ import { existsSync as existsSync31, readFileSync as readFileSync37, writeFileSync as writeFileSync32 } from "node:fs";
74698
75568
  import { availableParallelism } from "node:os";
74699
75569
  import { join as join41 } from "node:path";
74700
- import chalk32 from "chalk";
75570
+ import chalk33 from "chalk";
74701
75571
  import ora9 from "ora";
74702
75572
 
74703
75573
  // src/checks/agentic-nav.ts
@@ -74995,10 +75865,10 @@ async function vitalsCommand(opts) {
74995
75865
  const runId = newRunId();
74996
75866
  const paths = createRunDir(opts.output, runId);
74997
75867
  const t0 = Date.now();
74998
- console.log(chalk32.bold(`
75868
+ console.log(chalk33.bold(`
74999
75869
  parity vitals ${runId}`));
75000
- console.log(chalk32.dim(` prod: ${opts.prod}`));
75001
- console.log(chalk32.dim(` cand: ${opts.cand}`));
75870
+ console.log(chalk33.dim(` prod: ${opts.prod}`));
75871
+ console.log(chalk33.dim(` cand: ${opts.cand}`));
75002
75872
  const discoverSpinner = ora9("Descobrindo páginas…").start();
75003
75873
  const pagePaths = await discoverPagePaths2(opts.prod, opts);
75004
75874
  if (pagePaths.length === 0) {
@@ -75030,7 +75900,7 @@ async function vitalsCommand(opts) {
75030
75900
  completed++;
75031
75901
  const elapsed = ((Date.now() - t0) / 1000).toFixed(0);
75032
75902
  const etaSec = completed > 0 ? Math.round((Date.now() - t0) / completed * (total - completed) / 1000) : 0;
75033
- progress.text = `${completed}/${total} · ${elapsed}s · ETA ${etaSec}s · ${task.side === "prod" ? chalk32.cyan("prod") : chalk32.magenta("cand")} ${task.path} (${task.viewport})`;
75903
+ progress.text = `${completed}/${total} · ${elapsed}s · ETA ${etaSec}s · ${task.side === "prod" ? chalk33.cyan("prod") : chalk33.magenta("cand")} ${task.path} (${task.viewport})`;
75034
75904
  }
75035
75905
  });
75036
75906
  progress.succeed(`${total} capture(s) em ${((Date.now() - t0) / 1000).toFixed(1)}s`);
@@ -75059,7 +75929,7 @@ async function vitalsCommand(opts) {
75059
75929
  }
75060
75930
  lhCompleted++;
75061
75931
  const elapsed = ((Date.now() - lhT0) / 1000).toFixed(0);
75062
- lhProgress.text = `Lighthouse ${lhCompleted}/${done.length} · ${elapsed}s · ${task.side === "prod" ? chalk32.cyan("prod") : chalk32.magenta("cand")} ${task.path} (${task.viewport})`;
75932
+ lhProgress.text = `Lighthouse ${lhCompleted}/${done.length} · ${elapsed}s · ${task.side === "prod" ? chalk33.cyan("prod") : chalk33.magenta("cand")} ${task.path} (${task.viewport})`;
75063
75933
  });
75064
75934
  lhProgress.succeed(`Lighthouse ${done.length} página(s) em ${((Date.now() - lhT0) / 1000).toFixed(1)}s`);
75065
75935
  }
@@ -75124,7 +75994,7 @@ async function vitalsCommand(opts) {
75124
75994
  writeRunReportJson(paths.runDir, run);
75125
75995
  const html = renderHtmlReport(run, paths.runDir);
75126
75996
  writeRunReportHtml(paths.runDir, html);
75127
- writeFileSync31(join41(paths.runDir, "vitals.json"), `${JSON.stringify({
75997
+ writeFileSync32(join41(paths.runDir, "vitals.json"), `${JSON.stringify({
75128
75998
  schemaVersion: "0.1",
75129
75999
  prodUrl: opts.prod,
75130
76000
  candUrl: opts.cand,
@@ -75137,8 +76007,8 @@ async function vitalsCommand(opts) {
75137
76007
  `, "utf8");
75138
76008
  printSummary8(vitalsResult, cacheResult, scoresResult, oppsResult, agenticResult);
75139
76009
  console.log("");
75140
- console.log(chalk32.dim(` → ${paths.reportHtml}`));
75141
- console.log(chalk32.dim(` \uD83D\uDCA1 use 'parity serve ${runId}' pra preview iframe`));
76010
+ console.log(chalk33.dim(` → ${paths.reportHtml}`));
76011
+ console.log(chalk33.dim(` \uD83D\uDCA1 use 'parity serve ${runId}' pra preview iframe`));
75142
76012
  console.log("");
75143
76013
  if (opts.open) {
75144
76014
  const { default: open } = await import("open");
@@ -75229,14 +76099,14 @@ function parseUrlList(input) {
75229
76099
  if (input.startsWith("file:") || input.endsWith(".txt") || input.endsWith(".list")) {
75230
76100
  const path = input.replace(/^file:\/\//, "");
75231
76101
  if (existsSync31(path)) {
75232
- return readFileSync36(path, "utf8").split(/\r?\n/).map((s) => s.trim()).filter((s) => s && !s.startsWith("#")).map((s) => s.startsWith("/") ? s : `/${s}`);
76102
+ return readFileSync37(path, "utf8").split(/\r?\n/).map((s) => s.trim()).filter((s) => s && !s.startsWith("#")).map((s) => s.startsWith("/") ? s : `/${s}`);
75233
76103
  }
75234
76104
  }
75235
76105
  return input.split(",").map((s) => s.trim()).filter(Boolean).map((s) => s.startsWith("/") || s.startsWith("http") ? s : `/${s}`);
75236
76106
  }
75237
76107
  function printSummary8(vitals, cache, scores, opportunities, agentic) {
75238
76108
  console.log("");
75239
- console.log(chalk32.bold(" Summary:"));
76109
+ console.log(chalk33.bold(" Summary:"));
75240
76110
  console.log(` ${vitals.summary}`);
75241
76111
  console.log(` ${cache.summary}`);
75242
76112
  if (scores.status !== "skipped")
@@ -75528,6 +76398,20 @@ program.command("check").argument("<name>", "check name (kebab-case, e.g. consol
75528
76398
  json: opts.json
75529
76399
  }));
75530
76400
  });
76401
+ program.command("heatmap").description("Is the candidate PIXEL-IDENTICAL to prod — yes, no, or 'nothing was compared'. Zero tolerance, no LLM, no flag to loosen it: one differing pixel fails. Sweeps mobile→2560px so a broken breakpoint cannot hide at the one size you checked, and captures prod twice first so a page that is not identical to itself reports its own noise floor instead of blaming the candidate. Use `parity section` to find out WHY something differs; use this to decide WHETHER it does.").requiredOption("--prod <url>", "Production URL (the reference)").requiredOption("--cand <url>", "Candidate URL").option("--selector <sel>", "Compare only this section instead of the whole page. Without it the comparison is full-page.").option("--cand-selector <sel>", "Selector on the CANDIDATE side, when the ported component no longer answers to --selector. Defaults to --selector.").option("--viewports <list>", "Comma-separated. Each entry is a preset (mobile|tablet|desktop) or a literal <width>x<height>. Every entry must be clean for the run to pass.", DEFAULT_VIEWPORTS).option("--wait <ms>", "Extra ms after networkidle so hydration settles", "2000").option("--pr <number>", "Publish the verdict as a PR comment, with the diff images inline. Reporting only — a failure to publish never changes the verdict or the exit code.").option("--repo <owner/name>", "Repo for --pr. Defaults to whatever `gh` infers from the cwd.").option("--out-dir <dir>", "Where to write the screenshots and heatmaps", "./parity-output/heatmap").option("--json", "Emit one-line JSON instead of pretty text", false).action(async (opts) => {
76402
+ process.exit(await heatmapCommand({
76403
+ prod: opts.prod,
76404
+ cand: opts.cand,
76405
+ selector: opts.selector,
76406
+ candSelector: opts.candSelector,
76407
+ viewports: opts.viewports,
76408
+ wait: opts.wait,
76409
+ pr: opts.pr,
76410
+ repo: opts.repo,
76411
+ outDir: opts.outDir,
76412
+ json: opts.json
76413
+ }));
76414
+ });
75531
76415
  program.command("section").description("Focused prod×cand comparison of one section: HTML diff + screenshot + computed-styles diff, plus an opt-in numeric box-tree diff (--box-tree). No flags = all 3 facets. Designed for the 'in DOM but invisible' debug loop (issue #31).").requiredOption("--prod <url>", "Production URL (base, e.g. https://www.example.com)").requiredOption("--cand <url>", "Candidate URL (base, e.g. https://example.deco-cx.workers.dev)").requiredOption("--selector <sel>", "CSS selector for the section to compare").option("--cand-selector <sel>", "CSS selector on the CANDIDATE side, when the ported component no longer matches --selector (VTEX IO class names → hashed CSS Modules, data-fs-* attributes, …). Defaults to --selector.").option("--output-html", "Include the HTML diff facet (default: on if no facet flag passed)", false).option("--screenshot", "Include the screenshot facet (locator screenshot per side)", false).option("--computed-styles", "Include the computed-styles diff facet", false).option("--heatmap", "Run pixelmatch on the two screenshots and analyze diff regions (bounding box + hotspots). Implies --screenshot.", false).option("--box-tree", "Walk the selector's whole subtree on both sides and report numeric box deltas, biggest first (`margin-top: 32px → 24px -8`). Deterministic, no LLM — this is the answer to 'everything is a little off', which a pixelmatch percentage and a vision paragraph cannot give.", false).option("--css-source", "For each divergent computed-style property, resolve which CSS rule (stylesheet + selector) produced it via CDP. Useful when the LLM needs to know which file to edit.", false).option("--prompt", "Emit an LLM-ready bundle: <prefix>-bundle.json (machine-readable) + <prefix>-prompt.md (opinionated Markdown with embedded images). Implies all signals.", false).option("--llm-summary", "After building the bundle, invoke Claude (needs ANTHROPIC_API_KEY) and print a 1-paragraph 'what I understood' summary. Does NOT generate a patch. Implies --prompt.", false).option("--all", "Turn on every diagnostic facet at once (html + screenshot + computed-styles + heatmap + css-source + prompt + llm-summary) — the pixel-perfect debug shortcut formerly known as `parity fix`. Issue #415.", false).option("--no-llm", "With --all, skip the LLM call (still writes the markdown bundle). Use when offline or to avoid API costs.").option("--viewport <viewport>", "mobile | desktop | tablet", "mobile").option("--wait <ms>", "Extra ms after networkidle so hydration settles", "2000").option("--out-dir <dir>", "Where to write the screenshots", "./parity-output/sections").option("--plan-dir <dir>", "Run dir holding migration-plan.json. Its component rows are the only place the prod-side spelling of a component (`site/sections/Hero/HeroBannerV2.tsx`) and the cand-side one (`HeroSlideshow`) are written down together, so reading it lets the label pass pair nodes whose markup does not agree. Without it, unlabelled nodes fall back to the structural path.").option("--json", "Emit one-line JSON instead of pretty text", false).action(async (opts) => {
75532
76416
  process.exit(await sectionCommand({
75533
76417
  planDir: opts.planDir,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.33.33",
3
+ "version": "0.33.35",
4
4
  "description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with an LLM-ranked HTML report.",
5
5
  "type": "module",
6
6
  "license": "MIT",