@decocms/parity 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.17.0](https://github.com/decocms/parity/compare/v0.16.0...v0.17.0) (2026-07-28)
+
+### Added
+
+* **`open-minicart`/`add-to-cart` reveal-failure diagnostics fed to LLM recovery.** A poll-based step (waiting for the minicart drawer or an add-to-cart confirmation to appear) previously reported a bare "not found"/"no signal" on timeout, with no evidence of *why*. Failed polls now attach a structured `diagnostics` object to the step (`timedOut`, `budgetMs`, `elapsedMs`, `pollCount`, and a per-selector `probes` snapshot distinguishing "present in the DOM but stayed hidden" from "never matched at all") — surfaced in `report.json` and rendered in the HTML report's step cell. When `open-minicart` fails with this evidence available, parity now spends one LLM recovery attempt passing the diagnostics as concrete context (`RecoverInput.diagnostics`) instead of a bare failure, and the recovery prompt is told not to re-suggest a selector already confirmed present-but-hidden.
+* New `cartRevealTimeoutMs` (issue #149 follow-up) tunes how long `waitForCartReveal` polls for the drawer before giving up. Defaults to 4000ms (8000ms on localhost dev servers, which are slower).
+
+### Fixed
+
+* **`waitForCartReveal` polls instead of snapshotting once.** `openMinicart`'s reveal check (via `isCartRevealed`/Playwright `isVisible()`) was a one-shot read of the drawer's *current* state right after a fixed wait, not an actual wait. Drawers that reveal asynchronously — a CSS `allow-discrete` visibility/opacity transition, a data-gated render (react-query cart), or a slow click handler — can stay `visibility:hidden` (often positioned off-screen) for well over a second after the click, so the single snapshot landed inside the hidden window and wrongly reported the cart never opened, even with the correct selector, no overlay, and no console error. `openMinicart` now polls every 200ms up to an adaptive budget instead.
+* **`open-minicart` re-checks for a blocking overlay before giving up.** `dismissOverlays` only ran once at the very top of `openMinicart`, before the trigger was clicked. Confirmed live against a production deploy: a newsletter popup can appear *after* the add-to-cart click and silently intercept the minicart-trigger click (`force: true` clicks whatever is topmost at the coordinates, not necessarily the intended target), so the drawer never opens even though the selector and reveal-polling logic are both correct. `openMinicart` now detects this structurally (mirroring `dismissBlockingOverlay`, issues #145/#146) and retries the click once after clearing it.
+
 ## [0.16.0](https://github.com/decocms/parity/compare/v0.15.1...v0.16.0) (2026-07-28)
 
 ### Added

package/dist/cli.js

@@ -39020,6 +39020,21 @@ async function capturePage(page, opts) {
   let xRobotsTag = null;
   let vitals = null;
   let html3 = "";
+  let _resolveDisconnect;
+  const disconnectPromise = new Promise((r) => {
+    _resolveDisconnect = r;
+  });
+  const browser = page.context().browser();
+  const handleBrowserDisconnect = () => {
+    dlog(opts.side, opts.viewport, "    capturePage: browser disconnected — aborting capture");
+    _resolveDisconnect();
+  };
+  const handlePageCrash = () => {
+    dlog(opts.side, opts.viewport, "    capturePage: page crashed — aborting capture");
+    _resolveDisconnect();
+  };
+  browser?.on("disconnected", handleBrowserDisconnect);
+  page.on("crash", handlePageCrash);
   const inner = async () => {
     try {
       dlog(opts.side, opts.viewport, `    capturePage: goto(${opts.url}) start`);
@@ -39130,7 +39145,7 @@ async function capturePage(page, opts) {
   };
   const SAFETY_MARGIN_MS = 1e4;
   const outerDeadlineMs = overallBudgetMs + SAFETY_MARGIN_MS;
-  return Promise.race([
+  const result = await Promise.race([
     inner(),
     new Promise((resolve) => setTimeout(() => {
       state.console.push({
@@ -39138,8 +39153,18 @@ async function capturePage(page, opts) {
         text: `[capture-timeout] capturePage exceeded ${outerDeadlineMs}ms outer deadline — returning partial capture`
       });
       resolve(buildPartial());
-    }, outerDeadlineMs))
+    }, outerDeadlineMs)),
+    disconnectPromise.then(() => {
+      state.console.push({
+        type: "error",
+        text: "[browser-disconnected] browser/page crashed — returning partial capture"
+      });
+      return buildPartial();
+    })
   ]);
+  browser?.off("disconnected", handleBrowserDisconnect);
+  page.off("crash", handlePageCrash);
+  return result;
 }
 
 // src/report/html-template.ts
@@ -40340,6 +40365,14 @@ var REPORT_CSS = `
     color: var(--state-warn);
     font-style: italic;
   }
+  .step-diagnostics {
+    margin-top: 4px;
+    font-size: 10px;
+    color: var(--text-muted);
+    border-left: 2px solid var(--state-warn);
+    padding-left: 6px;
+  }
+  .step-diagnostics code { background: var(--surface-base); padding: 1px 4px; border-radius: 3px; }
 
   /* Network waterfall — per-page SVG bar chart. Issue #78. */
   .wf-page {
@@ -41154,6 +41187,18 @@ var StepCapture = z.object({
   loginValidation: z.object({
     stage: z.enum(["form-loaded", "submitted", "succeeded", "error-shown"]),
     errorMessage: z.string().optional()
+  }).optional(),
+  diagnostics: z.object({
+    timedOut: z.boolean().optional(),
+    budgetMs: z.number().optional(),
+    elapsedMs: z.number().optional(),
+    pollCount: z.number().optional(),
+    probes: z.array(z.object({
+      selector: z.string(),
+      present: z.boolean(),
+      visible: z.boolean()
+    })).optional(),
+    toastText: z.string().optional()
   }).optional()
 });
 var FlowCapture = z.object({
@@ -41436,7 +41481,8 @@ var ParityRc = z.object({
   serverFnFloodBudget: z.number().optional(),
   serverFnPattern: z.string().optional(),
   overlaySelectors: z.array(z.string()).optional(),
-  addToCartConfirmMs: z.number().optional()
+  addToCartConfirmMs: z.number().optional(),
+  cartRevealTimeoutMs: z.number().optional()
 });
 var ParityIgnore = z.object({
   ignoreSelectorsVisual: z.array(z.string()).default([]),
@@ -47516,12 +47562,26 @@ function renderStepCell(s, runDir) {
   const screenshot = s.screenshotPath ? `<a class="step-shot" href="${escapeHtml(relPath(runDir, s.screenshotPath))}" target="_blank" title="open screenshot">\uD83D\uDCF7</a>` : "";
   const selector = s.usedSelector ? `<div class="step-selector"><code>${escapeHtml(s.usedSelector)}</code></div>` : "";
   const note = s.note ? `<div class="step-note">${escapeHtml(s.note)}</div>` : "";
+  const diagnostics = renderStepDiagnostics(s.diagnostics);
   return `<td class="step-cell ${statusClass}">
     <div class="step-cell-head"><span class="step-status">${s.status}</span>${screenshot}<span class="dim">${s.durationMs}ms</span></div>
     ${selector}
     ${note}
+    ${diagnostics}
   </td>`;
 }
+function renderStepDiagnostics(d) {
+  if (!d?.timedOut)
+    return "";
+  const hidden = d.probes?.filter((p) => p.present && !p.visible) ?? [];
+  const missing = d.probes?.filter((p) => !p.present) ?? [];
+  const rows = [
+    `<div>esperou ${d.elapsedMs}ms / orçamento ${d.budgetMs}ms (${d.pollCount} poll(s))</div>`,
+    ...hidden.map((p) => `<div>⚠️ presente porém oculto: <code>${escapeHtml(p.selector)}</code></div>`),
+    ...missing.map((p) => `<div>não encontrado no DOM: <code>${escapeHtml(p.selector)}</code></div>`)
+  ];
+  return `<div class="step-diagnostics">${rows.join("")}</div>`;
+}
 function renderChecksTable(run) {
   return `
   <div class="card">
@@ -49313,9 +49373,21 @@ async function cssTraceCommand(opts) {
 
 // src/commands/e2e.ts
 import { writeFileSync as writeFileSync10 } from "node:fs";
+import { spawn } from "node:child_process";
 import chalk8 from "chalk";
 import ora4 from "ora";
 
+// src/util/localhost.ts
+var LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"]);
+function isLocalhost(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    return LOCALHOST_HOSTS.has(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
 // src/llm/pick-plp.ts
 init_client();
 var PATH_BLOCKLIST = [
@@ -49494,6 +49566,8 @@ REGRAS CRÍTICAS:
 
 9. **Quando incerto, retorne selector="" (string vazia).** É preferível que o flow declare a falha honestamente a chutar um seletor errado que apenas clica em coisa aleatória. Em especial: se a página parece ser uma LANDING PAGE (sem buy form, sem schema:Product, sem preço) e o step pede um buy/variant/cep selector, retorne string vazia — não force uma sugestão.
 
+10. **Se receber "Diagnóstico" com "present-but-hidden: &lt;seletor&gt;"**, isso significa que ESSE seletor específico já casa o elemento certo no DOM, mas ele ficou invisível pelo tempo orçado — é um problema de timing/animação/dados assíncronos, NÃO um seletor errado. NÃO sugira esse mesmo seletor de novo. Considere: (a) um seletor de TRIGGER diferente que realmente dispara a revelação (ex: o clique caiu num elemento errado), ou (b) se nada mais plausível existe, retorne selector="" — não invente um seletor alternativo só para dar uma resposta.
+
 Responda SEMPRE via tool_use suggest_recovery.
 `.trim();
 async function suggestRecovery(input) {
@@ -49504,6 +49578,7 @@ async function suggestRecovery(input) {
     userText: `Step: ${input.stepName}
 Ação desejada: ${input.intendedAction}
 ${input.alreadyTried?.length ? `Já tentei (não repita estes): ${input.alreadyTried.join(", ")}
+` : ""}${input.diagnostics ? `Diagnóstico: ${input.diagnostics}
 ` : ""}
 HTML compactado da página NESTE momento:
 \`\`\`html
@@ -50383,14 +50458,14 @@ async function findElement(page, ctx, opts) {
   }
   return null;
 }
-async function attemptRecovery(page, _ctx, stepName, intendedAction, alreadyTried) {
+async function attemptRecovery(page, _ctx, stepName, intendedAction, alreadyTried, diagnostics) {
   let html3 = "";
   try {
     html3 = await page.content();
   } catch {
     return null;
   }
-  const suggestion = await suggestRecovery({ stepName, intendedAction, html: html3, alreadyTried });
+  const suggestion = await suggestRecovery({ stepName, intendedAction, html: html3, alreadyTried, diagnostics });
   if (!suggestion)
     return null;
   try {
@@ -50866,6 +50941,66 @@ async function isCartRevealed(page, expectedProductTitle, ctx) {
   }
   return isCartUiVisible(page, ctx);
 }
+var CART_REVEAL_BUDGET_MS = 4000;
+var CART_REVEAL_BUDGET_LOCALHOST_MS = 8000;
+var CART_REVEAL_POLL_INTERVAL_MS = 200;
+var CART_REVEAL_HOVER_PROBE_MS = 1500;
+async function probeCartSelectors(page, ctx) {
+  const selectors = [...new Set([...selFor(ctx, "minicartPanel"), ...selFor(ctx, "cartOpenedIndicator")])];
+  const probes = [];
+  for (const sel of selectors) {
+    try {
+      const loc = page.locator(sel);
+      const present = await withCap(loc.count(), 300, 0) > 0;
+      const visible = present ? await withCap(loc.first().isVisible().catch(() => false), 300, false) : false;
+      probes.push({ selector: sel, present, visible });
+    } catch {
+      probes.push({ selector: sel, present: false, visible: false });
+    }
+  }
+  return probes;
+}
+function summarizeCartRevealDiagnostics(d) {
+  const parts = [`waited ${d.elapsedMs}ms/${d.budgetMs}ms (${d.pollCount} poll(s))`];
+  const hidden = d.probes?.filter((p) => p.present && !p.visible) ?? [];
+  const missing = d.probes?.filter((p) => !p.present) ?? [];
+  if (hidden.length) {
+    parts.push(`present-but-hidden: ${hidden.map((p) => p.selector).join(", ")}`);
+  }
+  if (missing.length) {
+    parts.push(`not-in-dom: ${missing.map((p) => p.selector).join(", ")}`);
+  }
+  return parts.join(" — ");
+}
+async function waitForCartReveal(page, expectedProductTitle, ctx, timeoutMs) {
+  const start = Date.now();
+  const deadline = start + timeoutMs;
+  let pollCount = 0;
+  for (;; ) {
+    pollCount++;
+    const marker = await isCartRevealed(page, expectedProductTitle, ctx);
+    if (marker) {
+      dlog2(ctx, `    waitForCartReveal: revealed after ${pollCount} poll(s) (${marker})`);
+      return {
+        marker,
+        diagnostics: { timedOut: false, budgetMs: timeoutMs, elapsedMs: Date.now() - start, pollCount }
+      };
+    }
+    if (Date.now() >= deadline) {
+      const probes = await probeCartSelectors(page, ctx);
+      const diagnostics = {
+        timedOut: true,
+        budgetMs: timeoutMs,
+        elapsedMs: Date.now() - start,
+        pollCount,
+        probes
+      };
+      dlog2(ctx, `    waitForCartReveal: ${summarizeCartRevealDiagnostics(diagnostics)}`);
+      return { marker: null, diagnostics };
+    }
+    await page.waitForTimeout(CART_REVEAL_POLL_INTERVAL_MS);
+  }
+}
 async function validateCartContainsTitleQuick(page, expectedTitle, ctx) {
   const quickSelectors = [
     ...ctx ? selFor(ctx, "minicartPanel") : [],
@@ -50903,7 +51038,9 @@ async function waitForCartHydration(page) {
 }
 async function openMinicart(page, trigger, ctx, expectedProductTitle) {
   const beforeUrl = page.url();
-  dlog2(ctx, `  openMinicart: starting — trigger=${trigger.selector} title=${expectedProductTitle?.slice(0, 40) ?? "none"}`);
+  let lastDiagnostics;
+  const revealBudget = ctx.rc.cartRevealTimeoutMs ?? (isLocalhost(beforeUrl) ? CART_REVEAL_BUDGET_LOCALHOST_MS : CART_REVEAL_BUDGET_MS);
+  dlog2(ctx, `  openMinicart: starting — trigger=${trigger.selector} title=${expectedProductTitle?.slice(0, 40) ?? "none"} revealBudget=${revealBudget}ms`);
   await Promise.race([
     dismissOverlays(page, ctx),
     new Promise((resolve) => setTimeout(resolve, 4000))
@@ -50922,11 +51059,12 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
     await trigger.locator.hover({ timeout: 3000 }).catch(() => {
       return;
     });
-    await page.waitForTimeout(1500);
-    const hoverOpened = await isCartRevealed(page, expectedProductTitle, ctx);
-    if (hoverOpened) {
-      dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
-      return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
+    const hoverProbeBudget = Math.min(CART_REVEAL_HOVER_PROBE_MS, revealBudget);
+    const hover1 = await waitForCartReveal(page, expectedProductTitle, ctx, hoverProbeBudget);
+    lastDiagnostics = hover1.diagnostics;
+    if (hover1.marker) {
+      dlog2(ctx, `  openMinicart: hover opened drawer (${hover1.marker})`);
+      return { method: "hover", url: page.url(), visibleMarker: hover1.marker, diagnostics: hover1.diagnostics };
     }
   }
   if (ctx.viewport === "mobile") {
@@ -50947,11 +51085,11 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       dlog2(ctx, `  openMinicart: tap navigated → ${page.url()} (settled)`);
       return { method: "click-navigate", url: page.url(), visibleMarker: null };
     }
-    await page.waitForTimeout(800);
-    const tapOpened = await isCartRevealed(page, expectedProductTitle, ctx);
-    if (tapOpened) {
-      dlog2(ctx, `  openMinicart: tap opened drawer (${tapOpened})`);
-      return { method: "click", url: page.url(), visibleMarker: tapOpened };
+    const tap = await waitForCartReveal(page, expectedProductTitle, ctx, revealBudget);
+    lastDiagnostics = tap.diagnostics;
+    if (tap.marker) {
+      dlog2(ctx, `  openMinicart: tap opened drawer (${tap.marker})`);
+      return { method: "click", url: page.url(), visibleMarker: tap.marker, diagnostics: tap.diagnostics };
     }
   }
   dlog2(ctx, `  openMinicart: trying force-click on ${trigger.selector}${triggerHref ? ` (href=${triggerHref})` : ""}`);
@@ -50972,22 +51110,35 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
     dlog2(ctx, `  openMinicart: click navigated → ${page.url()} (settled)`);
     return { method: "click-navigate", url: page.url(), visibleMarker: null };
   }
-  await page.waitForTimeout(1500);
-  const clickOpened = await isCartRevealed(page, expectedProductTitle, ctx);
-  if (clickOpened) {
-    dlog2(ctx, `  openMinicart: click opened drawer (${clickOpened})`);
-    return { method: "click", url: afterClickUrl, visibleMarker: clickOpened };
+  const click = await waitForCartReveal(page, expectedProductTitle, ctx, revealBudget);
+  lastDiagnostics = click.diagnostics;
+  if (click.marker) {
+    dlog2(ctx, `  openMinicart: click opened drawer (${click.marker})`);
+    return { method: "click", url: afterClickUrl, visibleMarker: click.marker, diagnostics: click.diagnostics };
+  }
+  const blockingOverlay = await dismissBlockingOverlay(page, ctx, trigger.locator);
+  if (blockingOverlay?.dismissed) {
+    dlog2(ctx, `  openMinicart: cleared blocking overlay (${blockingOverlay.method}) — retrying click`);
+    await trigger.locator.click({ force: true, timeout: 4000 }).catch(() => {
+      return;
+    });
+    const retry = await waitForCartReveal(page, expectedProductTitle, ctx, revealBudget);
+    lastDiagnostics = retry.diagnostics;
+    if (retry.marker) {
+      dlog2(ctx, `  openMinicart: click opened drawer after overlay dismissal (${retry.marker})`);
+      return { method: "click", url: page.url(), visibleMarker: retry.marker, diagnostics: retry.diagnostics };
+    }
   }
   if (ctx.viewport !== "desktop") {
     dlog2(ctx, `  openMinicart: click didn't reveal cart, trying hover (mobile)`);
     await trigger.locator.hover({ timeout: 3000 }).catch(() => {
       return;
     });
-    await page.waitForTimeout(1500);
-    const hoverOpened = await isCartRevealed(page, expectedProductTitle, ctx);
-    if (hoverOpened) {
-      dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
-      return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
+    const hover2 = await waitForCartReveal(page, expectedProductTitle, ctx, revealBudget);
+    lastDiagnostics = hover2.diagnostics;
+    if (hover2.marker) {
+      dlog2(ctx, `  openMinicart: hover opened drawer (${hover2.marker})`);
+      return { method: "hover", url: page.url(), visibleMarker: hover2.marker, diagnostics: hover2.diagnostics };
     }
   }
   if (hrefHasCartTarget && triggerHref) {
@@ -51010,8 +51161,8 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       }
     }
   }
-  dlog2(ctx, "  openMinicart: failed — no cart revealed by hover/click/goto");
-  return { method: "failed", url: page.url(), visibleMarker: null };
+  dlog2(ctx, `  openMinicart: failed — no cart revealed by hover/click/goto${lastDiagnostics ? ` (${summarizeCartRevealDiagnostics(lastDiagnostics)})` : ""}`);
+  return { method: "failed", url: page.url(), visibleMarker: null, diagnostics: lastDiagnostics };
 }
 function normalizeTitle(s) {
   return s.toLowerCase().replace(/[®©™]/g, "").replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
@@ -51868,6 +52019,7 @@ async function flowPurchaseJourney(ctx) {
       usedSelector: buyHit.selector,
       recoveredByLlm: buyRecovered || undefined,
       note: validation.status === "ok" ? undefined : validation.note,
+      diagnostics: validation.diagnostics,
       detail: {
         signal: validation.signal,
         errorText: validation.errorText,
@@ -51897,13 +52049,26 @@ async function flowPurchaseJourney(ctx) {
     let cartOpenMethod = "failed";
     let miniText = "";
     let cartRevealMode = "unknown";
+    let revealDiagnostics;
     const drawerAlreadyOpen = await isCartRevealed(page, expectedProductTitle, ctx) !== null;
     if (miniHit) {
       miniText = await miniHit.locator.innerText().catch(() => "");
       cartRevealMode = await detectCartRevealMode(page, miniHit.locator, drawerAlreadyOpen, ctx.viewport).catch(() => "unknown");
       dlog2(ctx, `step 7 open-minicart: cartRevealMode=${cartRevealMode}`);
-      const openResult = await openMinicart(page, miniHit, ctx, expectedProductTitle);
+      let openResult = await openMinicart(page, miniHit, ctx, expectedProductTitle);
       cartOpenMethod = openResult.method;
+      revealDiagnostics = openResult.diagnostics;
+      if (cartOpenMethod === "failed" && revealDiagnostics && budget.remaining > 0) {
+        const recovery = await attemptRecovery(page, ctx, "open-minicart", "Abrir o minicart/drawer do carrinho — o trigger foi clicado mas o drawer não revelou", [miniHit.selector], summarizeCartRevealDiagnostics(revealDiagnostics));
+        if (recovery) {
+          budget.remaining--;
+          miniHit = recovery;
+          miniRecovered = true;
+          openResult = await openMinicart(page, miniHit, ctx, expectedProductTitle);
+          cartOpenMethod = openResult.method;
+          revealDiagnostics = openResult.diagnostics;
+        }
+      }
     } else {
       if (drawerAlreadyOpen) {
         cartOpenMethod = "already-open";
@@ -51938,6 +52103,7 @@ async function flowPurchaseJourney(ctx) {
     const isProdCartEmptyQuirk = ctx.acceptProdQuirks === true && ctx.side === "prod" && step7Validation !== undefined && !step7Validation.found && cartEmptyReason.startsWith("cart genuinely empty");
     const step7Status = isProdCartEmptyQuirk ? "skipped" : cartOpenMethod === "failed" ? "failed" : step7Validation && !step7Validation.found ? "failed" : "ok";
     const step7QuirkNote = isProdCartEmptyQuirk ? "cart-empty-prod-quirk: aceito via --accept-prod-quirks (cartRevealMode validated by separate check)" : undefined;
+    const step7RevealFailureNote = cartOpenMethod === "failed" && revealDiagnostics ? `minicart não revelou — ${summarizeCartRevealDiagnostics(revealDiagnostics)}` : undefined;
     steps.push({
       step: 7,
       name: "open-minicart",
@@ -51952,13 +52118,14 @@ async function flowPurchaseJourney(ctx) {
       cartOpenMethod,
       cartRevealMode,
       cartValidation: step7Validation,
-      note: step7QuirkNote,
+      diagnostics: revealDiagnostics,
+      note: step7QuirkNote ?? step7RevealFailureNote,
       actionDescription: miniHit ? `Abriu minicart via ${cartOpenMethod}${miniText ? ` em '${miniText.slice(0, 30).trim()}'` : ""} (\`${miniHit.selector}\`)${miniRecovered ? " — selector via recovery LLM" : ""}${step7Validation ? step7Validation.found ? " ✓ produto encontrado no cart" : ` ✗ produto ESPERADO não encontrado (${step7Validation.observedTitles?.length ?? 0} itens observados)` : ""}` : cartOpenMethod === "already-open" ? "Minicart já estava aberto após add-to-cart" : "Minicart não pôde ser aberto",
       selectorKey: miniHit ? "minicartTrigger" : undefined,
       usedSelector: miniHit?.selector,
       recoveredByLlm: miniRecovered || undefined
     });
-    reportEnd(7, "open-minicart", step7Status, Date.now() - t7, step7QuirkNote);
+    reportEnd(7, "open-minicart", step7Status, Date.now() - t7, step7QuirkNote ?? step7RevealFailureNote);
     if (isProdCartEmptyQuirk) {
       const quirkNote = "cart-empty-prod-quirk: skipped (depende do cart que prod não persistiu)";
       reportStart(8, "shipping-calc-cart");
@@ -52299,9 +52466,22 @@ async function findPlusButtonNear(input) {
   return null;
 }
 async function validateAddToCart(page, ctx, cartCountBefore, beforeUrl) {
-  const deadline = Date.now() + resolveAddToCartConfirmMs(ctx.rc);
+  const startedAt = Date.now();
+  const budgetMs = resolveAddToCartConfirmMs(ctx.rc);
+  const deadline = startedAt + budgetMs;
   let lastErrorText;
+  let pollCount = 0;
+  const drawerSelectors = [
+    ...selFor(ctx, "cartOpenedIndicator"),
+    "[role='dialog']",
+    "[data-minicart][aria-expanded='true']",
+    "[data-cart-drawer].open",
+    "[data-minicart-drawer]:not([hidden])",
+    ".minicart--open",
+    ".cart-drawer--open"
+  ];
   while (Date.now() < deadline) {
+    pollCount++;
     const currentUrl = page.url();
     if (currentUrl !== beforeUrl && /\/(cart|carrinho|checkout)(\/|$|\?)/i.test(currentUrl)) {
       return {
@@ -52318,15 +52498,6 @@ async function validateAddToCart(page, ctx, cartCountBefore, beforeUrl) {
         note: `Contador do minicart foi de ${cartCountBefore} para ${cartCountNow}`
       };
     }
-    const drawerSelectors = [
-      ...selFor(ctx, "cartOpenedIndicator"),
-      "[role='dialog']",
-      "[data-minicart][aria-expanded='true']",
-      "[data-cart-drawer].open",
-      "[data-minicart-drawer]:not([hidden])",
-      ".minicart--open",
-      ".cart-drawer--open"
-    ];
     for (const sel of drawerSelectors) {
       const el = page.locator(sel).first();
       if (await el.isVisible({ timeout: 200 }).catch(() => false)) {
@@ -52359,18 +52530,32 @@ async function validateAddToCart(page, ctx, cartCountBefore, beforeUrl) {
     } catch {}
     await page.waitForTimeout(250);
   }
+  const diagnostics = {
+    timedOut: true,
+    budgetMs,
+    elapsedMs: Date.now() - startedAt,
+    pollCount,
+    probes: await Promise.all(drawerSelectors.map(async (selector) => {
+      const loc = page.locator(selector).first();
+      const present = await loc.count().catch(() => 0) > 0;
+      const visible = present ? await loc.isVisible({ timeout: 200 }).catch(() => false) : false;
+      return { selector, present, visible };
+    }))
+  };
   if (lastErrorText) {
     return {
       status: "failed",
       signal: "error-text",
       note: `add-to-cart silenciosamente falhou: '${lastErrorText}' visível na página`,
-      errorText: lastErrorText
+      errorText: lastErrorText,
+      diagnostics
     };
   }
   return {
     status: "failed",
     signal: "no-signal",
-    note: "add-to-cart sem confirmação visível (minicart não atualizou, sem drawer, sem mudança de URL)"
+    note: "add-to-cart sem confirmação visível (minicart não atualizou, sem drawer, sem mudança de URL)",
+    diagnostics
   };
 }
 
@@ -54988,6 +55173,19 @@ async function e2eCommand(opts) {
       quiet: opts.json === true
     });
   }
+  const E2E_TIMEOUT_MS = 3 * 60 * 1000;
+  const watchdogScript = `setTimeout(()=>{try{process.kill(${process.pid},9)}catch(_){}},${E2E_TIMEOUT_MS})`;
+  const watchdog = spawn(process.execPath, ["-e", watchdogScript], {
+    stdio: "ignore",
+    detached: false
+  });
+  watchdog.unref();
+  const onSignal = () => {
+    watchdog.kill();
+    process.exit(1);
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
   const spinner = opts.json ? null : ora4("Lançando browser…").start();
   let browser = null;
   const allFlows = [];
@@ -55031,6 +55229,9 @@ async function e2eCommand(opts) {
     if (spinner)
       spinner.succeed(`${allFlows.length} flow capture(s), ${allPages.length} página(s)`);
   } finally {
+    watchdog.kill();
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
     await browser?.close().catch(() => {
       return;
     });
@@ -58406,17 +58607,6 @@ function formatSecs(ms) {
   return `${min}m${sec.toString().padStart(2, "0")}s`;
 }
 
-// src/util/localhost.ts
-var LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"]);
-function isLocalhost(rawUrl) {
-  try {
-    const url = new URL(rawUrl);
-    return LOCALHOST_HOSTS.has(url.hostname);
-  } catch {
-    return false;
-  }
-}
-
 // src/util/timing.ts
 async function withTiming(fn) {
   const start = performance.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/parity",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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",