@decocms/parity 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ 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.4.0](https://github.com/decocms/parity/compare/v0.3.0...v0.4.0) (2026-05-27)
+
+
+### Added
+
+* **journey:** extract product title on PDP and validate the same product appears in cart drawer (step 6) and on checkout page (step 8). 30+ selectors cover VTEX legacy, checkout6, FastStore, Wake. ([PR #11](https://github.com/decocms/parity/pull/11))
+* **journey:** viewport-aware minicart open strategy — desktop tries hover first (popup-style minicarts on VTEX prod), mobile tries `tap()` first (real touch event bypasses overlay handlers that swallow synthetic clicks). Adds `force: true` click + goto-href fallback when interactive strategies fail.
+* **journey:** `dismissOverlays` actively closes cookie banners, add-to-cart toasts and `[role=alertdialog]` before interacting with the minicart trigger.
+* **journey:** `waitForCartHydration` waits for the orderForm XHR + first cart-item selector before validation runs after `page.goto('/checkout/#/cart')`.
+* **journey:** step 8 advance-checkout mode — when URL is already on a checkout subpage, prepends 15 next-step selectors (`#cart-to-orderform`, `a.orange-btn`, `:has-text('Continuar para pagamento')`, etc.) and waits for URL change instead of a `/checkout` match.
+* **journey:** empty-cart banner detection populates `step.cartValidation.reason` to distinguish "cart genuinely empty (session not persisting)" from "selectors don't match markup".
+* **journey:** `DEBUG_PARITY=1` env var enables structured per-step + per-substep dlog output to stderr.
+* **schema:** `StepCapture.cartValidation` (expectedTitle, found, method, observedTitles, reason) and `cartOpenMethod` (click | click-navigate | hover | already-open | failed) for report traceability.
+
+
+### Fixed
+
+* **journey:** `collectCandidateLinks` 15s budget + per-op `withCap` race — prevents indefinite hang when the page V8 main thread is wedged by memory leaks (CDP messages queue past `locator.count()` declared timeout).
+* **journey:** page-close cap of 5s in the flow timeout cleanup — closes never block the next flow indefinitely on a wedged page.
+* **journey:** flow-timeout step renamed from `visit-home` to `flow-timeout` so the summary shows honestly which step the deadline aborted.
+* **journey:** isReachedCheckout regex accepts 13 checkout-flow URL markers (VTEX `/checkout`, Shopify `/checkouts`, Wake `/pedido`, Magento `/onepage`, Nuvemshop `/finalizar`, custom `/secure`, `/pagamento`, etc.) — no longer too strict to VTEX-only patterns.
+* **journey:** `validateCartContainsTitle` scope-qualifies the `[data-product-name]` selector to cart/drawer/checkout/minicart context — prevents false positives where the PDP `<h1>` matched the cart-context selector.
+* **journey:** `validateCartContainsTitle` retries after 2s on empty observation — catches in-flight cart-items XHR finishing slightly late.
+* **journey:** `waitForCartHydration` uses Promise.race (not Promise.all) so the faster of orderForm-XHR / cart-item-selector signals wins, avoiding 8s stalls when one probe never matches.
+* **llm:** `tryRepairJson` recovers from truncated/fenced tool-call arguments returned by some OpenRouter-backed models.
+* **llm:** recovery prompt accepts `a[href*=checkout]` when qualified by text or scope (e.g. `:has-text('Finalizar')`, `[role=dialog] …`). Previous version was too strict and the LLM returned null even when the right element was findable.
+
+## [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

@@ -99,7 +99,15 @@ var StepCapture = z.object({
   actionDescription: z.string().optional(),
   beforeUrl: z.string().optional(),
   screenshotBeforePath: z.string().optional(),
-  tracePath: z.string().optional()
+  tracePath: z.string().optional(),
+  cartValidation: z.object({
+    expectedTitle: z.string(),
+    found: z.boolean(),
+    method: z.enum(["selector", "llm", "none"]).optional(),
+    observedTitles: z.array(z.string()).optional(),
+    reason: z.string().optional()
+  }).optional(),
+  cartOpenMethod: z.enum(["click", "click-navigate", "hover", "already-open", "failed"]).optional()
 });
 var FlowCapture = z.object({
   flow: FlowName,
@@ -931,6 +939,15 @@ async function stopTracing(ctx, path) {
 }
 
 // src/engine/collect.ts
+var DEBUG_PARITY = process.env.DEBUG_PARITY === "1" || process.env.DEBUG_PARITY === "true";
+var DEBUG_START = Date.now();
+function dlog(side, viewport, msg) {
+  if (!DEBUG_PARITY)
+    return;
+  const elapsed = ((Date.now() - DEBUG_START) / 1000).toFixed(1);
+  process.stderr.write(`[+${elapsed}s ${viewport}/${side}] ${msg}
+`);
+}
 var VITALS_INIT_SCRIPT = `
   (function() {
     if (window.__parity_vitals_installed) return;
@@ -1141,10 +1158,12 @@ async function capturePage(page, opts) {
   let html = "";
   const inner = async () => {
     try {
+      dlog(opts.side, opts.viewport, `    capturePage: goto(${opts.url}) start`);
       response = await page.goto(opts.url, {
         waitUntil: "domcontentloaded",
         timeout: Math.min(opts.timeoutMs ?? 30000, remaining())
       });
+      dlog(opts.side, opts.viewport, `    capturePage: goto done status=${response?.status() ?? "?"} (remaining=${remaining()}ms)`);
       finalUrl = page.url();
       if (response) {
         const headers = response.headers();
@@ -1156,20 +1175,25 @@ async function capturePage(page, opts) {
         });
         await page.waitForTimeout(Math.min(opts.settleMs ?? 1200, remaining()));
       } else {
+        dlog(opts.side, opts.viewport, `    capturePage: waitForLoadState('load') (cap=${Math.min(12000, remaining())}ms)`);
         await page.waitForLoadState("load", { timeout: Math.min(12000, remaining()) }).catch(() => {
           return;
         });
+        dlog(opts.side, opts.viewport, `    capturePage: waitForLoadState('networkidle') (cap=${Math.min(6000, remaining())}ms)`);
         await page.waitForLoadState("networkidle", { timeout: Math.min(6000, remaining()) }).catch(() => {
           return;
         });
+        dlog(opts.side, opts.viewport, `    capturePage: settle (cap=${Math.min(opts.settleMs ?? 2000, remaining())}ms)`);
         await page.waitForTimeout(Math.min(opts.settleMs ?? 2000, remaining()));
         if (opts.scrollToLoad !== false && remaining() > 3000) {
+          dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage start (remaining=${remaining()}ms)`);
           await Promise.race([
             scrollFullPage(page).catch(() => {
               return;
             }),
             new Promise((resolve) => setTimeout(resolve, Math.min(1e4, remaining())))
           ]);
+          dlog(opts.side, opts.viewport, `    capturePage: scrollFullPage done (remaining=${remaining()}ms)`);
           await page.waitForTimeout(Math.min(600, remaining()));
         }
       }
@@ -1179,23 +1203,29 @@ async function capturePage(page, opts) {
         text: `[navigation-error] ${err.message}`
       });
     }
