@decocms/parity 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0](https://github.com/decocms/parity/compare/v0.2.0...v0.3.0) (2026-05-26)
+
+
+### Added
+
+* **journey:** retry `go-checkout` via LLM recovery when the default selector clicks the wrong element and the URL never reaches `/checkout` ([5826d30](https://github.com/decocms/parity/commit/5826d309c6a910f8cf8017667cdcdcebd65f65d9))
+* **journey:** LLM recovery on `cep-pdp` + `cep-cart` when defaults miss the CEP input ([624b0f5](https://github.com/decocms/parity/commit/624b0f5acbe1c50fce2bea69faa6906e29d36e64))
+* **journey:** per-flow hard deadline so a single hung flow can't freeze the whole crawl ([e2d4a68](https://github.com/decocms/parity/commit/e2d4a681a5d4f0a9627251eceb1e733d12bdc68d))
+
+
+### Fixed
+
+* **journey:** abort in-flight Playwright ops when the deadline fires, instead of letting them mutate the next flow's shared BrowserContext ([a21aa78](https://github.com/decocms/parity/commit/a21aa78a4431e7a2cff9aac26ac34c4ca2fa768c))
+* **journey:** seal the timeout FlowCapture synchronously so Promise.race can't pick up the inner rejection caused by closing pages ([d2a0f1e](https://github.com/decocms/parity/commit/d2a0f1e7a08bf95a28a951bace322c5baf062bea))
+* **journey:** await timeout cleanup before runFlow returns so the next flow on the same context isn't racing in-flight close()s ([a2fd6c2](https://github.com/decocms/parity/commit/a2fd6c2e7e7a9eb493d2cb75d08f3d5cc7cc3f91))
+
+## [0.2.0](https://github.com/decocms/parity/compare/v0.1.1...v0.2.0) (2026-05-26)
+
+
+### Added
+
+* **css-trace:** inspect CSS rules affecting a DOM element ([1e323fa](https://github.com/decocms/parity/commit/1e323fa17564045d5f55bfbc5cbf2fcdb0112877))
+
+
+### Fixed
+
+* **capture:** hard outer deadline so capturePage cannot exceed budget+10s ([966b9a5](https://github.com/decocms/parity/commit/966b9a59851536262b88510da6175a215c90d0b2))
+* **capture:** hard outer deadline so capturePage cannot exceed budget+10s ([ea61116](https://github.com/decocms/parity/commit/ea61116c81fb1ec86e86ddb24216214380a81c81))
+* **lint:** replace 3 template literals without interpolation with strings ([c60f19c](https://github.com/decocms/parity/commit/c60f19c4a56c8441ead829fca0998ee36a671872))
+
 ## [Unreleased]
 
 ## [0.1.1] — 2026-05-22

package/dist/cli.js

@@ -1118,63 +1118,7 @@ async function capturePage(page, opts) {
   const overallBudgetMs = opts.fast ? 25000 : 60000;
   const deadline = start + overallBudgetMs;
   const remaining = () => Math.max(500, deadline - Date.now());
-  let response = null;
-  let finalUrl = opts.url;
-  let xRobotsTag = null;
-  try {
-    response = await page.goto(opts.url, {
-      waitUntil: "domcontentloaded",
-      timeout: Math.min(opts.timeoutMs ?? 30000, remaining())
-    });
-    finalUrl = page.url();
-    if (response) {
-      const headers = response.headers();
-      xRobotsTag = headers["x-robots-tag"] ?? null;
-    }
-    if (opts.fast) {
-      await page.waitForLoadState("networkidle", { timeout: Math.min(4000, remaining()) }).catch(() => {
-        return;
-      });
-      await page.waitForTimeout(Math.min(opts.settleMs ?? 1200, remaining()));
-    } else {
-      await page.waitForLoadState("load", { timeout: Math.min(12000, remaining()) }).catch(() => {
-        return;
-      });
-      await page.waitForLoadState("networkidle", { timeout: Math.min(6000, remaining()) }).catch(() => {
-        return;
-      });
-      await page.waitForTimeout(Math.min(opts.settleMs ?? 2000, remaining()));
-      if (opts.scrollToLoad !== false && remaining() > 3000) {
-        await Promise.race([
-          scrollFullPage(page).catch(() => {
-            return;
-          }),
-          new Promise((resolve) => setTimeout(resolve, Math.min(1e4, remaining())))
-        ]);
-        await page.waitForTimeout(Math.min(600, remaining()));
-      }
-    }
-  } catch (err) {
-    state.console.push({
-      type: "error",
-      text: `[navigation-error] ${err.message}`
-    });
-  }
-  const vitals = await page.evaluate(() => window.__parity_vitals).catch(() => null);
-  if (!opts.skipScreenshot) {
-    await Promise.race([
-      page.screenshot({ path: opts.screenshotPath, fullPage: true, animations: "disabled" }).catch(() => {
-        return;
-      }),
-      new Promise((resolve) => setTimeout(resolve, Math.min(15000, remaining())))
-    ]);
-  }
-  const html = await Promise.race([
-    page.content().catch(() => ""),
-    new Promise((resolve) => setTimeout(() => resolve(""), Math.min(5000, remaining())))
-  ]);
-  await flushCollectors(state, Math.min(3000, remaining()));
-  return {
+  const buildPartial = () => ({
     url: opts.url,
     finalUrl,
     status: response?.status() ?? 0,
@@ -1189,7 +1133,83 @@ async function capturePage(page, opts) {
     harPath: opts.harPath,
     tracePath: opts.tracePath,
     xRobotsTag
+  });
+  let response = null;
+  let finalUrl = opts.url;
+  let xRobotsTag = null;
+  let vitals = null;
+  let html = "";
+  const inner = async () => {
+    try {
+      response = await page.goto(opts.url, {
+        waitUntil: "domcontentloaded",
+        timeout: Math.min(opts.timeoutMs ?? 30000, remaining())
+      });
+      finalUrl = page.url();
+      if (response) {
+        const headers = response.headers();
+        xRobotsTag = headers["x-robots-tag"] ?? null;
+      }
+      if (opts.fast) {
+        await page.waitForLoadState("networkidle", { timeout: Math.min(4000, remaining()) }).catch(() => {
+          return;
+        });
+        await page.waitForTimeout(Math.min(opts.settleMs ?? 1200, remaining()));
+      } else {
+        await page.waitForLoadState("load", { timeout: Math.min(12000, remaining()) }).catch(() => {
+          return;
+        });
+        await page.waitForLoadState("networkidle", { timeout: Math.min(6000, remaining()) }).catch(() => {
+          return;
+        });
+        await page.waitForTimeout(Math.min(opts.settleMs ?? 2000, remaining()));
+        if (opts.scrollToLoad !== false && remaining() > 3000) {
+          await Promise.race([
+            scrollFullPage(page).catch(() => {
+              return;
+            }),
+            new Promise((resolve) => setTimeout(resolve, Math.min(1e4, remaining())))
+          ]);
+          await page.waitForTimeout(Math.min(600, remaining()));
+        }
+      }
+    } catch (err) {
+      state.console.push({
+        type: "error",
+        text: `[navigation-error] ${err.message}`
+      });
+    }
+    vitals = await Promise.race([
+      page.evaluate(() => window.__parity_vitals).catch(() => null),
+      new Promise((resolve) => setTimeout(() => resolve(null), Math.min(5000, remaining())))
+    ]) ?? null;
+    if (!opts.skipScreenshot) {
+      await Promise.race([
+        page.screenshot({ path: opts.screenshotPath, fullPage: true, animations: "disabled" }).catch(() => {
+          return;
+        }),
+        new Promise((resolve) => setTimeout(resolve, Math.min(15000, remaining())))
+      ]);
+    }
+    html = await Promise.race([
+      page.content().catch(() => ""),
+      new Promise((resolve) => setTimeout(() => resolve(""), Math.min(5000, remaining())))
+    ]);
+    await flushCollectors(state, Math.min(3000, remaining()));
+    return buildPartial();
   };
+  const SAFETY_MARGIN_MS = 1e4;
+  const outerDeadlineMs = overallBudgetMs + SAFETY_MARGIN_MS;
+  return Promise.race([
+    inner(),
+    new Promise((resolve) => setTimeout(() => {
+      state.console.push({
+        type: "error",
+        text: `[capture-timeout] capturePage exceeded ${outerDeadlineMs}ms outer deadline — returning partial capture`
+      });
+      resolve(buildPartial());
+    }, outerDeadlineMs))
+  ]);
 }
 
 // src/report/render.ts
@@ -4084,8 +4104,257 @@ Regressões (severity piorou):`));
   }
 }
 
-// src/commands/explain.ts
+// src/commands/css-trace.ts
 import chalk4 from "chalk";
+async function tracePage(page, url, selector, settleMs) {
+  await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
+  await page.waitForLoadState("load", { timeout: 12000 }).catch(() => {
+    return;
+  });
+  await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {
+    return;
+  });
+  await page.waitForTimeout(settleMs);
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send("DOM.enable");
+  await cdp.send("CSS.enable");
+  const { root } = await cdp.send("DOM.getDocument", { depth: -1 });
+  const found = await cdp.send("DOM.querySelector", {
+    nodeId: root.nodeId,
+    selector
+  });
+  if (!found.nodeId) {
+    await cdp.detach();
+    return { url, selector, found: false, computed: {}, rules: [] };
+  }
+  const computedResult = await cdp.send("CSS.getComputedStyleForNode", {
+    nodeId: found.nodeId
+  });
+  const computed = {};
+  for (const e of computedResult.computedStyle)
+    computed[e.name] = e.value;
+  const matched = await cdp.send("CSS.getMatchedStylesForNode", {
+    nodeId: found.nodeId
+  });
+  const sheetUrlCache = new Map;
+  async function sheetSource(styleSheetId, origin) {
+    if (!styleSheetId) {
+      if (origin === "user-agent")
+        return "user-agent";
+      return "inline";
+    }
+    if (sheetUrlCache.has(styleSheetId))
+      return sheetUrlCache.get(styleSheetId);
+    try {
+      const header = await cdp.send("CSS.getStyleSheetText", {
+        styleSheetId
+      });
+      const preview = header.text.replace(/\s+/g, " ").trim().slice(0, 100);
+      const label = `stylesheet#${styleSheetId} (${preview})`;
+      sheetUrlCache.set(styleSheetId, label);
+      return label;
+    } catch {
+      const label = `stylesheet#${styleSheetId}`;
+      sheetUrlCache.set(styleSheetId, label);
+      return label;
+    }
+  }
+  const buildRule = async (m, inheritedFromDistance) => {
+    const r = m.rule;
+    const selectors = r.selectorList.selectors.map((s) => s.text);
+    const matchedSelectors = m.matchingSelectors.map((i) => selectors[i]).filter(Boolean);
+    const sel = matchedSelectors.join(", ") || selectors.join(", ") || "(no selector text)";
+    const source = await sheetSource(r.styleSheetId, r.origin);
+    return {
+      source,
+      selector: sel,
+      properties: (r.style.cssProperties ?? []).filter((p) => p.name && p.value && !p.disabled).map((p) => {
+        const trimmed = p.value.replace(/\s*!important\s*$/i, "").trim();
+        return {
+          name: p.name,
+          value: trimmed || p.value,
+          important: p.important === true || /\s*!important\s*$/i.test(p.value),
+          disabled: p.disabled
+        };
+      }),
+      ...inheritedFromDistance !== undefined ? { inheritedFromDistance } : {}
+    };
+  };
+  const rules = [];
+  for (const m of matched.matchedCSSRules ?? []) {
+    rules.push(await buildRule(m));
+  }
+  const inheritedGroups = matched.inherited ?? [];
+  for (let i = 0;i < inheritedGroups.length; i++) {
+    const group = inheritedGroups[i];
+    if (!group?.matchedCSSRules?.length)
+      continue;
+    const distance = i + 1;
+    for (const m of group.matchedCSSRules) {
+      rules.push(await buildRule(m, distance));
+    }
+  }
+  await cdp.detach();
+  return { url, selector, found: true, computed, rules };
+}
+function applyFilter(result, filter) {
+  if (!filter)
+    return result;
+  const wanted = new Set(filter.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean));
+  const computed = {};
+  for (const [k, v] of Object.entries(result.computed)) {
+    if (wanted.has(k.toLowerCase()))
+      computed[k] = v;
+  }
+  const rules = result.rules.map((r) => ({
+    ...r,
+    properties: r.properties.filter((p) => wanted.has(p.name.toLowerCase()))
+  })).filter((r) => r.properties.length > 0);
+  return { ...result, computed, rules };
+}
+function printResult(result, header) {
+  console.log(chalk4.bold(`
+${header}`));
+  console.log(chalk4.dim(`URL: ${result.url}`));
+  console.log(chalk4.dim(`Selector: ${result.selector}`));
+  if (!result.found) {
+    console.log(chalk4.red("✖ Element not found"));
+    return;
+  }
+  const computedKeys = Object.keys(result.computed);
+  if (computedKeys.length > 0) {
+    console.log(chalk4.bold(`
+  Computed:`));
+    for (const k of computedKeys) {
+      console.log(`    ${chalk4.cyan(k)}: ${result.computed[k]}`);
+    }
+  }
+  if (result.rules.length === 0) {
+    console.log(chalk4.yellow(`
+  No matching rules after filter.`));
+    return;
+  }
+  console.log(chalk4.bold(`
+  Rules (ordered by CDP — most specific last):`));
+  for (const r of result.rules) {
+    const inheritLabel = r.inheritedFromDistance !== undefined ? chalk4.yellow(` ↑ inherited from ancestor (${r.inheritedFromDistance})`) : "";
+    console.log(`    ${chalk4.magenta(r.source)}${inheritLabel}`);
+    console.log(`      ${chalk4.green(r.selector)} {`);
+    for (const p of r.properties) {
+      const bang = p.important ? chalk4.red(" !important") : "";
+      console.log(`        ${p.name}: ${p.value}${bang};`);
+    }
+    console.log("      }");
+  }
+}
+function diffComputed(prod, cand) {
+  const keys = new Set([...Object.keys(prod.computed), ...Object.keys(cand.computed)]);
+  const out = [];
+  for (const k of keys) {
+    const p = prod.computed[k];
+    const c = cand.computed[k];
+    if (p !== c)
+      out.push({ property: k, prod: p, cand: c });
+  }
+  return out.sort((a, b) => a.property.localeCompare(b.property));
+}
+function printComparison(prod, cand) {
+  printResult(prod, "── PROD ──────────────────────────────────────────────");
+  printResult(cand, "── CAND ──────────────────────────────────────────────");
+  const diffs = diffComputed(prod, cand);
+  console.log(chalk4.bold(`
+── DIFF (computed) ───────────────────────────────────`));
+  if (diffs.length === 0) {
+    console.log(chalk4.green("  No computed-style differences in the filtered set."));
+    return;
+  }
+  for (const d of diffs) {
+    console.log(`  ${chalk4.cyan(d.property)}`);
+    console.log(`    prod: ${chalk4.green(d.prod ?? "(unset)")}`);
+    console.log(`    cand: ${chalk4.red(d.cand ?? "(unset)")}`);
+  }
+}
+async function cssTraceCommand(opts) {
+  const viewport = opts.viewport ?? "desktop";
+  const settleMs = opts.settleMs ?? 1500;
+  if (!opts.selector) {
+    console.error(chalk4.red("--selector is required"));
+    return 1;
+  }
+  const hasUrl = !!opts.url;
+  const hasProd = !!opts.prod;
+  const hasCand = !!opts.cand;
+  if (hasUrl && (hasProd || hasCand)) {
+    console.error(chalk4.red("--url is mutually exclusive with --prod / --cand. Pass one mode only."));
+    return 1;
+  }
+  if (hasProd && !hasCand || !hasProd && hasCand) {
+    console.error(chalk4.red("Comparison mode needs both --prod and --cand (got only one)."));
+    return 1;
+  }
+  if (!hasUrl && !hasProd && !hasCand) {
+    console.error(chalk4.red("Provide either --url or both --prod and --cand."));
+    return 1;
+  }
+  const isCompare = hasProd && hasCand;
+  let browser = null;
+  try {
+    browser = await launchBrowser({ headless: true });
+    if (isCompare) {
+      const prodCtx = await newContext(browser, { viewport });
+      const candCtx = await newContext(browser, { viewport });
+      const prodPage = await prodCtx.newPage();
+      const candPage = await candCtx.newPage();
+      try {
+        const [prodRes, candRes] = await Promise.all([
+          tracePage(prodPage, opts.prod, opts.selector, settleMs),
+          tracePage(candPage, opts.cand, opts.selector, settleMs)
+        ]);
+        const prodF = applyFilter(prodRes, opts.filter);
+        const candF = applyFilter(candRes, opts.filter);
+        if (opts.json) {
+          console.log(JSON.stringify({ prod: prodF, cand: candF, diff: diffComputed(prodF, candF) }, null, 2));
+        } else {
+          printComparison(prodF, candF);
+        }
+      } finally {
+        await prodCtx.close().catch(() => {
+          return;
+        });
+        await candCtx.close().catch(() => {
+          return;
+        });
+      }
+    } else {
+      const ctx = await newContext(browser, { viewport });
+      const page = await ctx.newPage();
+      try {
+        const res = await tracePage(page, opts.url, opts.selector, settleMs);
+        const filtered = applyFilter(res, opts.filter);
+        if (opts.json) {
+          console.log(JSON.stringify(filtered, null, 2));
+        } else {
+          printResult(filtered, "── RESULT ────────────────────────────────────────────");
+        }
+      } finally {
+        await ctx.close().catch(() => {
+          return;
+        });
+      }
+    }
+    return 0;
+  } catch (err) {
+    console.error(chalk4.red(`Error: ${err.message}`));
+    return 1;
+  } finally {
+    await browser?.close().catch(() => {
+      return;
+    });
+  }
+}
+
+// src/commands/explain.ts
+import chalk5 from "chalk";
 
 // src/llm/client.ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -4394,17 +4663,17 @@ Cada issue tem:
 // src/commands/explain.ts
 async function explainCommand(runId, issueId, output) {
   if (!isLlmAvailable()) {
-    console.error(chalk4.red("Nenhuma API key de LLM encontrada — set ANTHROPIC_API_KEY ou OPENROUTER_API_KEY."));
+    console.error(chalk5.red("Nenhuma API key de LLM encontrada — set ANTHROPIC_API_KEY ou OPENROUTER_API_KEY."));
     return 1;
   }
   const run = loadRun(output, runId);
   const issue = run.issues.find((i) => i.id === issueId) || run.topIssues.find((i) => i.id === issueId);
   if (!issue) {
-    console.error(chalk4.red(`Issue não encontrada: ${issueId}`));
+    console.error(chalk5.red(`Issue não encontrada: ${issueId}`));
     return 1;
   }
   const checks = run.checks.filter((c) => c.issues.some((i) => i.id === issueId || i.check === issue.check));
-  console.log(chalk4.dim(`Consultando LLM…
+  console.log(chalk5.dim(`Consultando LLM…
 `));
   const text = await callMessage({
     systemPrompt: ISSUE_AGGREGATOR_SYSTEM_PROMPT,
@@ -4425,7 +4694,7 @@ ${JSON.stringify(checks.map((c) => ({ name: c.name, status: c.status, summary: c
 // src/commands/journey.ts
 import { writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join7 } from "node:path";
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 import ora2 from "ora";
 
 // src/llm/pick-plp.ts
@@ -4790,19 +5059,60 @@ var PURCHASE_JOURNEY_TOTAL_STEPS = 8;
 function selFor(ctx, key) {
   return selectorsFor(key, { rc: ctx.rc, learned: ctx.learned, platform: ctx.platform });
 }
+var FLOW_DEADLINE_MS = {
+  homepage: 90000,
+  plp: 180000,
+  pdp: 240000,
+  "purchase-journey": 360000
+};
 async function runFlow(flow, ctx) {
   const start = Date.now();
-  switch (flow) {
-    case "homepage":
-      return finalize(flow, ctx, await flowHomepage(ctx), [], start);
-    case "plp":
-      return finalize(flow, ctx, await flowPlp(ctx), [], start);
-    case "pdp":
-      return finalize(flow, ctx, await flowPdp(ctx), [], start);
-    case "purchase-journey": {
-      const { pages, steps } = await flowPurchaseJourney(ctx);
-      return finalize(flow, ctx, pages, steps, start);
+  const deadlineMs = FLOW_DEADLINE_MS[flow];
+  const inner = async () => {
+    switch (flow) {
+      case "homepage":
+        return finalize(flow, ctx, await flowHomepage(ctx), [], start);
+      case "plp":
+        return finalize(flow, ctx, await flowPlp(ctx), [], start);
+      case "pdp":
+        return finalize(flow, ctx, await flowPdp(ctx), [], start);
+      case "purchase-journey": {
+        const { pages, steps } = await flowPurchaseJourney(ctx);
+        return finalize(flow, ctx, pages, steps, start);
+      }
     }
+  };
+  const innerPromise = inner();
+  innerPromise.catch(() => {
+    return;
+  });
+  let timer;
+  let cleanup = Promise.resolve();
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      const pages = ctx.ctx.pages();
+      resolve(finalize(flow, ctx, [], [
+        {
+          step: 0,
+          name: "visit-home",
+          side: ctx.side,
+          viewport: ctx.viewport,
+          status: "failed",
+          durationMs: deadlineMs,
+          screenshotPath: "",
+          actionDescription: `[flow-timeout] flow "${flow}" excedeu ${deadlineMs}ms — captura abortada pela safety net externa, ${pages.length} page(s) fechada(s) para liberar o contexto. Step interno provavelmente travou em uma operação Playwright que não respeitou seu timeout declarado.`
+        }
+      ], start));
+      cleanup = Promise.allSettled(pages.map((p) => p.close()));
+    }, deadlineMs);
+  });
+  try {
+    const result = await Promise.race([innerPromise, timeoutPromise]);
+    await cleanup;
+    return result;
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
   }
 }
 function finalize(flow, ctx, pages, steps, start) {
@@ -4995,7 +5305,16 @@ async function flowPurchaseJourney(ctx) {
     steps[steps.length - 1].actionDescription = `Abriu PDP \`${pdpHit.url}\` (via \`${pdpHit.selector}\`)`;
     steps[steps.length - 1].beforeUrl = plpHit.url;
     reportStart(4, "shipping-calc-pdp");
-    const cepInputPdp = await firstVisible(page, selFor(ctx, "cepInputPdp"));
+    let cepInputPdp = await firstVisible(page, selFor(ctx, "cepInputPdp"));
+    let cepPdpRecovered = false;
+    if (!cepInputPdp && recoveryBudget > 0) {
+      const recovery = await attemptRecovery(page, ctx, "shipping-calc-pdp", "Achar o input de CEP / código postal nesta PDP (deve ser um input visível com label/placeholder relacionado a frete, entrega ou CEP)", selFor(ctx, "cepInputPdp"));
+      if (recovery) {
+        cepInputPdp = recovery.selector;
+        cepPdpRecovered = true;
+        recoveryBudget--;
+      }
+    }
     if (cepInputPdp) {
       const t4 = Date.now();
       const beforeUrl4 = page.url();
@@ -5020,14 +5339,15 @@ async function flowPurchaseJourney(ctx) {
         screenshotPath: sp,
         screenshotBeforePath: spBefore4,
         beforeUrl: beforeUrl4,
-        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no input \`${cepInputPdp}\` e disparou cálculo de frete`,
+        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no input \`${cepInputPdp}\` e disparou cálculo de frete${cepPdpRecovered ? " (selector via LLM recovery)" : ""}`,
         detail: { cepUsed: ctx.rc.cep },
         selectorKey: "cepInputPdp",
-        usedSelector: cepInputPdp
+        usedSelector: cepInputPdp,
+        recoveredByLlm: cepPdpRecovered || undefined
       });
       reportEnd(4, "shipping-calc-pdp", step4Status, Date.now() - t4);
     } else {
-      steps.push(makeSkipStep(4, "shipping-calc-pdp", ctx, "no CEP input on PDP"));
+      steps.push(makeSkipStep(4, "shipping-calc-pdp", ctx, "no CEP input on PDP (recovery exhausted)"));
       reportEnd(4, "shipping-calc-pdp", "skipped", 0, "no CEP input on PDP");
     }
     reportStart(5, "add-to-cart");
@@ -5125,7 +5445,16 @@ async function flowPurchaseJourney(ctx) {
     });
     reportEnd(6, "open-minicart", "ok", Date.now() - t6);
     reportStart(7, "shipping-calc-cart");
-    const cepInputCart = await firstVisible(page, selFor(ctx, "cepInputCart"));
+    let cepInputCart = await firstVisible(page, selFor(ctx, "cepInputCart"));
+    let cepCartRecovered = false;
+    if (!cepInputCart && recoveryBudget > 0) {
+      const recovery = await attemptRecovery(page, ctx, "shipping-calc-cart", "Achar o input de CEP / código postal dentro do carrinho ou minicart aberto agora (input visível com label/placeholder de frete, entrega ou CEP)", selFor(ctx, "cepInputCart"));
+      if (recovery) {
+        cepInputCart = recovery.selector;
+        cepCartRecovered = true;
+        recoveryBudget--;
+      }
+    }
     if (cepInputCart) {
       const t7 = Date.now();
       const beforeUrl7 = page.url();
@@ -5150,14 +5479,15 @@ async function flowPurchaseJourney(ctx) {
         screenshotPath: sp7,
         screenshotBeforePath: spBefore7,
         beforeUrl: beforeUrl7,
-        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no carrinho (\`${cepInputCart}\`)`,
+        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no carrinho (\`${cepInputCart}\`)${cepCartRecovered ? " (selector via LLM recovery)" : ""}`,
         detail: { cepUsed: ctx.rc.cep },
         selectorKey: "cepInputCart",
-        usedSelector: cepInputCart
+        usedSelector: cepInputCart,
+        recoveredByLlm: cepCartRecovered || undefined
       });
       reportEnd(7, "shipping-calc-cart", step7Status, Date.now() - t7);
     } else {
-      steps.push(makeSkipStep(7, "shipping-calc-cart", ctx, "no CEP input in cart"));
+      steps.push(makeSkipStep(7, "shipping-calc-cart", ctx, "no CEP input in cart (recovery exhausted)"));
       reportEnd(7, "shipping-calc-cart", "skipped", 0, "no CEP input in cart");
     }
     reportStart(8, "go-checkout");
@@ -5176,28 +5506,47 @@ async function flowPurchaseJourney(ctx) {
       reportEnd(8, "go-checkout", "skipped", 0, "no checkout button found");
       return { pages, steps };
     }
-    const t8 = Date.now();
-    const beforeUrl8 = page.url();
-    const spBefore8 = screenshotPath(ctx, "pj-8-checkout-before");
-    await page.screenshot({ path: spBefore8, fullPage: false }).catch(() => {
-      return;
-    });
-    const checkoutText = await checkoutHit.locator.innerText().catch(() => "");
-    await Promise.all([
-      page.waitForURL(/checkout/i, { timeout: 1e4 }).catch(() => {
+    const tryCheckoutClick = async (hit, attempt2) => {
+      const spBefore = screenshotPath(ctx, `pj-8-checkout-before-${attempt2}`);
+      await page.screenshot({ path: spBefore, fullPage: false }).catch(() => {
         return;
-      }),
-      checkoutHit.locator.click({ timeout: 5000 }).catch(() => {
+      });
+      const clickedText2 = await hit.locator.innerText().catch(() => "");
+      await Promise.all([
+        page.waitForURL(/checkout/i, { timeout: 1e4 }).catch(() => {
+          return;
+        }),
+        hit.locator.click({ timeout: 5000 }).catch(() => {
+          return;
+        })
+      ]);
+      await page.waitForTimeout(1500);
+      const spAfter = screenshotPath(ctx, `pj-8-checkout-reached-${attempt2}`);
+      await page.screenshot({ path: spAfter, fullPage: false }).catch(() => {
         return;
-      })
-    ]);
-    await page.waitForTimeout(1500);
-    const sp8 = screenshotPath(ctx, "pj-8-checkout-reached");
-    await page.screenshot({ path: sp8, fullPage: false }).catch(() => {
-      return;
-    });
-    const checkoutUrl = page.url();
-    const reachedCheckout = /\/checkout/i.test(checkoutUrl);
+      });
+      return { url: page.url(), spBefore, spAfter, clickedText: clickedText2 };
+    };
+    const t8 = Date.now();
+    const beforeUrl8 = page.url();
+    let attempt = 1;
+    let result = await tryCheckoutClick(checkoutHit, attempt);
+    let reachedCheckout = /\/checkout/i.test(result.url);
+    let usedSelector = checkoutHit.selector;
+    let clickedText = result.clickedText;
+    if (!reachedCheckout && recoveryBudget > 0 && !/\/checkout/i.test(beforeUrl8)) {
+      const retrySuggestion = await attemptRecovery(page, ctx, "go-checkout-retry", `Cliquei em '${clickedText.slice(0, 40).trim()}' (selector \`${usedSelector}\`), mas a URL ficou em ${result.url} e não foi pra /checkout. Achar o botão que de fato navega pra /checkout neste cart/minicart aberto.`, [usedSelector, ...selFor(ctx, "checkoutButton")]);
+      if (retrySuggestion) {
+        recoveryBudget--;
+        checkoutRecovered = true;
+        attempt++;
+        const retryResult = await tryCheckoutClick(retrySuggestion, attempt);
+        result = retryResult;
+        usedSelector = retrySuggestion.selector;
+        clickedText = retryResult.clickedText;
+        reachedCheckout = /\/checkout/i.test(retryResult.url);
+      }
+    }
     const step8Status = reachedCheckout ? "ok" : "failed";
     steps.push({
       step: 8,
@@ -5206,13 +5555,13 @@ async function flowPurchaseJourney(ctx) {
       viewport: ctx.viewport,
       status: step8Status,
       durationMs: Date.now() - t8,
-      url: checkoutUrl,
-      screenshotPath: sp8,
-      screenshotBeforePath: spBefore8,
+      url: result.url,
+      screenshotPath: result.spAfter,
+      screenshotBeforePath: result.spBefore,
       beforeUrl: beforeUrl8,
-      actionDescription: `Clicou em${checkoutText ? ` '${checkoutText.slice(0, 30).trim()}'` : ""} (\`${checkoutHit.selector}\`); URL final: ${checkoutUrl}${reachedCheckout ? " ✓ atingiu /checkout" : " ✗ não foi pra checkout"}`,
+      actionDescription: `Clicou em${clickedText ? ` '${clickedText.slice(0, 30).trim()}'` : ""} (\`${usedSelector}\`); URL final: ${result.url}${reachedCheckout ? " ✓ atingiu /checkout" : " ✗ não foi pra checkout"}${attempt > 1 ? ` (após ${attempt} tentativas com recovery LLM)` : ""}`,
       selectorKey: "checkoutButton",
-      usedSelector: checkoutHit.selector,
+      usedSelector,
       recoveredByLlm: checkoutRecovered || undefined
     });
     reportEnd(8, "go-checkout", step8Status, Date.now() - t8);
@@ -5655,7 +6004,7 @@ var CRITICAL_STEPS = new Set([
 async function journeyCommand(opts) {
   const viewports = opts.viewports.split(",").map((s) => s.trim()).filter((s) => s === "mobile" || s === "desktop");
   if (viewports.length === 0) {
-    console.error(chalk5.red("Nenhum viewport válido (use mobile,desktop)"));
+    console.error(chalk6.red("Nenhum viewport válido (use mobile,desktop)"));
     return 2;
   }
   const rc = loadParityRc();
@@ -5665,13 +6014,13 @@ async function journeyCommand(opts) {
   const runId = newRunId();
   const paths = createRunDir(opts.output, runId);
   if (!opts.json) {
-    console.log(chalk5.bold(`
+    console.log(chalk6.bold(`
   parity journey ${runId}`));
-    console.log(chalk5.dim(`  prod: ${opts.prod}`));
-    console.log(chalk5.dim(`  cand: ${opts.cand}`));
-    console.log(chalk5.dim(`  viewports: ${viewports.join(", ")} · CEP: ${rc.cep}`));
+    console.log(chalk6.dim(`  prod: ${opts.prod}`));
+    console.log(chalk6.dim(`  cand: ${opts.cand}`));
+    console.log(chalk6.dim(`  viewports: ${viewports.join(", ")} · CEP: ${rc.cep}`));
     if (isLlmAvailable())
-      console.log(chalk5.dim(`  llm: ${providerLabel()}`));
+      console.log(chalk6.dim(`  llm: ${providerLabel()}`));
     console.log("");
   }
   let platform = "custom";
@@ -5715,15 +6064,15 @@ async function journeyCommand(opts) {
   const onStepFor = (viewport, side) => (event) => {
     if (opts.json)
       return;
-    const sideTag = side === "prod" ? chalk5.cyan("prod") : chalk5.magenta("cand");
-    const prefix = `  ${chalk5.dim(`[${viewport}/`)}${sideTag}${chalk5.dim("]")}`;
+    const sideTag = side === "prod" ? chalk6.cyan("prod") : chalk6.magenta("cand");
+    const prefix = `  ${chalk6.dim(`[${viewport}/`)}${sideTag}${chalk6.dim("]")}`;
     if (event.phase === "start") {
-      console.log(`${prefix} ${chalk5.dim(`${event.index}/${event.total}`)} ▶ ${chalk5.bold(stepLabel(event.name))}`);
+      console.log(`${prefix} ${chalk6.dim(`${event.index}/${event.total}`)} ▶ ${chalk6.bold(stepLabel(event.name))}`);
     } else {
-      const glyph = event.status === "ok" ? chalk5.green("✓") : event.status === "skipped" ? chalk5.yellow("○") : chalk5.red("✗");
-      const noteText = event.note ? chalk5.dim(` (${event.note})`) : "";
-      const time = chalk5.dim(`${(event.durationMs / 1000).toFixed(1)}s`);
-      console.log(`${prefix} ${chalk5.dim(`${event.index}/${event.total}`)} ${glyph} ${stepLabel(event.name)} ${time}${noteText}`);
+      const glyph = event.status === "ok" ? chalk6.green("✓") : event.status === "skipped" ? chalk6.yellow("○") : chalk6.red("✗");
+      const noteText = event.note ? chalk6.dim(` (${event.note})`) : "";
+      const time = chalk6.dim(`${(event.durationMs / 1000).toFixed(1)}s`);
+      console.log(`${prefix} ${chalk6.dim(`${event.index}/${event.total}`)} ${glyph} ${stepLabel(event.name)} ${time}${noteText}`);
     }
   };
   async function runOneSide(browserInstance, viewport, side) {
@@ -5761,7 +6110,7 @@ async function journeyCommand(opts) {
     spinner?.succeed("Browser pronto");
     for (const viewport of viewports) {
       if (!opts.json)
-        console.log(chalk5.bold(`
+        console.log(chalk6.bold(`
   ── ${viewport} ─────────────────────────────────────────────`));
       const [prodCap, candCap] = await Promise.all([
         runOneSide(browser, viewport, "prod"),
@@ -5788,7 +6137,7 @@ async function journeyCommand(opts) {
     if (opts.junit) {
       writeFileSync6(opts.junit, buildJUnit(rows, failures), "utf8");
       if (!opts.json)
-        console.log(chalk5.dim(`  → JUnit XML: ${opts.junit}`));
+        console.log(chalk6.dim(`  → JUnit XML: ${opts.junit}`));
     }
     return failures.some((f) => f.critical) ? 1 : 0;
   } catch (err) {
@@ -5853,14 +6202,14 @@ function collectFailures(rows) {
 function printTable(viewports, rows) {
   console.log("");
   for (const viewport of viewports) {
-    console.log(chalk5.bold(`  [${viewport}]`));
+    console.log(chalk6.bold(`  [${viewport}]`));
     const vrows = rows.filter((r) => r.viewport === viewport);
     for (const r of vrows) {
       const label = STEP_LABELS[r.name] ?? r.name;
       const p = statusGlyph(r.prod?.status);
       const c = statusGlyph(r.cand?.status);
-      const status = r.prod?.status === "ok" && r.cand?.status !== "ok" ? chalk5.red("FAILED") : "";
-      const note = r.cand?.status === "failed" || r.cand?.status === "skipped" ? chalk5.dim(`(${r.cand?.note ?? r.cand?.status})`) : "";
+      const status = r.prod?.status === "ok" && r.cand?.status !== "ok" ? chalk6.red("FAILED") : "";
+      const note = r.cand?.status === "failed" || r.cand?.status === "skipped" ? chalk6.dim(`(${r.cand?.note ?? r.cand?.status})`) : "";
       console.log(`    ${label.padEnd(24)}  prod ${p}   cand ${c}   ${status} ${note}`);
     }
     console.log("");
@@ -5868,12 +6217,12 @@ function printTable(viewports, rows) {
 }
 function statusGlyph(status) {
   if (!status)
-    return chalk5.dim("—");
+    return chalk6.dim("—");
   if (status === "ok")
-    return chalk5.green("✓");
+    return chalk6.green("✓");
   if (status === "skipped")
-    return chalk5.yellow("○");
-  return chalk5.red("✗");
+    return chalk6.yellow("○");
+  return chalk6.red("✗");
 }
 function printSummary2(rows, failures, htmlPath) {
   const byViewport = new Map;
@@ -5884,25 +6233,25 @@ function printSummary2(rows, failures, htmlPath) {
       v.passed++;
     byViewport.set(r.viewport, v);
   }
-  console.log(chalk5.bold("  Summary:"));
+  console.log(chalk6.bold("  Summary:"));
   for (const [vp, { passed, total }] of byViewport) {
-    const stat = passed === total ? chalk5.green("✓") : chalk5.yellow(`${passed}/${total}`);
+    const stat = passed === total ? chalk6.green("✓") : chalk6.yellow(`${passed}/${total}`);
     console.log(`    ${vp.padEnd(8)} ${stat} steps em cand`);
   }
   if (failures.length > 0) {
     const crit = failures.filter((f) => f.critical).length;
     console.log("");
-    console.log(chalk5.red(`  ✗ ${failures.length} step(s) divergent(es) (${crit} crítico)`));
+    console.log(chalk6.red(`  ✗ ${failures.length} step(s) divergent(es) (${crit} crítico)`));
     for (const f of failures) {
-      const tag = f.critical ? chalk5.red("[critical]") : chalk5.yellow("[warn]");
+      const tag = f.critical ? chalk6.red("[critical]") : chalk6.yellow("[warn]");
       console.log(`    ${tag} [${f.viewport}] ${f.step}: ${f.reason}`);
     }
   } else {
     console.log("");
-    console.log(chalk5.green("  ✓ jornada completa em cand"));
+    console.log(chalk6.green("  ✓ jornada completa em cand"));
   }
   console.log("");
-  console.log(chalk5.dim(`  → ${htmlPath}`));
+  console.log(chalk6.dim(`  → ${htmlPath}`));
   console.log("");
 }
 function emitGithubAnnotations(failures) {
@@ -6130,23 +6479,23 @@ function escapeHtml(s) {
 }
 
 // src/commands/learned.ts
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 function learnedStats() {
   const lib = loadLearned();
   const stats = statsFromLib(lib);
   if (stats.platforms.length === 0) {
-    console.log(chalk6.dim(`Biblioteca vazia: ${LEARNED_PATH}`));
-    console.log(chalk6.dim("Rode `parity run ...` em algum site para começar a popular."));
+    console.log(chalk7.dim(`Biblioteca vazia: ${LEARNED_PATH}`));
+    console.log(chalk7.dim("Rode `parity run ...` em algum site para começar a popular."));
     return 0;
   }
-  console.log(chalk6.bold(`
+  console.log(chalk7.bold(`
 learned-selectors stats (${LEARNED_PATH})
 `));
   for (const p of stats.platforms) {
-    console.log(`${chalk6.cyan(p.platform)}: ${p.activeSelectors} active · ${chalk6.dim(`${p.deprecatedSelectors} deprecated`)}`);
+    console.log(`${chalk7.cyan(p.platform)}: ${p.activeSelectors} active · ${chalk7.dim(`${p.deprecatedSelectors} deprecated`)}`);
     for (const top of p.topByKey) {
       const sr = `${(top.successRate * 100).toFixed(0)}%`;
-      console.log(`   ${chalk6.dim(top.key.padEnd(18))} ${chalk6.green(sr.padStart(4))}  ${chalk6.dim(`(${top.hosts} hosts)`)}  ${top.selector}`);
+      console.log(`   ${chalk7.dim(top.key.padEnd(18))} ${chalk7.green(sr.padStart(4))}  ${chalk7.dim(`(${top.hosts} hosts)`)}  ${top.selector}`);
     }
     console.log("");
   }
@@ -6156,7 +6505,7 @@ learned-selectors stats (${LEARNED_PATH})
 // src/commands/vitals.ts
 import { existsSync as existsSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join8 } from "node:path";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import ora3 from "ora";
 
 // src/diff/vitals.ts
@@ -6306,10 +6655,10 @@ async function vitalsCommand(opts) {
   const runId = newRunId();
   const paths = createRunDir(opts.output, runId);
   const t0 = Date.now();
-  console.log(chalk7.bold(`
+  console.log(chalk8.bold(`
   parity vitals ${runId}`));
-  console.log(chalk7.dim(`  prod: ${opts.prod}`));
-  console.log(chalk7.dim(`  cand: ${opts.cand}`));
+  console.log(chalk8.dim(`  prod: ${opts.prod}`));
+  console.log(chalk8.dim(`  cand: ${opts.cand}`));
   const discoverSpinner = ora3("Descobrindo páginas…").start();
   const pagePaths = await discoverPagePaths2(opts.prod, opts);
   if (pagePaths.length === 0) {
@@ -6341,7 +6690,7 @@ async function vitalsCommand(opts) {
         completed++;
         const elapsed = ((Date.now() - t0) / 1000).toFixed(0);
         const etaSec = completed > 0 ? Math.round((Date.now() - t0) / completed * (total - completed) / 1000) : 0;
-        progress.text = `${completed}/${total} · ${elapsed}s · ETA ${etaSec}s · ${task.side === "prod" ? chalk7.cyan("prod") : chalk7.magenta("cand")} ${task.path} (${task.viewport})`;
+        progress.text = `${completed}/${total} · ${elapsed}s · ETA ${etaSec}s · ${task.side === "prod" ? chalk8.cyan("prod") : chalk8.magenta("cand")} ${task.path} (${task.viewport})`;
       }
     });
     progress.succeed(`${total} capture(s) em ${((Date.now() - t0) / 1000).toFixed(1)}s`);
@@ -6414,8 +6763,8 @@ async function vitalsCommand(opts) {
 `, "utf8");
     printSummary3(vitalsResult, cacheResult);
     console.log("");
-    console.log(chalk7.dim(`  → ${paths.reportHtml}`));
-    console.log(chalk7.dim(`  \uD83D\uDCA1 use 'parity serve ${runId}' pra preview iframe`));
+    console.log(chalk8.dim(`  → ${paths.reportHtml}`));
+    console.log(chalk8.dim(`  \uD83D\uDCA1 use 'parity serve ${runId}' pra preview iframe`));
     console.log("");
     if (opts.open) {
       const { default: open } = await import("open");
@@ -6543,27 +6892,27 @@ function computeVerdict2(checks, issues) {
 }
 function printSummary3(vitals, cache) {
   console.log("");
-  console.log(chalk7.bold("  Summary:"));
+  console.log(chalk8.bold("  Summary:"));
   console.log(`    ${vitals.summary}`);
   console.log(`    ${cache.summary}`);
 }
 
 // src/commands/list.ts
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 function listCommand(output) {
   const runs = listRuns(output);
   if (runs.length === 0) {
-    console.log(chalk8.dim(`Nenhum run salvo em ${output}`));
+    console.log(chalk9.dim(`Nenhum run salvo em ${output}`));
     return 0;
   }
   for (const r of runs) {
     try {
       const run = loadRun(output, r.id);
       const v = run.verdict;
-      const status = v.status === "pass" ? chalk8.green(v.status) : v.status === "warn" ? chalk8.yellow(v.status) : chalk8.red(v.status);
-      console.log(`  ${chalk8.bold(r.id)}  ${status}  score=${v.score}  critical=${v.critical} high=${v.high}  ${chalk8.dim(r.timestamp)}`);
+      const status = v.status === "pass" ? chalk9.green(v.status) : v.status === "warn" ? chalk9.yellow(v.status) : chalk9.red(v.status);
+      console.log(`  ${chalk9.bold(r.id)}  ${status}  score=${v.score}  critical=${v.critical} high=${v.high}  ${chalk9.dim(r.timestamp)}`);
     } catch {
-      console.log(`  ${chalk8.bold(r.id)}  ${chalk8.dim("(report.json ausente)")}`);
+      console.log(`  ${chalk9.bold(r.id)}  ${chalk9.dim("(report.json ausente)")}`);
     }
   }
   return 0;
@@ -6571,13 +6920,13 @@ function listCommand(output) {
 
 // src/commands/prompt.ts
 import { existsSync as existsSync8, writeFileSync as writeFileSync8 } from "node:fs";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function promptCommand(runId, opts) {
   let run;
   try {
     run = loadRun(opts.output, runId);
   } catch (err) {
-    console.error(chalk9.red(`✖ ${err.message}`));
+    console.error(chalk10.red(`✖ ${err.message}`));
     return 1;
   }
   const md = buildLlmPrompt(run, {
@@ -6586,10 +6935,10 @@ function promptCommand(runId, opts) {
   });
   if (opts.out) {
     writeFileSync8(opts.out, md, "utf8");
-    console.log(chalk9.green(`✔ prompt salvo em ${opts.out}`));
+    console.log(chalk10.green(`✔ prompt salvo em ${opts.out}`));
     if (existsSync8(opts.out)) {
       const sizeKb = (md.length / 1024).toFixed(1);
-      console.log(chalk9.dim(`  ${md.length} chars (${sizeKb} KB)`));
+      console.log(chalk10.dim(`  ${md.length} chars (${sizeKb} KB)`));
     }
   } else {
     process.stdout.write(md);
@@ -6598,20 +6947,20 @@ function promptCommand(runId, opts) {
 }
 
 // src/commands/report.ts
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 import open from "open";
 async function reportCommand(runId, output) {
   const paths = getRunPaths(output, runId);
-  console.log(chalk10.dim(`opening ${paths.reportHtml}`));
+  console.log(chalk11.dim(`opening ${paths.reportHtml}`));
   await open(paths.reportHtml).catch((err) => {
-    console.error(chalk10.red(`failed to open: ${err.message}`));
+    console.error(chalk11.red(`failed to open: ${err.message}`));
   });
   return 0;
 }
 
 // src/commands/run.ts
 import { join as join11 } from "node:path";
-import chalk12 from "chalk";
+import chalk13 from "chalk";
 import ora4 from "ora";
 
 // src/checks/http-status.ts
@@ -8905,7 +9254,7 @@ cand: ${JSON.stringify(cand)}`,
 
 // src/commands/serve.ts
 import { existsSync as existsSync11 } from "node:fs";
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 
 // src/server/proxy-server.ts
 import { existsSync as existsSync10, readFileSync as readFileSync10, statSync } from "node:fs";
@@ -9125,16 +9474,16 @@ async function serveRunAndBlock(runDir, opts = {}) {
   try {
     handle = await startProxyServer(runDir, { port: opts.port });
   } catch (err) {
-    console.error(chalk11.red(`  ✖ Falha ao iniciar servidor: ${err.message}`));
+    console.error(chalk12.red(`  ✖ Falha ao iniciar servidor: ${err.message}`));
     return 2;
   }
   const label = opts.label ?? "parity serve";
   console.log("");
-  console.log(chalk11.bold(`  ${label}`));
-  console.log(`  ${chalk11.green("●")} ${handle.url}`);
-  console.log(chalk11.dim(`  Servindo: ${runDir}`));
-  console.log(chalk11.dim(`  Proxy de iframes: ${handle.url}proxy?url=<encoded>`));
-  console.log(chalk11.dim(`  Ctrl+C pra parar (2x pra forçar saída).
+  console.log(chalk12.bold(`  ${label}`));
+  console.log(`  ${chalk12.green("●")} ${handle.url}`);
+  console.log(chalk12.dim(`  Servindo: ${runDir}`));
+  console.log(chalk12.dim(`  Proxy de iframes: ${handle.url}proxy?url=<encoded>`));
+  console.log(chalk12.dim(`  Ctrl+C pra parar (2x pra forçar saída).
 `));
   if (opts.open !== false) {
     const { default: open2 } = await import("open");
@@ -9167,11 +9516,11 @@ async function serveRunAndBlock(runDir, opts = {}) {
 async function serveCommand(runId, opts) {
   const paths = getRunPaths(opts.output, runId);
   if (!existsSync11(paths.runDir)) {
-    console.error(chalk11.red(`✖ Run não encontrado: ${runId} (em ${opts.output})`));
+    console.error(chalk12.red(`✖ Run não encontrado: ${runId} (em ${opts.output})`));
     return 1;
   }
   if (!existsSync11(paths.reportHtml)) {
-    console.error(chalk11.red(`✖ report.html não existe em ${paths.runDir}`));
+    console.error(chalk12.red(`✖ report.html não existe em ${paths.runDir}`));
     return 1;
   }
   return serveRunAndBlock(paths.runDir, {
@@ -9231,7 +9580,7 @@ function applyPreset(opts) {
 async function runCommand(rawOpts) {
   const opts = applyPreset(rawOpts);
   if (rawOpts.preset) {
-    console.log(chalk12.dim(`  preset: ${rawOpts.preset}`));
+    console.log(chalk13.dim(`  preset: ${rawOpts.preset}`));
   }
   const flows = opts.flows.split(",").map((s) => s.trim());
   const viewports = opts.viewports.split(",").map((s) => s.trim());
@@ -9241,11 +9590,11 @@ async function runCommand(rawOpts) {
   const ignore = loadParityIgnore();
   const preflight = await preflightCheck(opts.prod, opts.cand);
   if (!preflight.ok) {
-    console.error(chalk12.red(`
+    console.error(chalk13.red(`
   ✖ pre-flight falhou:`));
     for (const err of preflight.errors)
-      console.error(chalk12.red(`    - ${err}`));
-    console.error(chalk12.dim(`
+      console.error(chalk13.red(`    - ${err}`));
+    console.error(chalk13.dim(`
   dica: verifique se as URLs estão corretas e acessíveis`));
     return 2;
   }
@@ -9256,7 +9605,7 @@ async function runCommand(rawOpts) {
   if (prodHomeHtml) {
     platform = detectPlatform({ url: opts.prod, html: prodHomeHtml });
     if (platform !== "custom") {
-      console.log(chalk12.dim(`  Detected platform: ${platform}`));
+      console.log(chalk13.dim(`  Detected platform: ${platform}`));
     }
   }
   const prodHost = hostOf(opts.prod);
@@ -9298,11 +9647,11 @@ async function runCommand(rawOpts) {
   const paths = createRunDir(opts.output, runId);
   const startedAt = Date.now();
   const timestamp = new Date().toISOString();
-  console.log(chalk12.bold(`
+  console.log(chalk13.bold(`
   parity run ${runId}`));
-  console.log(chalk12.dim(`  prod: ${opts.prod}`));
-  console.log(chalk12.dim(`  cand: ${opts.cand}`));
-  console.log(chalk12.dim(`  flows: ${flows.join(", ")} · viewports: ${viewports.join(", ")} · CEP: ${rc.cep}
+  console.log(chalk13.dim(`  prod: ${opts.prod}`));
+  console.log(chalk13.dim(`  cand: ${opts.cand}`));
+  console.log(chalk13.dim(`  flows: ${flows.join(", ")} · viewports: ${viewports.join(", ")} · CEP: ${rc.cep}
 `));
   const spinner = ora4("Launching browser…").start();
   let browser = null;
@@ -9616,7 +9965,7 @@ async function runCommand(rawOpts) {
     if (opts.ci) {
       const blocking = allIssues.filter((i) => failOn.includes(i.severity));
       if (blocking.length > 0) {
-        console.log(chalk12.red(`
+        console.log(chalk13.red(`
   ✖ ${blocking.length} issue(s) bloqueante(s) [${failOn.join(", ")}] — exit 1`));
         return 1;
       }
@@ -9755,26 +10104,26 @@ function hostOf(url) {
 }
 function printSummary4(run, htmlPath, meta) {
   const { verdict } = run;
-  const emoji = verdict.status === "pass" ? chalk12.green("✔") : verdict.status === "warn" ? chalk12.yellow("⚠") : chalk12.red("✖");
-  const score = verdict.status === "pass" ? chalk12.green(verdict.score) : verdict.status === "warn" ? chalk12.yellow(verdict.score) : chalk12.red(verdict.score);
+  const emoji = verdict.status === "pass" ? chalk13.green("✔") : verdict.status === "warn" ? chalk13.yellow("⚠") : chalk13.red("✖");
+  const score = verdict.status === "pass" ? chalk13.green(verdict.score) : verdict.status === "warn" ? chalk13.yellow(verdict.score) : chalk13.red(verdict.score);
   console.log("");
   console.log(`  ${emoji}  parity ${verdict.status.toUpperCase()} · score ${score}/100`);
-  console.log(`     checks: ${chalk12.green(verdict.checksPassed)} pass · ${chalk12.red(verdict.checksFailed)} fail · ${chalk12.dim(`${verdict.checksSkipped} skipped`)}`);
-  console.log(`     issues: ${chalk12.red(verdict.critical)} critical · ${chalk12.yellow(verdict.high)} high · ${verdict.medium} medium · ${chalk12.dim(`${verdict.low} low`)}`);
+  console.log(`     checks: ${chalk13.green(verdict.checksPassed)} pass · ${chalk13.red(verdict.checksFailed)} fail · ${chalk13.dim(`${verdict.checksSkipped} skipped`)}`);
+  console.log(`     issues: ${chalk13.red(verdict.critical)} critical · ${chalk13.yellow(verdict.high)} high · ${verdict.medium} medium · ${chalk13.dim(`${verdict.low} low`)}`);
   if (run.topIssues.length > 0) {
     console.log("");
-    console.log(chalk12.bold("  Top issues:"));
+    console.log(chalk13.bold("  Top issues:"));
     for (const i of run.topIssues.slice(0, 5)) {
-      const sev = i.severity === "critical" ? chalk12.red(`[${i.severity}]`) : i.severity === "high" ? chalk12.yellow(`[${i.severity}]`) : chalk12.dim(`[${i.severity}]`);
+      const sev = i.severity === "critical" ? chalk13.red(`[${i.severity}]`) : i.severity === "high" ? chalk13.yellow(`[${i.severity}]`) : chalk13.dim(`[${i.severity}]`);
       console.log(`     ${sev} ${i.summary}`);
     }
   }
   if (meta.promotedCount > 0 || meta.deprecatedCount > 0) {
     console.log("");
-    console.log(chalk12.dim(`  \uD83D\uDCDA learned-selectors [${meta.platform}]: ${chalk12.green(`+${meta.promotedCount}`)} promoted · ${chalk12.yellow(meta.deprecatedCount)} deprecated`));
+    console.log(chalk13.dim(`  \uD83D\uDCDA learned-selectors [${meta.platform}]: ${chalk13.green(`+${meta.promotedCount}`)} promoted · ${chalk13.yellow(meta.deprecatedCount)} deprecated`));
   }
   console.log("");
-  console.log(chalk12.dim(`  → ${htmlPath}`));
+  console.log(chalk13.dim(`  → ${htmlPath}`));
   console.log("");
 }
 
@@ -9824,6 +10173,18 @@ program.command("prompt").argument("<runId>", "Run ID").description("Generate a
 program.command("explain").argument("<runId>", "Run ID").argument("<issueId>", "Issue ID").option("--output <dir>", "Output directory", "./parity-output").description("LLM deep-dive on a specific issue (requires ANTHROPIC_API_KEY)").action(async (runId, issueId, opts) => {
   process.exit(await explainCommand(runId, issueId, opts.output));
 });
+program.command("css-trace").description("Inspect which CSS rules (from which stylesheets) are affecting a DOM element. Single URL mode lists every matched rule; --prod + --cand mode diffs computed styles between Fresh and TanStack sides.").option("--url <url>", "Single URL to inspect (mutually exclusive with --prod/--cand)").option("--prod <url>", "Production URL (for comparison mode)").option("--cand <url>", "Candidate URL (for comparison mode)").requiredOption("--selector <sel>", "CSS selector for the target element (e.g. 'html', '[data-aside]', '.drawer-side')").option("--filter <props>", "Comma-separated property names to focus on (e.g. 'scrollbar-gutter,position,width')").option("--viewport <viewport>", "mobile, tablet, or desktop", "desktop").option("--settle <ms>", "Wait this many ms after `load` for hydration", (v) => Number(v), 1500).option("--json", "Output JSON instead of pretty text", false).action(async (opts) => {
+  process.exit(await cssTraceCommand({
+    url: opts.url,
+    prod: opts.prod,
+    cand: opts.cand,
+    selector: opts.selector,
+    filter: opts.filter,
+    viewport: opts.viewport,
+    settleMs: opts.settle,
+    json: opts.json
+  }));
+});
 program.command("learned").description("Inspect the learned-selectors library").addCommand(new Command("stats").description("Print learned-selectors stats per platform").action(() => {
   process.exit(learnedStats());
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@decocms/parity",
-	"version": "0.1.1",
+	"version": "0.3.0",
 	"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.",
 	"type": "module",
 	"license": "MIT",