+    dlog(opts.side, opts.viewport, `    capturePage: vitals evaluate (cap=${Math.min(5000, remaining())}ms)`);
     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) {
+      dlog(opts.side, opts.viewport, `    capturePage: screenshot start (cap=${Math.min(15000, remaining())}ms)`);
       await Promise.race([
         page.screenshot({ path: opts.screenshotPath, fullPage: true, animations: "disabled" }).catch(() => {
           return;
         }),
         new Promise((resolve) => setTimeout(resolve, Math.min(15000, remaining())))
       ]);
+      dlog(opts.side, opts.viewport, "    capturePage: screenshot done");
     }
+    dlog(opts.side, opts.viewport, `    capturePage: page.content() (cap=${Math.min(5000, remaining())}ms)`);
     html = await Promise.race([
       page.content().catch(() => ""),
       new Promise((resolve) => setTimeout(() => resolve(""), Math.min(5000, remaining())))
     ]);
+    dlog(opts.side, opts.viewport, `    capturePage: flushCollectors (cap=${Math.min(3000, remaining())}ms)`);
     await flushCollectors(state, Math.min(3000, remaining()));
+    dlog(opts.side, opts.viewport, `    capturePage: inner done total=${Date.now() - start}ms`);
     return buildPartial();
   };
   const SAFETY_MARGIN_MS = 1e4;
@@ -4491,10 +4521,17 @@ async function callOpenRouterTool(params) {
     const json = await response.json();
     const toolCall = json.choices?.[0]?.message?.tool_calls?.[0];
     if (toolCall?.function?.name === params.tool.name) {
+      const raw = toolCall.function.arguments ?? "";
       try {
-        return JSON.parse(toolCall.function.arguments);
-      } catch (err) {
-        console.error(`[llm-openrouter] failed to parse tool arguments: ${err.message}`);
+        return JSON.parse(raw);
+      } catch {
+        const repaired = tryRepairJson(raw);
+        if (repaired) {
+          try {
+            return JSON.parse(repaired);
+          } catch {}
+        }
+        console.error(`[llm-openrouter] failed to parse tool arguments (raw len=${raw.length}, head=${JSON.stringify(raw.slice(0, 80))})`);
         return null;
       }
     }
@@ -4511,6 +4548,56 @@ async function callOpenRouterTool(params) {
   }
   return null;
 }
+function tryRepairJson(raw) {
+  let s = raw.trim();
+  if (!s)
+    return null;
+  const fence = s.match(/^```(?:json)?\s*([\s\S]*?)\s*```\s*$/);
+  if (fence?.[1])
+    s = fence[1].trim();
+  if (!s.startsWith("{") && !s.startsWith("["))
+    return null;
+  let depthObj = 0;
+  let depthArr = 0;
+  let inString = false;
+  let isEscaped = false;
+  for (let i = 0;i < s.length; i++) {
+    const ch = s[i];
+    if (isEscaped) {
+      isEscaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      isEscaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString)
+      continue;
+    if (ch === "{")
+      depthObj++;
+    else if (ch === "}")
+      depthObj--;
+    else if (ch === "[")
+      depthArr++;
+    else if (ch === "]")
+      depthArr--;
+  }
+  if (inString)
+    s += '"';
+  while (depthArr > 0) {
+    s += "]";
+    depthArr--;
+  }
+  while (depthObj > 0) {
+    s += "}";
+    depthObj--;
+  }
+  return s;
+}
 async function callMessage(params) {
   const provider = getProvider();
   if (provider === "anthropic")
@@ -4794,15 +4881,55 @@ function compactHtmlForRecovery(html, maxChars = 12000) {
     return html.slice(0, maxChars);
   }
 }
+var RECOVERY_SYSTEM_PROMPT = `
+Você ajuda a recuperar passos de teste E2E (Playwright) que falharam contra sites de e-commerce.
+
+Receba o nome do step, a ação desejada e o HTML compactado da página ATUAL. Sugira UM seletor + ação ('click' | 'fill' | 'press') que provavelmente funciona NESTE HTML específico.
+
+REGRAS CRÍTICAS:
+
+1. **Baseie no HTML fornecido.** Encontre o elemento literal no markup. Confirme mentalmente que o seletor que você vai retornar casa um elemento VISÍVEL no HTML compactado.
+
+2. **Se o step é 'go-checkout' ou 'go-checkout-retry':**
+   - O alvo é um BOTÃO/LINK CTA com texto visível contendo "Finalizar", "Finalizar compra", "Continuar", "Continuar para pagamento", "Ir para o checkout", "Checkout", "Concluir", "Pagar", "Ir para o pagamento", "Avançar", "Próxima etapa".
+   - **NUNCA** sugira o ícone genérico de carrinho do HEADER (texto curto "0", "1", badge counter, ou aria-label "Carrinho" sozinho). Esse é o gatilho que ABRE o drawer/cart-page, não o que finaliza compra.
+   - **Selectors com href de checkout (\`a[href*="checkout"]\`, \`a[href="/checkout/#/cart?v=1"]\`) PODEM funcionar** mas SOMENTE quando qualificados — ou seja, garanta uma das duas:
+     a. Qualificação por **texto**: \`a[href*="checkout"]:has-text('Finalizar')\`, \`a[href*="checkout"]:has-text('Continuar')\`
+     b. Qualificação por **scope**: \`[role='dialog'] a[href*="checkout"]\`, \`[class*='minicart' i] a[href*="checkout"]\`, \`.cart-drawer a[href*="checkout"]\`
+     Selectors GENÉRICOS sem qualificador (apenas \`a[href*="checkout"]\` sozinho) casam o ícone do header e devem ser EVITADOS.
+   - Se NENHUM elemento com texto/scope plausível existe no HTML, retorne selector="" para sinalizar incerteza honestamente.
+
+3. **Se o step é 'shipping-calc-cart' ou 'shipping-calc-pdp':**
+   - O alvo é um \`<input>\` (não button/link) visível com label/placeholder mencionando "CEP", "Frete", "Calcular", "Entrega", "Zip".
+   - Prefira inputs cujo container/pai está visível (não escondido em accordion fechado).
+
+4. **Seletores preferidos** (nesta ordem):
+   - Text-based Playwright: \`button:has-text('Finalizar')\`, \`a:has-text('Continuar para pagamento')\`
+   - data-attributes específicos: \`[data-checkout-button]\`, \`[data-cart-finalize]\`, \`[data-fs-cart-button]\`
+   - ARIA: \`[aria-label*='finalizar' i]\`, \`[role='button'][aria-label*='checkout' i]\`
+   - Classes específicas de plataforma: \`.vtex-minicart-2-x-checkoutButton\`, \`.fs-cart__checkout\`
+   - Por último, escopo hierárquico curto: \`[role='dialog'] button.cta\`, \`.minicart-drawer button[type='submit']\`
+
+5. **EVITE:**
+   - IDs hash-gerados (\`#r-abc123\`)
+   - Tailwind utility classes encadeadas (\`.flex.items-center.bg-blue\`)
+   - Seletores genéricos sem qualificador (\`a[href*=...]\`, \`button[type=submit]\` sozinho)
+   - Seletores que casam o ELEMENTO ERRADO em outra parte do DOM (ex: link de "checkout your reviews" no footer)
+   - Seletores muito profundos (>4 níveis hierárquicos)
+
+6. **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.
+
+Responda SEMPRE via tool_use suggest_recovery.
+`.trim();
 async function suggestRecovery(input) {
   const compacted = compactHtmlForRecovery(input.html);
   const inp = await callTool({
-    systemPrompt: "Você ajuda a recuperar passos de teste E2E (Playwright) que falharam. Receba o nome do step, a ação desejada e o HTML atual da página. Sugira UM seletor e ação ('click' | 'fill' | 'press') que provavelmente funciona. Para 'fill', preferir input visível com label relacionada. Para 'click', preferir botão visível com texto/label que case com a intenção. Use Playwright selectors quando apropriado (`button:has-text('X')`, `[role='button']`). Não invente seletores genéricos; baseie no HTML fornecido.",
+    systemPrompt: RECOVERY_SYSTEM_PROMPT,
     userText: `Step: ${input.stepName}
 Ação desejada: ${input.intendedAction}
-${input.alreadyTried?.length ? `Já tentei: ${input.alreadyTried.join(", ")}
+${input.alreadyTried?.length ? `Já tentei (não repita estes): ${input.alreadyTried.join(", ")}
 ` : ""}
-HTML compactado:
+HTML compactado da página NESTE momento:
 \`\`\`html
 ${compacted}
 \`\`\``,
@@ -4813,9 +4940,9 @@ ${compacted}
       inputSchema: RECOVER_STEP_INPUT_SCHEMA
     }
   });
-  if (inp?.selector && inp.action) {
+  if (inp?.selector?.trim() && inp.action) {
     return {
-      selector: inp.selector,
+      selector: inp.selector.trim(),
       action: inp.action,
       value: inp.value,
       reasoning: inp.reasoning
@@ -5056,22 +5183,79 @@ function isResolutionContext(v) {
 
 // src/engine/flows.ts
 var PURCHASE_JOURNEY_TOTAL_STEPS = 8;
+var DEBUG_PARITY2 = process.env.DEBUG_PARITY === "1" || process.env.DEBUG_PARITY === "true";
+var DEBUG_START2 = Date.now();
+function dlog2(ctx, msg) {
+  if (!DEBUG_PARITY2)
+    return;
+  const elapsed = ((Date.now() - DEBUG_START2) / 1000).toFixed(1);
+  process.stderr.write(`[+${elapsed}s ${ctx.viewport}/${ctx.side}] ${msg}
+`);
+}
 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: "flow-timeout",
+          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));
+      const CLOSE_CAP_MS = 5000;
+      const cappedClose = (p) => Promise.race([
+        p.close().catch(() => {
+          return;
+        }),
+        new Promise((resolve2) => setTimeout(resolve2, CLOSE_CAP_MS))
+      ]);
+      cleanup = Promise.allSettled(pages.map(cappedClose));
+    }, 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) {
@@ -5178,12 +5362,15 @@ async function flowPurchaseJourney(ctx) {
   };
   try {
     reportStart(1, "visit-home");
+    dlog2(ctx, `step 1 visit-home: capturePage(${ctx.baseUrl}) start (scrollToLoad=false)`);
     const homeCap = await capturePage(page, {
       url: ctx.baseUrl,
       side: ctx.side,
       viewport: ctx.viewport,
-      screenshotPath: screenshotPath(ctx, "pj-1-home")
+      screenshotPath: screenshotPath(ctx, "pj-1-home"),
+      scrollToLoad: false
     });
+    dlog2(ctx, `step 1 visit-home: capturePage done status=${homeCap.status}`);
     pages.push(homeCap);
     const step1Status = homeCap.status >= 200 && homeCap.status < 400 ? "ok" : "failed";
     steps.push({
@@ -5202,19 +5389,24 @@ async function flowPurchaseJourney(ctx) {
       return { pages, steps };
     }
     reportStart(2, "navigate-plp");
+    dlog2(ctx, `step 2 navigate-plp: findCategoryUrl start (hint=${ctx.rc.plpUrlHint ?? "—"})`);
     const plpHit = ctx.rc.plpUrlHint ? { url: new URL(ctx.rc.plpUrlHint, ctx.baseUrl).toString(), selector: "__hint__" } : await findCategoryUrl(page, ctx);
+    dlog2(ctx, `step 2 navigate-plp: findCategoryUrl done → ${plpHit?.url ?? "null"}`);
     if (!plpHit) {
       steps.push(makeSkipStep(2, "navigate-plp", ctx, "no category link found"));
       reportEnd(2, "navigate-plp", "skipped", 0, "no category link found");
       return { pages, steps };
     }
     const t2 = Date.now();
+    dlog2(ctx, `step 2 navigate-plp: capturePage(${plpHit.url}) start (scrollToLoad=false)`);
     const plpCap = await capturePage(page, {
       url: plpHit.url,
       side: ctx.side,
       viewport: ctx.viewport,
-      screenshotPath: screenshotPath(ctx, "pj-2-plp")
+      screenshotPath: screenshotPath(ctx, "pj-2-plp"),
+      scrollToLoad: false
     });
+    dlog2(ctx, `step 2 navigate-plp: capturePage done status=${plpCap.status}`);
     pages.push(plpCap);
     const step2Status = plpCap.status >= 200 && plpCap.status < 400 ? "ok" : "failed";
     steps.push({
@@ -5244,7 +5436,8 @@ async function flowPurchaseJourney(ctx) {
       url: pdpHit.url,
       side: ctx.side,
       viewport: ctx.viewport,
-      screenshotPath: screenshotPath(ctx, "pj-3-pdp")
+      screenshotPath: screenshotPath(ctx, "pj-3-pdp"),
+      scrollToLoad: false
     });
     pages.push(pdpCap);
     const step3Status = pdpCap.status >= 200 && pdpCap.status < 400 ? "ok" : "failed";
@@ -5263,8 +5456,25 @@ async function flowPurchaseJourney(ctx) {
     reportEnd(3, "enter-pdp", step3Status, Date.now() - t3);
     steps[steps.length - 1].actionDescription = `Abriu PDP \`${pdpHit.url}\` (via \`${pdpHit.selector}\`)`;
     steps[steps.length - 1].beforeUrl = plpHit.url;
+    const expectedProductTitle = await extractProductTitle(page);
+    dlog2(ctx, `step 3 enter-pdp: extracted product title → ${expectedProductTitle ? `"${expectedProductTitle.slice(0, 60)}"` : "null"}`);
+    if (expectedProductTitle) {
+      steps[steps.length - 1].detail = {
+        ...steps[steps.length - 1].detail ?? {},
+        productTitle: expectedProductTitle
+      };
+    }
     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();
@@ -5289,14 +5499,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");
@@ -5364,37 +5575,79 @@ async function flowPurchaseJourney(ctx) {
         recoveryBudget--;
       }
     }
+    let cartOpenMethod = "failed";
     let miniText = "";
     if (miniHit) {
       miniText = await miniHit.locator.innerText().catch(() => "");
-      await miniHit.locator.click({ timeout: 3000 }).catch(() => {
-        return;
-      });
-      await page.waitForTimeout(1500);
+      const openResult = await openMinicart(page, miniHit, ctx, expectedProductTitle);
+      cartOpenMethod = openResult.method;
+    } else {
+      const alreadyOpen = await isCartRevealed(page, expectedProductTitle);
+      if (alreadyOpen) {
+        cartOpenMethod = "already-open";
+        dlog2(ctx, `step 6 open-minicart: no trigger, but drawer already visible (matched ${alreadyOpen})`);
+      }
+    }
+    let step6Validation;
+    if (expectedProductTitle && cartOpenMethod !== "failed") {
+      const v = await validateCartContainsTitle(page, expectedProductTitle, ctx);
+      let reasonText;
+      if (!v.found) {
+        if (v.observedTitles.length === 0) {
+          const emptyBanner = await detectEmptyCartBanner(page);
+          reasonText = emptyBanner ? `cart genuinely empty — upstream add-to-cart didn't persist (session/cookie may not have carried over). Banner observed: "${emptyBanner}"` : "no cart line items visible after open (selectors may not match markup)";
+        } else {
+          reasonText = `expected title not found among ${v.observedTitles.length} observed`;
+        }
+      }
+      step6Validation = {
+        expectedTitle: expectedProductTitle,
+        found: v.found,
+        method: v.method,
+        observedTitles: v.observedTitles.slice(0, 8),
+        reason: reasonText
+      };
+      dlog2(ctx, `step 6 open-minicart: cart validation → found=${v.found} (${v.method})${reasonText ? ` — ${reasonText.slice(0, 80)}` : ""}`);
+    } else if (!expectedProductTitle) {
+      dlog2(ctx, "step 6 open-minicart: skipping validation — no PDP title captured");
+    } else {
+      dlog2(ctx, "step 6 open-minicart: skipping validation — cart UI not revealed");
     }
     const sp6 = screenshotPath(ctx, "pj-6-minicart");
     await page.screenshot({ path: sp6, fullPage: false }).catch(() => {
       return;
     });
+    const step6Status = cartOpenMethod === "failed" ? "failed" : step6Validation && !step6Validation.found ? "failed" : "ok";
     steps.push({
       step: 6,
       name: "open-minicart",
       side: ctx.side,
       viewport: ctx.viewport,
-      status: "ok",
+      status: step6Status,
       durationMs: Date.now() - t6,
       url: page.url(),
       screenshotPath: sp6,
       screenshotBeforePath: spBefore6,
       beforeUrl: beforeUrl6,
-      actionDescription: miniHit ? `Clicou no trigger do minicart${miniText ? ` '${miniText.slice(0, 30).trim()}'` : ""} (\`${miniHit.selector}\`)${miniRecovered ? " — selector via recovery LLM" : ""}` : "Minicart já aberto após add-to-cart (drawer/popup)",
+      cartOpenMethod,
+      cartValidation: step6Validation,
+      actionDescription: miniHit ? `Abriu minicart via ${cartOpenMethod}${miniText ? ` em '${miniText.slice(0, 30).trim()}'` : ""} (\`${miniHit.selector}\`)${miniRecovered ? " — selector via recovery LLM" : ""}${step6Validation ? step6Validation.found ? " ✓ produto encontrado no cart" : ` ✗ produto ESPERADO não encontrado (${step6Validation.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(6, "open-minicart", "ok", Date.now() - t6);
+    reportEnd(6, "open-minicart", step6Status, 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();
@@ -5419,21 +5672,83 @@ 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");
-    let checkoutHit = await firstVisibleLocator(page, selFor(ctx, "checkoutButton"));
+    const beforeStep8Url = page.url();
+    const alreadyInCheckoutPage = /\/(checkout|cart|carrinho)(\/|#|$|\?)/i.test(beforeStep8Url);
+    dlog2(ctx, `step 8 go-checkout: beforeUrl=${beforeStep8Url} alreadyInCheckoutPage=${alreadyInCheckoutPage}`);
+    if (!alreadyInCheckoutPage) {
+      const drawerStillOpen = await firstVisible(page, [
+        "[role='dialog']:visible",
+        "[aria-modal='true']:visible",
+        "[data-minicart][aria-hidden='false']",
+        ".minicart--open",
+        ".minicart-drawer:not([hidden])",
+        "[class*='minicart'][class*='open']",
+        "[class*='cart-drawer'][class*='open']"
+      ]);
+      if (!drawerStillOpen) {
+        dlog2(ctx, "step 8 go-checkout: drawer appears closed, re-clicking minicart trigger");
+        const reTrigger = await firstVisibleLocator(page, selFor(ctx, "minicartTrigger"));
+        if (reTrigger) {
+          await reTrigger.locator.click({ timeout: 3000 }).catch(() => {
+            return;
+          });
+          await page.waitForTimeout(1500);
+          dlog2(ctx, `step 8 go-checkout: re-opened drawer via ${reTrigger.selector}`);
+        } else {
+          dlog2(ctx, "step 8 go-checkout: minicartTrigger not found — drawer state unknown");
+        }
+      } else {
+        dlog2(ctx, `step 8 go-checkout: drawer still open (matched ${drawerStillOpen})`);
+      }
+    }
+    const nextStepSelectors = alreadyInCheckoutPage ? [
+      "button:has-text('Continuar para pagamento')",
+      "a:has-text('Continuar para pagamento')",
+      "button:has-text('Ir para o pagamento')",
+      "a:has-text('Ir para o pagamento')",
+      "button:has-text('Continuar')",
+      "a:has-text('Continuar')",
+      "button:has-text('Avançar')",
+      "a:has-text('Avançar')",
+      "button:has-text('Próxima etapa')",
+      "a:has-text('Próxima etapa')",
+      "button:has-text('Confirmar')",
+      "button:has-text('Finalizar')",
+      "a:has-text('Finalizar')",
+      "#cart-to-orderform",
+      "#btn-go-to-payment",
+      ".btn-go-to-payment",
+      "a.btn-place-order",
+      "a.orange-btn",
+      ".cart-links-bottom a",
+      "button[type='submit'][class*='checkout' i]",
+      "button[type='submit'][class*='continue' i]",
+      "[data-checkout-next]",
+      "[data-fs-cart-checkout-button]"
+    ] : [];
+    const baseSelectors = selFor(ctx, "checkoutButton");
+    const checkoutSelectors = [...nextStepSelectors, ...baseSelectors];
+    dlog2(ctx, `step 8 go-checkout: firstVisibleLocator on ${checkoutSelectors.length} selectors${alreadyInCheckoutPage ? ` (${nextStepSelectors.length} next-step prefixed)` : ""}`);
+    let checkoutHit = await firstVisibleLocator(page, checkoutSelectors);
+    dlog2(ctx, `step 8 go-checkout: default match → ${checkoutHit ? `selector=${checkoutHit.selector}` : "null"}`);
     let checkoutRecovered = false;
     if (!checkoutHit && recoveryBudget > 0) {
-      const recovery = await attemptRecovery(page, ctx, "go-checkout", "Clicar no botão 'Finalizar compra' / 'Ir para o checkout'", selFor(ctx, "checkoutButton"));
+      const recoveryIntent = alreadyInCheckoutPage ? "Já estou no checkout (URL contém /checkout ou /cart). Achar o botão visível que avança pra próxima etapa do checkout (geralmente 'Continuar para pagamento', 'Continuar', 'Avançar', 'Próxima etapa', 'Confirmar', ou similar). NÃO é o ícone do header — é uma CTA primary na página." : "Clicar no botão 'Finalizar compra' / 'Ir para o checkout' / 'Finalizar' dentro do drawer/popup do carrinho aberto.";
+      dlog2(ctx, `step 8 go-checkout: defaults missed, calling attemptRecovery (budget=${recoveryBudget}, mode=${alreadyInCheckoutPage ? "advance-checkout" : "drawer-finalize"})`);
+      const recovery = await attemptRecovery(page, ctx, "go-checkout", recoveryIntent, checkoutSelectors);
+      dlog2(ctx, `step 8 go-checkout: LLM recovery → ${recovery ? `selector=${recovery.selector}` : "null"}`);
       if (recovery) {
         checkoutHit = recovery;
         checkoutRecovered = true;
@@ -5441,33 +5756,92 @@ async function flowPurchaseJourney(ctx) {
       }
     }
     if (!checkoutHit) {
+      dlog2(ctx, "step 8 go-checkout: no button found, skipping");
       steps.push(makeSkipStep(8, "go-checkout", ctx, "no checkout button found (recovery exhausted)"));
       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(() => "");
+      const urlBefore = page.url();
+      const urlChangePredicate = alreadyInCheckoutPage ? (u) => u.toString() !== urlBefore : /checkout/i;
+      await Promise.all([
+        page.waitForURL(urlChangePredicate, { 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);
-    const step8Status = reachedCheckout ? "ok" : "failed";
+      });
+      return { url: page.url(), spBefore, spAfter, clickedText: clickedText2 };
+    };
+    const t8 = Date.now();
+    const beforeUrl8 = page.url();
+    const CHECKOUT_URL_MARKERS = /\/(checkout|checkouts|finalize|finalizar|pagamento|payment|pedido|order|orderform|onepage|secure|seguro)(\/|#|$|\?|-)/i;
+    const isReachedCheckout = (finalUrl) => {
+      if (finalUrl === beforeUrl8)
+        return false;
+      return CHECKOUT_URL_MARKERS.test(finalUrl);
+    };
+    let attempt = 1;
+    dlog2(ctx, `step 8 go-checkout: tryCheckoutClick attempt 1 — selector=${checkoutHit.selector}, beforeUrl=${beforeUrl8}`);
+    let result = await tryCheckoutClick(checkoutHit, attempt);
+    let reachedCheckout = isReachedCheckout(result.url);
+    let usedSelector = checkoutHit.selector;
+    let clickedText = result.clickedText;
+    dlog2(ctx, `step 8 go-checkout: attempt 1 result — finalUrl=${result.url} reached=${reachedCheckout} clicked='${clickedText.slice(0, 40).trim()}'`);
+    if (!reachedCheckout && recoveryBudget > 0) {
+      dlog2(ctx, `step 8 go-checkout: attempt 1 missed target — calling attemptRecovery for retry (budget=${recoveryBudget}, mode=${alreadyInCheckoutPage ? "advance-checkout" : "drawer-finalize"})`);
+      const retryIntent = alreadyInCheckoutPage ? `Já estou no checkout, em ${beforeUrl8}. Cliquei em '${clickedText.slice(0, 40).trim()}' (selector \`${usedSelector}\`), mas a URL não mudou ou foi pra ${result.url}. Achar o botão que avança pra próxima etapa do checkout (Continuar para pagamento, Avançar, Próxima etapa, Confirmar, etc).` : `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.`;
+      const retrySuggestion = await attemptRecovery(page, ctx, "go-checkout-retry", retryIntent, [usedSelector, ...checkoutSelectors]);
+      dlog2(ctx, `step 8 go-checkout: retry LLM suggestion → ${retrySuggestion ? `selector=${retrySuggestion.selector}` : "null"}`);
+      if (retrySuggestion) {
+        recoveryBudget--;
+        checkoutRecovered = true;
+        attempt++;
+        dlog2(ctx, `step 8 go-checkout: tryCheckoutClick attempt 2 — selector=${retrySuggestion.selector}`);
+        const retryResult = await tryCheckoutClick(retrySuggestion, attempt);
+        result = retryResult;
+        usedSelector = retrySuggestion.selector;
+        clickedText = retryResult.clickedText;
+        reachedCheckout = isReachedCheckout(retryResult.url);
+        dlog2(ctx, `step 8 go-checkout: attempt 2 result — finalUrl=${retryResult.url} reached=${reachedCheckout} clicked='${retryResult.clickedText.slice(0, 40).trim()}'`);
+      }
+    } else if (!reachedCheckout) {
+      dlog2(ctx, `step 8 go-checkout: not retrying — recoveryBudget=${recoveryBudget}`);
+    }
+    let step8Validation;
+    if (expectedProductTitle && reachedCheckout) {
+      await page.waitForTimeout(1500);
+      const v = await validateCartContainsTitle(page, expectedProductTitle, ctx);
+      let reasonText;
+      if (!v.found) {
+        if (v.observedTitles.length === 0) {
+          const emptyBanner = await detectEmptyCartBanner(page);
+          reasonText = emptyBanner ? `checkout shows empty cart banner — upstream session lost. Banner: "${emptyBanner}"` : "checkout page has no visible line items (selectors may not match markup)";
+        } else {
+          reasonText = `expected title not found among ${v.observedTitles.length} observed on checkout`;
+        }
+      }
+      step8Validation = {
+        expectedTitle: expectedProductTitle,
+        found: v.found,
+        method: v.method,
+        observedTitles: v.observedTitles.slice(0, 8),
+        reason: reasonText
+      };
+      dlog2(ctx, `step 8 go-checkout: checkout validation → found=${v.found} (${v.method})${reasonText ? ` — ${reasonText.slice(0, 80)}` : ""}`);
+    }
+    const step8Status = reachedCheckout ? step8Validation && !step8Validation.found ? "failed" : "ok" : "failed";
     steps.push({
       step: 8,
       name: "go-checkout",
@@ -5475,13 +5849,14 @@ 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"}`,
+      cartValidation: step8Validation,
+      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)` : ""}${step8Validation ? step8Validation.found ? " ✓ produto persiste no checkout" : ` ✗ produto ESPERADO ausente no checkout (${step8Validation.observedTitles?.length ?? 0} itens observados)` : ""}`,
       selectorKey: "checkoutButton",
-      usedSelector: checkoutHit.selector,
+      usedSelector,
       recoveredByLlm: checkoutRecovered || undefined
     });
     reportEnd(8, "go-checkout", step8Status, Date.now() - t8);
@@ -5504,10 +5879,15 @@ function makeSkipStep(step, name, ctx, note) {
 }
 async function findCategoryUrl(page, ctx) {
   const selectors = selFor(ctx, "categoryLink");
+  dlog2(ctx, `  findCategoryUrl: collectCandidateLinks(${selectors.length} selectors) start`);
+  const t0 = Date.now();
   const candidates = await collectCandidateLinks(page, selectors, 12);
+  dlog2(ctx, `  findCategoryUrl: collectCandidateLinks done in ${Date.now() - t0}ms → ${candidates.length} candidates`);
   if (candidates.length === 0)
     return null;
+  dlog2(ctx, "  findCategoryUrl: pickCategoryLink LLM call start");
   const picked = await pickCategoryLink(candidates.map((c) => ({ text: c.text, href: c.href })));
+  dlog2(ctx, `  findCategoryUrl: pickCategoryLink LLM done → ${picked?.href ?? "null"}`);
   if (!picked)
     return null;
   const original = candidates.find((c) => c.href === picked.href);
@@ -5556,20 +5936,34 @@ async function firstVisibleLocator(page, selectors) {
   }
   return null;
 }
+var COLLECT_CANDIDATES_BUDGET_MS = 15000;
+function withCap(p, capMs, fallback) {
+  return Promise.race([
+    p.catch(() => fallback),
+    new Promise((resolve) => setTimeout(() => resolve(fallback), capMs))
+  ]);
+}
 async function collectCandidateLinks(page, selectors, limit = 12) {
   const out = [];
   const seenHrefs = new Set;
+  const deadline = Date.now() + COLLECT_CANDIDATES_BUDGET_MS;
+  const expired = () => Date.now() >= deadline;
   for (const sel of selectors) {
     if (out.length >= limit)
       break;
+    if (expired())
+      break;
     try {
       const elements = page.locator(sel);
-      const count = await elements.count();
+      const count = await withCap(elements.count(), 1000, 0);
       for (let i = 0;i < count && out.length < limit; i++) {
+        if (expired())
+          break;
         const el = elements.nth(i);
-        if (!await el.isVisible({ timeout: 250 }).catch(() => false))
+        const visible = await withCap(el.isVisible({ timeout: 250 }).catch(() => false), 400, false);
+        if (!visible)
           continue;
-        const href = await el.getAttribute("href").catch(() => null);
+        const href = await withCap(el.getAttribute("href").catch(() => null), 400, null);
         if (!href)
           continue;
         let abs = href;
@@ -5581,7 +5975,7 @@ async function collectCandidateLinks(page, selectors, limit = 12) {
         if (seenHrefs.has(abs))
           continue;
         seenHrefs.add(abs);
-        const text = (await el.innerText().catch(() => "")).slice(0, 60).trim();
+        const text = (await withCap(el.innerText().catch(() => ""), 400, "")).slice(0, 60).trim();
         out.push({ text, href: abs, selector: sel });
       }
     } catch {}
@@ -5600,6 +5994,386 @@ async function fillCep(page, selector, cep) {
     return false;
   }
 }
+var GENERIC_TITLE_PATTERNS = [
+  /^p[áa]gina de produto/i,
+  /^product page/i,
+  /^carregando/i,
+  /^loading/i,
+  /^undefined/i,
+  /^home$/i
+];
+function looksGeneric(s) {
+  const t = s.trim();
+  return GENERIC_TITLE_PATTERNS.some((re) => re.test(t));
+}
+async function extractProductTitle(page) {
+  await page.waitForSelector("h1", { timeout: 2500, state: "attached" }).catch(() => {
+    return;
+  });
+  const visibleSelectors = [
+    "main h1",
+    "h1[class*='product' i]",
+    "h1.product-title",
+    "[itemprop='name'][data-product-name]",
+    "[data-product-name]",
+    "[data-fs-product-title]",
+    "[itemprop='name']",
+    ".vtex-store-components-3-x-productNameContainer",
+    "h1"
+  ];
+  for (const sel of visibleSelectors) {
+    try {
+      const el = page.locator(sel).first();
+      const visible = await withCap(el.isVisible({ timeout: 250 }).catch(() => false), 400, false);
+      if (!visible)
+        continue;
+      const text = await withCap(el.innerText().catch(() => ""), 500, "");
+      const clean = text.trim();
+      if (clean.length > 3 && !looksGeneric(clean))
+        return clean;
+    } catch {}
+  }
+  try {
+    const jsonLdName = await withCap(page.evaluate(() => {
+      const scripts = Array.from(document.querySelectorAll('script[type="application/ld+json"]'));
+      for (const s of scripts) {
+        try {
+          const data = JSON.parse(s.textContent ?? "{}");
+          const items = Array.isArray(data) ? data : [data];
+          for (const item of items) {
+            const product = item?.["@graph"]?.find?.((x) => x?.["@type"] === "Product") ?? item;
+            if (product?.["@type"] === "Product" && typeof product.name === "string") {
+              return product.name;
+            }
+          }
+        } catch {}
+      }
+      return null;
+    }), 1000, null);
+    if (jsonLdName && jsonLdName.trim().length > 3 && !looksGeneric(jsonLdName)) {
+      return jsonLdName.trim();
+    }
+  } catch {}
+  try {
+    const og = await withCap(page.locator("meta[property='og:title']").first().getAttribute("content").catch(() => null), 500, null);
+    if (og && og.trim().length > 3 && !looksGeneric(og))
+      return og.trim();
+  } catch {}
+  const docTitle = await withCap(page.title().catch(() => ""), 500, "");
+  if (docTitle.trim().length > 3 && !looksGeneric(docTitle))
+    return docTitle.trim();
+  return null;
+}
+async function isCartUiVisible(page) {
+  return firstVisible(page, [
+    "[role='dialog']:visible",
+    "[aria-modal='true']:visible",
+    "[data-minicart][aria-hidden='false']",
+    "[data-minicart-open]",
+    ".minicart--open",
+    ".minicart-drawer:not([hidden])",
+    "[class*='minicart'][class*='open']",
+    "[class*='cart-drawer'][class*='open']",
+    "[class*='drawer-cart']:visible"
+  ]);
+}
+async function isCartRevealed(page, expectedProductTitle) {
+  if (expectedProductTitle) {
+    const v = await validateCartContainsTitleQuick(page, expectedProductTitle);
+    if (v)
+      return `title-found:${v}`;
+  }
+  return isCartUiVisible(page);
+}
+async function validateCartContainsTitleQuick(page, expectedTitle) {
+  const quickSelectors = [
+    "[role='dialog']",
+    "[class*='minicart' i]",
+    "[class*='cart' i]",
+    "[class*='checkout' i]",
+    "#cart-fixed",
+    "table.cart-items"
+  ];
+  for (const scope of quickSelectors) {
+    try {
+      const scopeLoc = page.locator(scope);
+      if (await withCap(scopeLoc.count(), 800, 0) === 0)
+        continue;
+      const text = await withCap(scopeLoc.first().innerText().catch(() => ""), 800, "");
+      if (text && titlesMatch(text, expectedTitle))
+        return scope;
+    } catch {}
+  }
+  return null;
+}
+async function dismissOverlays(page, ctx) {
+  const overlaySelectors = [
+    "[class*='cookie' i][class*='banner' i]",
+    "[class*='cookie' i][class*='consent' i]",
+    "[id*='cookie' i][class*='banner' i]",
+    "[role='alertdialog']:visible",
+    "[class*='toast' i]:visible",
+    "[class*='snackbar' i]:visible",
+    "[class*='added-to-cart' i]:visible",
+    "[class*='product-added' i]:visible"
+  ];
+  let dismissedAny = false;
+  for (const sel of overlaySelectors) {
+    try {
+      const overlay = page.locator(sel).first();
+      if (!await withCap(overlay.isVisible({ timeout: 200 }).catch(() => false), 400, false))
+        continue;
+      const closer = overlay.locator("button[aria-label*='close' i], button[aria-label*='fechar' i], button[class*='close' i], [data-close], [aria-label='Close']").first();
+      if (await withCap(closer.isVisible({ timeout: 200 }).catch(() => false), 400, false)) {
+        await closer.click({ timeout: 1500 }).catch(() => {
+          return;
+        });
+        dismissedAny = true;
+        continue;
+      }
+      await page.keyboard.press("Escape").catch(() => {
+        return;
+      });
+      dismissedAny = true;
+    } catch {}
+  }
+  if (dismissedAny) {
+    dlog2(ctx, "  openMinicart: dismissed overlay(s) before interacting");
+    await page.waitForTimeout(500);
+  }
+}
+async function waitForCartHydration(page) {
+  await Promise.race([
+    page.waitForResponse((r) => /\/api\/checkout\/pub\/orderForm|orderForm|cart\/api/i.test(r.url()) && r.ok(), { timeout: 8000 }).catch(() => {
+      return;
+    }),
+    page.waitForSelector(".cart-items, [class*='cart-item' i], #cart-fixed .item, [data-cart-item]", { timeout: 8000 }).catch(() => {
+      return;
+    })
+  ]);
+  await page.waitForTimeout(800);
+}
+async function openMinicart(page, trigger, ctx, expectedProductTitle) {
+  const beforeUrl = page.url();
+  await dismissOverlays(page, ctx);
+  await page.waitForTimeout(800);
+  const alreadyOpen = await isCartRevealed(page, expectedProductTitle);
+  if (alreadyOpen) {
+    dlog2(ctx, `  openMinicart: already-open (matched ${alreadyOpen})`);
+    return { method: "already-open", url: beforeUrl, visibleMarker: alreadyOpen };
+  }
+  const triggerHref = await trigger.locator.getAttribute("href").catch(() => null);
+  const hrefHasCartTarget = !!triggerHref && /\/(checkout|cart|carrinho)/i.test(triggerHref);
+  if (ctx.viewport === "desktop") {
+    dlog2(ctx, `  openMinicart: trying hover first on ${trigger.selector}${triggerHref ? ` (href=${triggerHref})` : ""}`);
+    await trigger.locator.hover({ timeout: 3000 }).catch(() => {
+      return;
+    });
+    await page.waitForTimeout(1500);
+    const hoverOpened = await isCartRevealed(page, expectedProductTitle);
+    if (hoverOpened) {
+      dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
+      return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
+    }
+  }
+  if (ctx.viewport === "mobile") {
+    dlog2(ctx, `  openMinicart: trying tap (mobile) on ${trigger.selector}`);
+    await Promise.all([
+      page.waitForURL((url) => url.toString() !== beforeUrl, { timeout: 4000 }).catch(() => {
+        return;
+      }),
+      trigger.locator.tap({ timeout: 4000 }).catch(() => {
+        return;
+      })
+    ]);
+    if (page.url() !== beforeUrl) {
+      await page.waitForLoadState("load", { timeout: 8000 }).catch(() => {
+        return;
+      });
+      await waitForCartHydration(page);
+      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);
+    if (tapOpened) {
+      dlog2(ctx, `  openMinicart: tap opened drawer (${tapOpened})`);
+      return { method: "click", url: page.url(), visibleMarker: tapOpened };
+    }
+  }
+  dlog2(ctx, `  openMinicart: trying force-click on ${trigger.selector}${triggerHref ? ` (href=${triggerHref})` : ""}`);
+  await Promise.all([
+    page.waitForURL((url) => url.toString() !== beforeUrl, { timeout: 4000 }).catch(() => {
+      return;
+    }),
+    trigger.locator.click({ force: true, timeout: 4000 }).catch(() => {
+      return;
+    })
+  ]);
+  const afterClickUrl = page.url();
+  if (afterClickUrl !== beforeUrl) {
+    await page.waitForLoadState("load", { timeout: 8000 }).catch(() => {
+      return;
+    });
+    await waitForCartHydration(page);
+    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);
+  if (clickOpened) {
+    dlog2(ctx, `  openMinicart: click opened drawer (${clickOpened})`);
+    return { method: "click", url: afterClickUrl, visibleMarker: clickOpened };
+  }
+  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);
+    if (hoverOpened) {
+      dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
+      return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
+    }
+  }
+  if (hrefHasCartTarget && triggerHref) {
+    const targetUrl = (() => {
+      try {
+        return new URL(triggerHref, page.url()).toString();
+      } catch {
+        return null;
+      }
+    })();
+    if (targetUrl) {
+      dlog2(ctx, `  openMinicart: all interactive strategies failed but trigger has cart href, navigating directly to ${targetUrl}`);
+      await page.goto(targetUrl, { waitUntil: "load", timeout: 15000 }).catch(() => {
+        return;
+      });
+      await waitForCartHydration(page);
+      if (page.url() !== beforeUrl) {
+        dlog2(ctx, `  openMinicart: goto fallback landed on ${page.url()}`);
+        return { method: "click-navigate", url: page.url(), visibleMarker: null };
+      }
+    }
+  }
+  dlog2(ctx, "  openMinicart: failed — no cart revealed by hover/click/goto");
+  return { method: "failed", url: page.url(), visibleMarker: null };
+}
+function normalizeTitle(s) {
+  return s.toLowerCase().replace(/[®©™]/g, "").replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
+}
+function titlesMatch(observed, expected) {
+  const o = normalizeTitle(observed);
+  const e = normalizeTitle(expected);
+  if (!o || !e)
+    return false;
+  if (o === e)
+    return true;
+  if (e.length >= 12 && o.includes(e))
+    return true;
+  if (o.length >= 12 && e.includes(o))
+    return true;
+  return false;
+}
+async function validateCartContainsTitle(page, expectedTitle, ctx) {
+  const titleSelectors = [
+    "[data-cart-item-name]",
+    "[data-cart-item] [class*='title' i]",
+    "[data-cart-item] [class*='name' i]",
+    "[class*='cart' i] [data-product-name]",
+    "[role='dialog'] [data-product-name]",
+    "[class*='checkout' i] [data-product-name]",
+    "[class*='minicart' i] [data-product-name]",
+    "[data-testid='cart-item-name']",
+    "[data-testid='product-name']",
+    "[role='dialog'] li [class*='product' i]",
+    "[role='dialog'] li [class*='name' i]",
+    "[role='dialog'] li [class*='title' i]",
+    "[role='dialog'] a[href*='/p']",
+    "[class*='minicart' i] [class*='item' i] [class*='name' i]",
+    "[class*='minicart' i] [class*='item' i] [class*='title' i]",
+    "[class*='cart-item' i] [class*='name' i]",
+    "[class*='cart-item' i] [class*='title' i]",
+    "[class*='checkout' i] [class*='product' i] [class*='name' i]",
+    ".vtex-minicart-2-x-itemNameContainer",
+    ".vtex-checkout-summary-0-x-itemName",
+    ".product-name",
+    ".item-name",
+    "a.product-name",
+    ".cart-items .item-name",
+    "tr.product-item .item-name",
+    "tr.cart-item .item-name",
+    "table.cart-items td a",
+    "#cart-fixed .item .product-name",
+    "#cart-fixed .item-name",
+    ".cart-fixed .item-name",
+    ".cart-fixed .product-name",
+    "#cart-fixed li a",
+    "#minicart-content .item-name",
+    "[data-fs-cart-item-summary-title]",
+    "[data-fs-cart-item-image] + * a",
+    "[class*='cart' i] a[href*='/p']",
+    "[class*='checkout' i] a[href*='/p']"
+  ];
+  const sweepTitles = async () => {
+    const observed2 = [];
+    for (const sel of titleSelectors) {
+      try {
+        const loc = page.locator(sel);
+        const count = await withCap(loc.count(), 1000, 0);
+        const limit = Math.min(count, 10);
+        for (let i = 0;i < limit; i++) {
+          const el = loc.nth(i);
+          const visible = await withCap(el.isVisible({ timeout: 200 }).catch(() => false), 400, false);
+          if (!visible)
+            continue;
+          const text = await withCap(el.innerText().catch(() => ""), 500, "");
+          const clean = text.trim().slice(0, 200);
+          if (clean.length > 2)
+            observed2.push(clean);
+        }
+        if (observed2.length > 0)
+          return observed2;
+      } catch {}
+    }
+    return observed2;
+  };
+  let observed = await sweepTitles();
+  if (observed.length === 0) {
+    dlog2(ctx, "  validateCartContainsTitle: 0 titles on first pass, retrying after 2s");
+    await page.waitForTimeout(2000);
+    observed = await sweepTitles();
+  }
+  dlog2(ctx, `  validateCartContainsTitle: observed ${observed.length} titles ${observed.length ? `[${observed.slice(0, 3).map((t) => t.slice(0, 30)).join(" | ")}${observed.length > 3 ? " | …" : ""}]` : ""}`);
+  if (observed.length === 0) {
+    return { found: false, observedTitles: [], method: "none" };
+  }
+  const found = observed.some((o) => titlesMatch(o, expectedTitle));
+  return { found, observedTitles: observed, method: "selector" };
+}
+async function detectEmptyCartBanner(page) {
+  const bannerSelectors = [
+    ":text-matches('carrinho.*vazio', 'i')",
+    ":text-matches('seu carrinho está vazio', 'i')",
+    ":text-matches('empty cart', 'i')",
+    ":text-matches('cart is empty', 'i')",
+    ":text-matches('nenhum item.*carrinho', 'i')",
+    "[class*='empty' i][class*='cart' i]",
+    "[class*='cart-empty' i]"
+  ];
+  for (const sel of bannerSelectors) {
+    try {
+      const loc = page.locator(sel).first();
+      if (await withCap(loc.isVisible({ timeout: 300 }).catch(() => false), 500, false)) {
+        const text = await withCap(loc.innerText().catch(() => ""), 500, "");
+        if (text.trim())
+          return text.trim().slice(0, 120);
+      }
+    } catch {}
+  }
+  return null;
+}
 async function attemptRecovery(page, _ctx, stepName, intendedAction, alreadyTried) {
   let html = "";
   try {

package/package.json

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