@decocms/parity 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,21 +1,5 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli.ts
@@ -107,7 +91,15 @@ var StepCapture = z.object({
     observedTitles: z.array(z.string()).optional(),
     reason: z.string().optional()
   }).optional(),
-  cartOpenMethod: z.enum(["click", "click-navigate", "hover", "already-open", "failed"]).optional()
+  cartOpenMethod: z.enum(["click", "click-navigate", "hover", "already-open", "failed"]).optional(),
+  cartRevealMode: z.enum([
+    "hover-drawer",
+    "click-drawer",
+    "click-navigate-checkout",
+    "click-navigate-cart",
+    "inline-notification",
+    "unknown"
+  ]).optional()
 });
 var FlowCapture = z.object({
   flow: FlowName,
@@ -302,7 +294,13 @@ var ParityRc = z.object({
     minicartTrigger: z.string().optional(),
     cepInputPdp: z.string().optional(),
     cepInputCart: z.string().optional(),
-    checkoutButton: z.string().optional()
+    checkoutButton: z.string().optional(),
+    sizeSwatch: z.string().optional(),
+    colorSwatch: z.string().optional(),
+    variantRow: z.string().optional(),
+    quantityIncrement: z.string().optional(),
+    quantityInput: z.string().optional(),
+    minicartCount: z.string().optional()
   }).default({}),
   skipSteps: z.array(z.string()).default([])
 });
@@ -874,6 +872,138 @@ function diffSitemap(prodUrls, candUrls) {
 
 // src/engine/browser.ts
 import { chromium, devices } from "playwright";
+
+// src/engine/carousel-stabilizer.ts
+var CAROUSEL_STABILIZER_INIT_SCRIPT = `
+(function () {
+  if (window.__parityCarouselInstalled) return;
+  window.__parityCarouselInstalled = true;
+  window.__parityCarouselStop = false;
+
+  /**
+   * Walks the page for known carousel libraries and pins them to slide 0.
+   * Idempotent — safe to call multiple times. Returns a counters object
+   * so the harness can log how many were stabilized.
+   */
+  window.__parityStabilizeCarousels = function () {
+    var counts = { swiper: 0, splide: 0, slick: 0, keenSlider: 0, generic: 0 };
+
+    // 1. Swiper — most common in Deco sites. Two ways to find instances:
+    //    - element.swiper (newer versions)
+    //    - window.Swiper.instances (older)
+    try {
+      var swiperEls = document.querySelectorAll('.swiper, .swiper-container');
+      swiperEls.forEach(function (el) {
+        var inst = el.swiper;
+        if (inst && typeof inst.slideTo === 'function') {
+          try { inst.autoplay && inst.autoplay.stop && inst.autoplay.stop(); } catch (_) {}
+          try { inst.slideTo(0, 0, false); counts.swiper++; } catch (_) {}
+        }
+      });
+    } catch (_) {}
+
+    // 2. Splide
+    try {
+      var splideEls = document.querySelectorAll('.splide');
+      splideEls.forEach(function (el) {
+        var inst = el.splide || (el.__splide);
+        if (inst && typeof inst.go === 'function') {
+          try { inst.go(0); counts.splide++; } catch (_) {}
+        }
+      });
+    } catch (_) {}
+
+    // 3. Slick
+    try {
+      if (window.jQuery) {
+        var $slick = window.jQuery('.slick-slider, .slick-initialized');
+        if ($slick.length) {
+          try { $slick.slick('slickGoTo', 0, true); counts.slick += $slick.length; } catch (_) {}
+        }
+      }
+    } catch (_) {}
+
+    // 4. KeenSlider
+    try {
+      var keenEls = document.querySelectorAll('.keen-slider');
+      keenEls.forEach(function (el) {
+        var inst = el.__keenSlider || el.keenSlider;
+        if (inst && typeof inst.moveToIdx === 'function') {
+          try { inst.moveToIdx(0, true, { duration: 0 }); counts.keenSlider++; } catch (_) {}
+        }
+      });
+    } catch (_) {}
+
+    // 5. Generic fallback — any element inside a [data-section] matching
+    //    carousel|slider|banner|hero, reset scrollLeft to 0 on any
+    //    scrolled descendant. Catches CSS-only scroll-snap carousels
+    //    and custom Deco implementations.
+    //
+    //    Cubic flagged that the previous version did
+    //    querySelectorAll('*') + getComputedStyle per node — O(N) layout
+    //    flushes on every screenshot. Now we only touch elements with
+    //    non-zero scrollLeft (a DOM-level read, no layout flush) which
+    //    are the only ones we'd mutate anyway. Skips the entire
+    //    getComputedStyle scan.
+    try {
+      var BANNER_RE = /(carousel|slider|banner|hero)/i;
+      var sections = document.querySelectorAll('[data-section]');
+      for (var s = 0; s < sections.length; s++) {
+        var sec = sections[s];
+        var name = sec.getAttribute('data-section') || '';
+        if (!BANNER_RE.test(name)) continue;
+        try { if (sec.scrollLeft > 0) { sec.scrollLeft = 0; counts.generic++; } } catch (_) {}
+        var scrollers = sec.querySelectorAll('*');
+        for (var i = 0; i < scrollers.length; i++) {
+          var el = scrollers[i];
+          if (el && el.scrollLeft > 0) {
+            try { el.scrollLeft = 0; counts.generic++; } catch (_) {}
+          }
+        }
+      }
+    } catch (_) {}
+
+    // 6. Set the freeze flag so future auto-advance ticks bail out (libs
+    //    that check this flag before mutating slide index).
+    window.__parityCarouselStop = true;
+    return counts;
+  };
+})();
+`.trim();
+async function stabilizeCarousels(page) {
+  const empty = {
+    swiper: 0,
+    splide: 0,
+    slick: 0,
+    keenSlider: 0,
+    generic: 0,
+    total: 0
+  };
+  try {
+    const counts = await page.evaluate(() => {
+      const fn = window.__parityStabilizeCarousels;
+      return fn ? fn() : null;
+    });
+    if (!counts)
+      return empty;
+    const total = (counts.swiper ?? 0) + (counts.splide ?? 0) + (counts.slick ?? 0) + (counts.keenSlider ?? 0) + (counts.generic ?? 0);
+    if (total > 0) {
+      await page.waitForTimeout(150);
+    }
+    return {
+      swiper: counts.swiper ?? 0,
+      splide: counts.splide ?? 0,
+      slick: counts.slick ?? 0,
+      keenSlider: counts.keenSlider ?? 0,
+      generic: counts.generic ?? 0,
+      total
+    };
+  } catch {
+    return empty;
+  }
+}
+
+// src/engine/browser.ts
 var DISABLE_ANIMATIONS_CSS = `
   *, *::before, *::after {
     animation-duration: 0s !important;
@@ -883,17 +1013,33 @@ var DISABLE_ANIMATIONS_CSS = `
     scroll-behavior: auto !important;
   }
 `;
+var USER_AGENT_BY_VIEWPORT = {
+  mobile: "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Mobile Safari/537.36",
+  tablet: "Mozilla/5.0 (iPad; CPU OS 16_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
+  desktop: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
+};
+function userAgentFor(viewport) {
+  return USER_AGENT_BY_VIEWPORT[viewport];
+}
 var VIEWPORT_PRESETS = {
   mobile: {
-    ...devices["Pixel 7"]
+    ...devices["Pixel 7"],
+    userAgent: USER_AGENT_BY_VIEWPORT.mobile,
+    isMobile: true,
+    hasTouch: true
   },
   tablet: {
-    ...devices["iPad Mini"]
+    ...devices["iPad Mini"],
+    userAgent: USER_AGENT_BY_VIEWPORT.tablet,
+    isMobile: true,
+    hasTouch: true
   },
   desktop: {
     viewport: { width: 1440, height: 900 },
     deviceScaleFactor: 1,
-    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
+    userAgent: USER_AGENT_BY_VIEWPORT.desktop,
+    isMobile: false,
+    hasTouch: false
   }
 };
 async function launchBrowser(opts = {}) {
@@ -909,7 +1055,8 @@ async function newContext(browser, opts) {
     ...baseContext,
     recordHar: opts.harPath ? { path: opts.harPath, mode: "minimal" } : undefined,
     bypassCSP: true,
-    ignoreHTTPSErrors: true
+    ignoreHTTPSErrors: true,
+    extraHTTPHeaders: opts.noCache ? { "Cache-Control": "no-cache", Pragma: "no-cache" } : undefined
   });
   await ctx.addInitScript({
     content: `
@@ -920,6 +1067,7 @@ async function newContext(browser, opts) {
       } catch (e) {}
     `
   });
+  await ctx.addInitScript({ content: CAROUSEL_STABILIZER_INIT_SCRIPT });
   if (opts.cohortCookieValue) {
     await ctx.addCookies([
       {
@@ -1209,6 +1357,12 @@ async function capturePage(page, opts) {
       new Promise((resolve) => setTimeout(() => resolve(null), Math.min(5000, remaining())))
     ]) ?? null;
     if (!opts.skipScreenshot) {
+      await Promise.race([
+        stabilizeCarousels(page).catch(() => {
+          return;
+        }),
+        new Promise((resolve) => setTimeout(resolve, Math.min(3000, remaining())))
+      ]);
       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(() => {
@@ -4469,6 +4623,23 @@ async function callAnthropicTool(params) {
   return null;
 }
 async function callOpenRouterTool(params) {
+  const baseTokens = params.maxTokens ?? 2000;
+  const totalBudget = params.timeoutMs ?? defaultTimeout(params);
+  const start = Date.now();
+  for (let attempt = 1;attempt <= 2; attempt++) {
+    const isRetry = attempt > 1;
+    const remaining = totalBudget - (Date.now() - start);
+    if (remaining <= 2000 && isRetry) {
+      return null;
+    }
+    const tokens = isRetry ? Math.max(baseTokens * 2, 4000) : baseTokens;
+    const result = await openRouterToolOnce(params, tokens, isRetry, Math.max(remaining, 2000));
+    if (result !== undefined)
+      return result;
+  }
+  return null;
+}
+async function openRouterToolOnce(params, maxTokens, isRetry, attemptTimeoutMs) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey)
     return null;
@@ -4481,8 +4652,7 @@ async function callOpenRouterTool(params) {
       }
     });
   }
-  const timeoutMs = params.timeoutMs ?? defaultTimeout(params);
-  const { signal, clear } = makeTimeoutSignal(timeoutMs);
+  const { signal, clear } = makeTimeoutSignal(attemptTimeoutMs);
   try {
     const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
       method: "POST",
@@ -4495,7 +4665,7 @@ async function callOpenRouterTool(params) {
       },
       body: JSON.stringify({
         model: LLM_MODEL_OPENROUTER,
-        max_tokens: params.maxTokens ?? 2000,
+        max_tokens: maxTokens,
         messages: [
           { role: "system", content: params.systemPrompt },
           { role: "user", content: userContent }
@@ -4516,6 +4686,8 @@ async function callOpenRouterTool(params) {
     if (!response.ok) {
       const txt = await response.text().catch(() => "");
       console.error(`[llm-openrouter] HTTP ${response.status}: ${txt.slice(0, 200)}`);
+      if (response.status >= 500 || response.status === 429)
+        return;
       return null;
     }
     const json = await response.json();
@@ -4531,8 +4703,12 @@ async function callOpenRouterTool(params) {
             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;
+        if (isRetry) {
+          console.error(`[llm-openrouter] failed to parse tool arguments after retry (raw len=${raw.length}, head=${JSON.stringify(raw.slice(0, 80))})`);
+          return null;
+        }
+        console.error(`[llm-openrouter] parse error, retrying with more tokens (raw len=${raw.length}, head=${JSON.stringify(raw.slice(0, 80))})`);
+        return;
       }
     }
     const content = json.choices?.[0]?.message?.content;
@@ -4541,12 +4717,17 @@ async function callOpenRouterTool(params) {
         return JSON.parse(content);
       } catch {}
     }
+    return null;
   } catch (err) {
-    console.error(`[llm-openrouter] failed: ${err.message}`);
+    const msg = err.message;
+    console.error(`[llm-openrouter] failed: ${msg}`);
+    if (!isRetry && (msg.includes("ECONN") || msg.includes("aborted") || msg.includes("fetch"))) {
+      return;
+    }
+    return null;
   } finally {
     clear();
   }
-  return null;
 }
 function tryRepairJson(raw) {
   let s = raw.trim();
@@ -4962,7 +5143,13 @@ var SelectorKey = z2.enum([
   "minicartTrigger",
   "cepInputPdp",
   "cepInputCart",
-  "checkoutButton"
+  "checkoutButton",
+  "sizeSwatch",
+  "colorSwatch",
+  "variantRow",
+  "quantityIncrement",
+  "quantityInput",
+  "minicartCount"
 ]);
 var SelectorEntry = z2.object({
   selector: z2.string(),
@@ -5156,8 +5343,80 @@ var DEFAULT_SELECTORS = {
     "button:has-text('Finalizar compra')",
     "a:has-text('Ir para o checkout')",
     "button:has-text('Ir para o checkout')",
+    "[role='dialog'] a:has-text('Finalizar')",
+    "[role='dialog'] button:has-text('Finalizar')",
+    "[data-minicart] a:has-text('Finalizar')",
+    "[data-minicart] button:has-text('Finalizar')",
+    "[data-cart-drawer] a:has-text('Finalizar')",
+    "[data-cart-drawer] button:has-text('Finalizar')",
     "a:has-text('Checkout')",
-    "[data-checkout-button]"
+    "[data-checkout-button]",
+    "a:text-is('Finalizar')",
+    "button:text-is('Finalizar')"
+  ],
+  sizeSwatch: [
+    "[data-size]:not([disabled]):not([aria-disabled='true']):not(.unavailable):not(.sold-out)",
+    "[data-variant-size]:not([disabled]):not([aria-disabled='true']):not(.unavailable)",
+    "button[aria-label*='tamanho' i]:not([aria-disabled='true']):not([disabled])",
+    "button[aria-label*='size' i]:not([aria-disabled='true']):not([disabled])",
+    "[data-testid='size-selector'] button:not([disabled]):not(.unavailable)",
+    ".size-selector button:not([disabled]):not(.unavailable):not(.sold-out)",
+    "[class*='size'] button:not([disabled]):not(.unavailable)",
+    "label:has(input[name*='size' i]:not([disabled])) "
+  ],
+  colorSwatch: [
+    "[data-color]:not([disabled]):not([aria-disabled='true']):not(.unavailable):not(.sold-out)",
+    "[data-variant-color]:not([disabled]):not([aria-disabled='true']):not(.unavailable)",
+    "button[aria-label*='cor' i]:not([aria-disabled='true']):not([disabled])",
+    "button[aria-label*='color' i]:not([aria-disabled='true']):not([disabled])",
+    "[data-testid='color-selector'] button:not([disabled]):not(.unavailable)",
+    ".color-swatch:not(.unavailable):not(.sold-out)",
+    "[class*='color'] button:not([disabled]):not(.unavailable)"
+  ],
+  variantRow: [
+    "[data-sku-row]",
+    "[data-variant-row]",
+    "tr[data-variant]",
+    "tr:has([aria-label*='quantidade' i])",
+    "tbody tr:has(input[type='number'])"
+  ],
+  quantityIncrement: [
+    "[data-qty-plus]",
+    "[data-quantity-plus]",
+    "button[aria-label*='aumentar' i]",
+    "button[aria-label*='increase' i]",
+    "button[aria-label*='increment' i]",
+    "button:has-text('+')",
+    "[class*='qty'] button:has-text('+')"
+  ],
+  quantityInput: [
+    "input[type='number'][min='0'][value='0']",
+    "input[id*='quantity-input' i]",
+    "input[name*='qty' i]",
+    "input[name*='quantity' i]",
+    "input[name*='quantidade' i]",
+    "input[aria-label*='quantidade' i]",
+    "[data-qty-input]",
+    "input[type='number'][min='0']",
+    "input[type='number'][min='1']"
+  ],
+  minicartCount: [
+    "[data-minicart-count]",
+    "[data-cart-count]",
+    ".cart-count",
+    ".minicart__count",
+    "[class*='cart-count']",
+    "[class*='CartCount']",
+    "[aria-label*='itens' i][role='status']",
+    "header [data-minicart-trigger] [class*='badge']",
+    "header [aria-label*='cart' i] [class*='count']",
+    "header [aria-label*='sacola' i] [class*='badge']",
+    "header [aria-label*='sacola' i] [class*='count']",
+    "header a[href*='/cart'] [class*='count']",
+    "header a[href*='/checkout'] [class*='count']",
+    "[data-fs-cart-icon] + [class*='count']",
+    "[class*='Minicart'] [class*='count']",
+    "[class*='minicart'] [class*='count']"
   ]
 };
 function selectorsFor(key, ctxOrRc = {}) {
@@ -5182,7 +5441,18 @@ function isResolutionContext(v) {
 }
 
 // src/engine/flows.ts
-var PURCHASE_JOURNEY_TOTAL_STEPS = 8;
+async function screenshotStable(page, opts) {
+  await Promise.race([
+    stabilizeCarousels(page).catch(() => {
+      return;
+    }),
+    new Promise((resolve) => setTimeout(resolve, 3000))
+  ]);
+  await page.screenshot({ path: opts.path, fullPage: opts.fullPage ?? false }).catch(() => {
+    return;
+  });
+}
+var PURCHASE_JOURNEY_TOTAL_STEPS = 9;
 var DEBUG_PARITY2 = process.env.DEBUG_PARITY === "1" || process.env.DEBUG_PARITY === "true";
 var DEBUG_START2 = Date.now();
 function dlog2(ctx, msg) {
@@ -5192,6 +5462,41 @@ function dlog2(ctx, msg) {
   process.stderr.write(`[+${elapsed}s ${ctx.viewport}/${ctx.side}] ${msg}
 `);
 }
+function withCap(p, capMs, fallback) {
+  return Promise.race([
+    p.catch(() => fallback),
+    new Promise((resolve) => setTimeout(() => resolve(fallback), capMs))
+  ]);
+}
+var VARIANT_REQUIRED_TEXT_PATTERNS = [
+  /selecione um produto/i,
+  /selecione um tamanho/i,
+  /selecione uma cor/i,
+  /selecione uma op[cç][aã]o/i,
+  /select a size/i,
+  /select a color/i,
+  /select an option/i,
+  /choose an option/i,
+  /please select/i,
+  /select size/i,
+  /select color/i
+];
+var ADD_TO_CART_ERROR_PATTERNS = [
+  ...VARIANT_REQUIRED_TEXT_PATTERNS,
+  /estoque esgotado/i,
+  /out of stock/i,
+  /indispon[ií]vel/i,
+  /unavailable/i
+];
+var ADD_TO_CART_SUCCESS_PATTERNS = [
+  /produto adicionado/i,
+  /adicionado ao carrinho/i,
+  /adicionado [aà]\s+sacola/i,
+  /added to cart/i,
+  /added to bag/i,
+  /item added/i,
+  /successfully added/i
+];
 function selFor(ctx, key) {
   return selectorsFor(key, { rc: ctx.rc, learned: ctx.learned, platform: ctx.platform });
 }
@@ -5199,7 +5504,7 @@ var FLOW_DEADLINE_MS = {
   homepage: 90000,
   plp: 180000,
   pdp: 240000,
-  "purchase-journey": 360000
+  "purchase-journey": 420000
 };
 async function runFlow(flow, ctx) {
   const start = Date.now();
@@ -5236,7 +5541,7 @@ async function runFlow(flow, ctx) {
           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.`
+          actionDescription: `[flow-timeout] flow "${flow}" excedeu ${deadlineMs}ms — captura abortada pela safety net externa, ${pages.length} page(s) fechada(s) para liberar o contexto.`
         }
       ], start));
       const CLOSE_CAP_MS = 5000;
@@ -5244,7 +5549,7 @@ async function runFlow(flow, ctx) {
         p.close().catch(() => {
           return;
         }),
-        new Promise((resolve2) => setTimeout(resolve2, CLOSE_CAP_MS))
+        new Promise((resolveClose) => setTimeout(resolveClose, CLOSE_CAP_MS))
       ]);
       cleanup = Promise.allSettled(pages.map(cappedClose));
     }, deadlineMs);
@@ -5352,7 +5657,7 @@ async function flowPurchaseJourney(ctx) {
   const pages = [];
   const steps = [];
   const page = await ctx.ctx.newPage();
-  let recoveryBudget = ctx.recoveryBudget ?? 3;
+  const budget = { remaining: ctx.recoveryBudget ?? 5 };
   const total = PURCHASE_JOURNEY_TOTAL_STEPS;
   const reportStart = (idx, name) => {
     ctx.onStep?.({ phase: "start", name, index: idx, total });
@@ -5362,15 +5667,12 @@ 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"),
-      scrollToLoad: false
+      screenshotPath: screenshotPath(ctx, "pj-1-home")
     });
-    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({
@@ -5389,24 +5691,19 @@ 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"),
-      scrollToLoad: false
+      screenshotPath: screenshotPath(ctx, "pj-2-plp")
     });
-    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({
@@ -5425,9 +5722,35 @@ async function flowPurchaseJourney(ctx) {
     steps[steps.length - 1].actionDescription = `Navegou pra categoria \`${plpHit.url}\` (via \`${plpHit.selector}\`)`;
     steps[steps.length - 1].beforeUrl = ctx.baseUrl;
     reportStart(3, "enter-pdp");
-    const pdpHit = await findProductUrl(page, ctx);
+    let pdpHit = await findProductUrl(page, ctx);
+    let pdpRecoveredByLlm = false;
+    if (!pdpHit && budget.remaining > 0) {
+      const html = await page.content().catch(() => "");
+      if (html) {
+        const suggestion = await suggestRecovery({
+          stepName: "enter-pdp",
+          intendedAction: "Encontrar um link <a> que leve para a página de detalhes (PDP) de algum produto listado na PLP atual",
+          html,
+          alreadyTried: selFor(ctx, "productCard")
+        });
+        if (suggestion) {
+          budget.remaining--;
+          try {
+            const el = page.locator(suggestion.selector).first();
+            if (await el.isVisible({ timeout: 2000 }).catch(() => false)) {
+              const href = await el.getAttribute("href");
+              if (href) {
+                const abs = new URL(href, page.url()).toString();
+                pdpHit = { url: abs, selector: suggestion.selector };
+                pdpRecoveredByLlm = true;
+              }
+            }
+          } catch {}
+        }
+      }
+    }
     if (!pdpHit) {
-      steps.push(makeSkipStep(3, "enter-pdp", ctx, "no product card found"));
+      steps.push(makeSkipStep(3, "enter-pdp", ctx, "no product card found (recovery exhausted)"));
       reportEnd(3, "enter-pdp", "skipped", 0, "no product card found");
       return { pages, steps };
     }
@@ -5436,8 +5759,7 @@ async function flowPurchaseJourney(ctx) {
       url: pdpHit.url,
       side: ctx.side,
       viewport: ctx.viewport,
-      screenshotPath: screenshotPath(ctx, "pj-3-pdp"),
-      scrollToLoad: false
+      screenshotPath: screenshotPath(ctx, "pj-3-pdp")
     });
     pages.push(pdpCap);
     const step3Status = pdpCap.status >= 200 && pdpCap.status < 400 ? "ok" : "failed";
@@ -5451,10 +5773,11 @@ async function flowPurchaseJourney(ctx) {
       url: pdpCap.finalUrl,
       screenshotPath: pdpCap.screenshotPath,
       selectorKey: "productCard",
-      usedSelector: pdpHit.selector
+      usedSelector: pdpHit.selector,
+      recoveredByLlm: pdpRecoveredByLlm || undefined
     });
     reportEnd(3, "enter-pdp", step3Status, Date.now() - t3);
-    steps[steps.length - 1].actionDescription = `Abriu PDP \`${pdpHit.url}\` (via \`${pdpHit.selector}\`)`;
+    steps[steps.length - 1].actionDescription = `Abriu PDP \`${pdpHit.url}\` (via \`${pdpHit.selector}\`${pdpRecoveredByLlm ? " — recovery LLM" : ""})`;
     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"}`);
@@ -5464,402 +5787,445 @@ async function flowPurchaseJourney(ctx) {
         productTitle: expectedProductTitle
       };
     }
-    reportStart(4, "shipping-calc-pdp");
+    reportStart(4, "select-variant");
+    const t4 = Date.now();
+    const beforeUrl4 = page.url();
+    const spBefore4 = screenshotPath(ctx, "pj-4-select-variant-before");
+    await screenshotStable(page, { path: spBefore4, fullPage: false });
+    const variantResult = await selectVariant(page, ctx);
+    let variantLlmAction = null;
+    if (variantResult.actions.length === 0 && variantResult.variantRequired && budget.remaining > 0) {
+      variantLlmAction = await attemptStepAction({
+        page,
+        ctx,
+        stepName: "select-variant",
+        intendedAction: "Selecionar uma variante disponível (tamanho, cor, sabor) ou clicar no botão '+' para incrementar a quantidade da primeira variante listada na PDP. Não clique no botão de comprar.",
+        selectorKey: "quantityIncrement",
+        action: "click",
+        recoveryBudget: budget
+      });
+    }
+    const sp4 = screenshotPath(ctx, "pj-4-select-variant");
+    await screenshotStable(page, { path: sp4, fullPage: false });
+    if (variantResult.actions.length > 0 || variantLlmAction?.performed) {
+      const llmDesc = variantLlmAction?.performed ? `Recovery LLM: ${variantLlmAction.action} em \`${variantLlmAction.selector}\`` : null;
+      const desc = variantResult.actions.length > 0 ? variantResult.actions.join("; ") : llmDesc ?? "(variante selecionada)";
+      steps.push({
+        step: 4,
+        name: "select-variant",
+        side: ctx.side,
+        viewport: ctx.viewport,
+        status: "ok",
+        durationMs: Date.now() - t4,
+        url: page.url(),
+        screenshotPath: sp4,
+        screenshotBeforePath: spBefore4,
+        beforeUrl: beforeUrl4,
+        actionDescription: llmDesc && variantResult.actions.length > 0 ? `${desc}; ${llmDesc}` : desc,
+        selectorKey: variantLlmAction?.performed ? "quantityIncrement" : variantResult.primarySelectorKey,
+        usedSelector: variantLlmAction?.performed ? variantLlmAction.selector : variantResult.primarySelector,
+        recoveredByLlm: variantLlmAction?.recoveredByLlm || undefined,
+        detail: { actions: variantResult.actions, llmRecovery: !!variantLlmAction?.performed }
+      });
+      reportEnd(4, "select-variant", "ok", Date.now() - t4);
+    } else {
+      const skipNote = variantResult.variantRequired ? "variant required by store but no selectors matched (LLM recovery also failed)" : "no variant selectors found on PDP (assuming single-SKU product)";
+      steps.push(makeSkipStep(4, "select-variant", ctx, skipNote));
+      reportEnd(4, "select-variant", "skipped", 0, skipNote);
+    }
+    reportStart(5, "shipping-calc-pdp");
     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--;
+    let cepPdpRecoveredByLlm = false;
+    if (!cepInputPdp && budget.remaining > 0) {
+      const html = await page.content().catch(() => "");
+      if (html) {
+        const suggestion = await suggestRecovery({
+          stepName: "shipping-calc-pdp",
+          intendedAction: "Encontre o <input> de CEP (código postal de ENDEREÇO de entrega) na PDP, usado pra CALCULAR FRETE — placeholder normalmente é 'CEP', 'Digite seu CEP', 'Cód. postal', 'Postal code', aria-label='CEP' ou name='zip'/'cep'/'postal'. **NÃO** retorne o input de CUPOM de desconto / código promocional / 'Digite o cupom' / 'Insira código' — esses são pra desconto, não pra frete.",
+          html,
+          alreadyTried: selFor(ctx, "cepInputPdp")
+        });
+        if (suggestion) {
+          budget.remaining--;
+          const el = page.locator(suggestion.selector).first();
+          if (await el.isVisible({ timeout: 2000 }).catch(() => false)) {
+            cepInputPdp = suggestion.selector;
+            cepPdpRecoveredByLlm = true;
+          }
+        }
       }
     }
     if (cepInputPdp) {
-      const t4 = Date.now();
-      const beforeUrl4 = page.url();
-      const spBefore4 = screenshotPath(ctx, "pj-4-shipping-pdp-before");
-      await page.screenshot({ path: spBefore4, fullPage: false }).catch(() => {
-        return;
-      });
+      const t5 = Date.now();
+      const beforeUrl5 = page.url();
+      const spBefore5 = screenshotPath(ctx, "pj-5-shipping-pdp-before");
+      await screenshotStable(page, { path: spBefore5, fullPage: false });
       const ok = await fillCep(page, cepInputPdp, ctx.rc.cep);
-      const sp = screenshotPath(ctx, "pj-4-shipping-pdp");
-      await page.screenshot({ path: sp, fullPage: false }).catch(() => {
-        return;
-      });
-      const step4Status = ok ? "ok" : "failed";
+      const sp = screenshotPath(ctx, "pj-5-shipping-pdp");
+      await screenshotStable(page, { path: sp, fullPage: false });
+      const step5Status = ok ? "ok" : "failed";
       steps.push({
-        step: 4,
+        step: 5,
         name: "shipping-calc-pdp",
         side: ctx.side,
         viewport: ctx.viewport,
-        status: step4Status,
-        durationMs: Date.now() - t4,
+        status: step5Status,
+        durationMs: Date.now() - t5,
         url: page.url(),
         screenshotPath: sp,
-        screenshotBeforePath: spBefore4,
-        beforeUrl: beforeUrl4,
-        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no input \`${cepInputPdp}\` e disparou cálculo de frete${cepPdpRecovered ? " (selector via LLM recovery)" : ""}`,
+        screenshotBeforePath: spBefore5,
+        beforeUrl: beforeUrl5,
+        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no input \`${cepInputPdp}\`${cepPdpRecoveredByLlm ? " (via recovery LLM)" : ""}`,
         detail: { cepUsed: ctx.rc.cep },
         selectorKey: "cepInputPdp",
         usedSelector: cepInputPdp,
-        recoveredByLlm: cepPdpRecovered || undefined
+        recoveredByLlm: cepPdpRecoveredByLlm || undefined
       });
-      reportEnd(4, "shipping-calc-pdp", step4Status, Date.now() - t4);
+      reportEnd(5, "shipping-calc-pdp", step5Status, Date.now() - t5);
     } else {
-      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");
+      steps.push(makeSkipStep(5, "shipping-calc-pdp", ctx, "no CEP input on PDP (recovery exhausted)"));
+      reportEnd(5, "shipping-calc-pdp", "skipped", 0, "no CEP input on PDP");
     }
-    reportStart(5, "add-to-cart");
+    reportStart(6, "add-to-cart");
     let buyHit = await firstVisibleLocator(page, selFor(ctx, "buyButton"));
     let buyRecovered = false;
-    if (!buyHit && recoveryBudget > 0) {
+    if (!buyHit && budget.remaining > 0) {
       const recovery = await attemptRecovery(page, ctx, "add-to-cart", "Clicar no botão de comprar/adicionar ao carrinho", selFor(ctx, "buyButton"));
       if (recovery) {
         buyHit = recovery;
         buyRecovered = true;
-        recoveryBudget--;
+        budget.remaining--;
       }
     }
     if (!buyHit) {
-      steps.push(makeSkipStep(5, "add-to-cart", ctx, "no buy button found (recovery exhausted)"));
-      reportEnd(5, "add-to-cart", "skipped", 0, "no buy button found");
+      steps.push(makeSkipStep(6, "add-to-cart", ctx, "no buy button found (recovery exhausted)"));
+      reportEnd(6, "add-to-cart", "skipped", 0, "no buy button found");
       return { pages, steps };
     }
-    const t5 = Date.now();
-    const beforeUrl5 = page.url();
-    const spBefore5 = screenshotPath(ctx, "pj-5-add-cart-before");
-    await page.screenshot({ path: spBefore5, fullPage: false }).catch(() => {
-      return;
-    });
+    const t6 = Date.now();
+    const beforeUrl6 = page.url();
+    const spBefore6 = screenshotPath(ctx, "pj-6-add-cart-before");
+    await screenshotStable(page, { path: spBefore6, fullPage: false });
+    const cartCountBefore = await readCartCount(page, ctx);
     const buyText = await buyHit.locator.innerText().catch(() => "");
     await buyHit.locator.click({ timeout: 5000 }).catch(() => {
       return;
     });
-    await page.waitForTimeout(2000);
-    const sp5 = screenshotPath(ctx, "pj-5-add-cart");
-    await page.screenshot({ path: sp5, fullPage: false }).catch(() => {
-      return;
-    });
+    let validation = await validateAddToCart(page, ctx, cartCountBefore, beforeUrl6);
+    let variantRetryNote;
+    if (validation.status === "failed" && validation.errorText && VARIANT_REQUIRED_TEXT_PATTERNS.some((re) => re.test(validation.errorText))) {
+      const retryHit = await findAndIncrementZeroQtyInput(page, ctx);
+      if (retryHit) {
+        variantRetryNote = `Retry: ${retryHit.description}`;
+      } else if (budget.remaining > 0) {
+        const llmRetry = await attemptStepAction({
+          page,
+          ctx,
+          stepName: "add-to-cart-retry-variant",
+          intendedAction: "A loja rejeitou o add-to-cart com a mensagem 'Selecione um produto/tamanho/cor'. Encontre o picker de variante visível e selecione UMA opção (clicar num swatch, em '+' ao lado de uma quantidade '0', em um botão de tamanho). Não clique no botão de comprar.",
+          selectorKey: "quantityIncrement",
+          action: "click",
+          recoveryBudget: budget
+        });
+        if (llmRetry.performed) {
+          variantRetryNote = `Retry via LLM: ${llmRetry.action} em \`${llmRetry.selector}\``;
+        }
+      }
+      if (variantRetryNote) {
+        await page.waitForTimeout(500);
+        await buyHit.locator.click({ timeout: 5000 }).catch(() => {
+          return;
+        });
+        validation = await validateAddToCart(page, ctx, cartCountBefore, beforeUrl6);
+      }
+    }
+    const sp6 = screenshotPath(ctx, "pj-6-add-cart");
+    await screenshotStable(page, { path: sp6, fullPage: false });
+    const buyActionDesc = `Clicou no botão${buyText ? ` '${buyText.slice(0, 40).trim()}'` : ""} (\`${buyHit.selector}\`)${buyRecovered ? " — selector veio de recovery LLM" : ""}`;
+    const fullActionDesc = variantRetryNote ? `${buyActionDesc} — ${variantRetryNote} — ${validation.note}` : `${buyActionDesc} — ${validation.note}`;
     steps.push({
-      step: 5,
+      step: 6,
       name: "add-to-cart",
       side: ctx.side,
       viewport: ctx.viewport,
-      status: "ok",
-      durationMs: Date.now() - t5,
+      status: validation.status,
+      durationMs: Date.now() - t6,
       url: page.url(),
-      screenshotPath: sp5,
-      screenshotBeforePath: spBefore5,
-      beforeUrl: beforeUrl5,
-      actionDescription: `Clicou no botão${buyText ? ` '${buyText.slice(0, 40).trim()}'` : ""} (\`${buyHit.selector}\`)${buyRecovered ? " — selector veio de recovery LLM" : ""}`,
+      screenshotPath: sp6,
+      screenshotBeforePath: spBefore6,
+      beforeUrl: beforeUrl6,
+      actionDescription: fullActionDesc,
       selectorKey: "buyButton",
       usedSelector: buyHit.selector,
-      recoveredByLlm: buyRecovered || undefined
-    });
-    reportEnd(5, "add-to-cart", "ok", Date.now() - t5);
-    reportStart(6, "open-minicart");
-    const t6 = Date.now();
-    const beforeUrl6 = page.url();
-    const spBefore6 = screenshotPath(ctx, "pj-6-minicart-before");
-    await page.screenshot({ path: spBefore6, fullPage: false }).catch(() => {
-      return;
+      recoveredByLlm: buyRecovered || undefined,
+      note: validation.status === "ok" ? undefined : validation.note,
+      detail: { signal: validation.signal, errorText: validation.errorText, variantRetry: variantRetryNote }
     });
+    reportEnd(6, "add-to-cart", validation.status, Date.now() - t6, validation.status === "ok" ? undefined : validation.note);
+    if (validation.status === "failed") {
+      return { pages, steps };
+    }
+    reportStart(7, "open-minicart");
+    const t7 = Date.now();
+    const beforeUrl7 = page.url();
+    const spBefore7 = screenshotPath(ctx, "pj-7-minicart-before");
+    await screenshotStable(page, { path: spBefore7, fullPage: false });
     let miniHit = await firstVisibleLocator(page, selFor(ctx, "minicartTrigger"));
     let miniRecovered = false;
-    if (!miniHit && recoveryBudget > 0) {
+    if (!miniHit && budget.remaining > 0) {
       const recovery = await attemptRecovery(page, ctx, "open-minicart", "Abrir o minicart/drawer do carrinho", selFor(ctx, "minicartTrigger"));
       if (recovery) {
         miniHit = recovery;
         miniRecovered = true;
-        recoveryBudget--;
+        budget.remaining--;
       }
     }
     let cartOpenMethod = "failed";
     let miniText = "";
+    let cartRevealMode = "unknown";
+    const drawerAlreadyOpen = await isCartRevealed(page, expectedProductTitle) !== 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);
       cartOpenMethod = openResult.method;
     } else {
-      const alreadyOpen = await isCartRevealed(page, expectedProductTitle);
-      if (alreadyOpen) {
+      if (drawerAlreadyOpen) {
         cartOpenMethod = "already-open";
-        dlog2(ctx, `step 6 open-minicart: no trigger, but drawer already visible (matched ${alreadyOpen})`);
+        cartRevealMode = "inline-notification";
+        dlog2(ctx, "step 7 open-minicart: no trigger, drawer already visible");
       }
     }
-    let step6Validation;
+    let step7Validation;
     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)";
+          reasonText = emptyBanner ? `cart genuinely empty — add-to-cart didn't persist. Banner: "${emptyBanner}"` : "no cart line items visible (selectors may not match markup)";
         } else {
           reasonText = `expected title not found among ${v.observedTitles.length} observed`;
         }
       }
-      step6Validation = {
+      step7Validation = {
         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";
+      dlog2(ctx, `step 7 open-minicart: validation → found=${v.found} (${v.method})${reasonText ? ` — ${reasonText.slice(0, 80)}` : ""}`);
+    }
+    const sp7 = screenshotPath(ctx, "pj-7-minicart");
+    await screenshotStable(page, { path: sp7, fullPage: false });
+    const cartEmptyReason = step7Validation?.reason ?? "";
+    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;
     steps.push({
-      step: 6,
+      step: 7,
       name: "open-minicart",
       side: ctx.side,
       viewport: ctx.viewport,
-      status: step6Status,
-      durationMs: Date.now() - t6,
+      status: step7Status,
+      durationMs: Date.now() - t7,
       url: page.url(),
-      screenshotPath: sp6,
-      screenshotBeforePath: spBefore6,
-      beforeUrl: beforeUrl6,
+      screenshotPath: sp7,
+      screenshotBeforePath: spBefore7,
+      beforeUrl: beforeUrl7,
       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",
+      cartRevealMode,
+      cartValidation: step7Validation,
+      note: step7QuirkNote,
+      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(6, "open-minicart", step6Status, Date.now() - t6);
-    reportStart(7, "shipping-calc-cart");
+    reportEnd(7, "open-minicart", step7Status, Date.now() - t7, step7QuirkNote);
+    if (isProdCartEmptyQuirk) {
+      const quirkNote = "cart-empty-prod-quirk: skipped (depende do cart que prod não persistiu)";
+      reportStart(8, "shipping-calc-cart");
+      steps.push(makeSkipStep(8, "shipping-calc-cart", ctx, quirkNote));
+      reportEnd(8, "shipping-calc-cart", "skipped", 0, quirkNote);
+      reportStart(9, "go-checkout");
+      steps.push(makeSkipStep(9, "go-checkout", ctx, quirkNote));
+      reportEnd(9, "go-checkout", "skipped", 0, quirkNote);
+      return { pages, steps };
+    }
+    reportStart(8, "shipping-calc-cart");
     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--;
+    let cepCartRecoveredByLlm = false;
+    if (!cepInputCart && budget.remaining > 0) {
+      const html = await page.content().catch(() => "");
+      if (html) {
+        const suggestion = await suggestRecovery({
+          stepName: "shipping-calc-cart",
+          intendedAction: "Encontre o <input> de CEP (código postal de ENDEREÇO de entrega) dentro do minicart drawer ou da página de carrinho — usado pra CALCULAR FRETE antes do checkout. Placeholder normalmente é 'CEP', 'Digite seu CEP', 'Cód. postal', 'Postal code', aria-label='CEP' ou name='zip'/'cep'/'postal'. **NÃO** retorne o input de CUPOM de desconto / 'Digite o cupom' / código promocional — esses são pra desconto, não pra frete. Também NÃO retorne campo de e-mail/newsletter.",
+          html,
+          alreadyTried: selFor(ctx, "cepInputCart")
+        });
+        if (suggestion) {
+          budget.remaining--;
+          const el = page.locator(suggestion.selector).first();
+          if (await el.isVisible({ timeout: 2000 }).catch(() => false)) {
+            cepInputCart = suggestion.selector;
+            cepCartRecoveredByLlm = true;
+          }
+        }
       }
     }
     if (cepInputCart) {
-      const t7 = Date.now();
-      const beforeUrl7 = page.url();
-      const spBefore7 = screenshotPath(ctx, "pj-7-shipping-cart-before");
-      await page.screenshot({ path: spBefore7, fullPage: false }).catch(() => {
-        return;
-      });
+      const t8 = Date.now();
+      const beforeUrl8 = page.url();
+      const spBefore8 = screenshotPath(ctx, "pj-8-shipping-cart-before");
+      await screenshotStable(page, { path: spBefore8, fullPage: false });
       const ok = await fillCep(page, cepInputCart, ctx.rc.cep);
-      const sp7 = screenshotPath(ctx, "pj-7-shipping-cart");
-      await page.screenshot({ path: sp7, fullPage: false }).catch(() => {
-        return;
-      });
-      const step7Status = ok ? "ok" : "failed";
+      const sp8 = screenshotPath(ctx, "pj-8-shipping-cart");
+      await screenshotStable(page, { path: sp8, fullPage: false });
+      const step8Status = ok ? "ok" : "failed";
       steps.push({
-        step: 7,
+        step: 8,
         name: "shipping-calc-cart",
         side: ctx.side,
         viewport: ctx.viewport,
-        status: step7Status,
-        durationMs: Date.now() - t7,
+        status: step8Status,
+        durationMs: Date.now() - t8,
         url: page.url(),
-        screenshotPath: sp7,
-        screenshotBeforePath: spBefore7,
-        beforeUrl: beforeUrl7,
-        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no carrinho (\`${cepInputCart}\`)${cepCartRecovered ? " (selector via LLM recovery)" : ""}`,
+        screenshotPath: sp8,
+        screenshotBeforePath: spBefore8,
+        beforeUrl: beforeUrl8,
+        actionDescription: `Preencheu CEP '${ctx.rc.cep}' no carrinho (\`${cepInputCart}\`)${cepCartRecoveredByLlm ? " — recovery LLM" : ""}`,
         detail: { cepUsed: ctx.rc.cep },
         selectorKey: "cepInputCart",
         usedSelector: cepInputCart,
-        recoveredByLlm: cepCartRecovered || undefined
+        recoveredByLlm: cepCartRecoveredByLlm || undefined
       });
-      reportEnd(7, "shipping-calc-cart", step7Status, Date.now() - t7);
+      reportEnd(8, "shipping-calc-cart", step8Status, Date.now() - t8);
     } else {
-      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");
-    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})`);
+      steps.push(makeSkipStep(8, "shipping-calc-cart", ctx, "no CEP input in cart (recovery exhausted)"));
+      reportEnd(8, "shipping-calc-cart", "skipped", 0, "no CEP input in cart");
+    }
+    reportStart(9, "go-checkout");
+    const t9 = Date.now();
+    const beforeUrl9 = page.url();
+    if (/\/(checkout|carrinho)(\/|$|\?)/i.test(beforeUrl9)) {
+      await waitForCartHydration(page);
+      let step9EarlyValidation;
+      if (expectedProductTitle) {
+        const v = await validateCartContainsTitle(page, expectedProductTitle, ctx);
+        step9EarlyValidation = {
+          expectedTitle: expectedProductTitle,
+          found: v.found,
+          method: v.method,
+          observedTitles: v.observedTitles.slice(0, 8),
+          reason: v.found ? undefined : `expected title not found among ${v.observedTitles.length} observed on checkout`
+        };
       }
+      const sp9early = screenshotPath(ctx, "pj-9-checkout-reached");
+      await screenshotStable(page, { path: sp9early, fullPage: false });
+      const earlyStatus = step9EarlyValidation && !step9EarlyValidation.found ? "failed" : "ok";
+      steps.push({
+        step: 9,
+        name: "go-checkout",
+        side: ctx.side,
+        viewport: ctx.viewport,
+        status: earlyStatus,
+        durationMs: Date.now() - t9,
+        url: page.url(),
+        screenshotPath: sp9early,
+        cartValidation: step9EarlyValidation,
+        actionDescription: `Já estava em \`${beforeUrl9}\` (minicart navegou direto para checkout)${step9EarlyValidation ? step9EarlyValidation.found ? " ✓ produto persiste no checkout" : ` ✗ produto ESPERADO ausente (${step9EarlyValidation.observedTitles?.length ?? 0} observados)` : ""}`,
+        detail: { reachedVia: "minicart-direct-link" }
+      });
+      reportEnd(9, "go-checkout", earlyStatus, Date.now() - t9);
+      return { pages, steps };
     }
-    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 checkoutHit = await firstVisibleLocator(page, selFor(ctx, "checkoutButton"));
     let checkoutRecovered = false;
-    if (!checkoutHit && recoveryBudget > 0) {
-      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 (!checkoutHit && budget.remaining > 0) {
+      const recovery = await attemptRecovery(page, ctx, "go-checkout", "Clicar no botão 'Finalizar compra' / 'Ir para o checkout' / 'Finalizar'", selFor(ctx, "checkoutButton"));
       if (recovery) {
         checkoutHit = recovery;
         checkoutRecovered = true;
-        recoveryBudget--;
+        budget.remaining--;
       }
     }
     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");
+      steps.push(makeSkipStep(9, "go-checkout", ctx, "no checkout button found (recovery exhausted)"));
+      reportEnd(9, "go-checkout", "skipped", 0, "no checkout button found");
       return { pages, steps };
     }
-    const tryCheckoutClick = async (hit, attempt2) => {
-      const spBefore = screenshotPath(ctx, `pj-8-checkout-before-${attempt2}`);
-      await page.screenshot({ path: spBefore, fullPage: false }).catch(() => {
-        return;
-      });
-      const clickedText2 = await hit.locator.innerText().catch(() => "");
-      const urlBefore = page.url();
-      const urlChangePredicate = alreadyInCheckoutPage ? (u) => u.toString() !== urlBefore : /checkout/i;
+    const spBefore9 = screenshotPath(ctx, "pj-9-checkout-before");
+    await screenshotStable(page, { path: spBefore9, fullPage: false });
+    let usedSelector = checkoutHit.selector;
+    let clickedText = await checkoutHit.locator.innerText().catch(() => "");
+    let reachedCheckout = false;
+    let attempt = 0;
+    const triedSelectors = new Set([usedSelector]);
+    while (attempt < 3) {
+      attempt++;
       await Promise.all([
-        page.waitForURL(urlChangePredicate, { timeout: 1e4 }).catch(() => {
+        page.waitForURL(/\/(checkout|carrinho)/i, { timeout: 1e4 }).catch(() => {
           return;
         }),
-        hit.locator.click({ timeout: 5000 }).catch(() => {
+        checkoutHit.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;
-      });
-      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);
+      reachedCheckout = /\/(checkout|carrinho)(\/|$|\?)/i.test(page.url());
+      if (reachedCheckout)
+        break;
+      if (budget.remaining <= 0)
+        break;
+      dlog2(ctx, `step 9 go-checkout: click on \`${usedSelector}\` didn't navigate (attempt ${attempt}). URL still ${page.url()}. Asking LLM for another selector.`);
+      const triedList = Array.from(triedSelectors);
+      const recovery = await attemptRecovery(page, ctx, "go-checkout", `O click anterior em \`${usedSelector}\` não navegou para /checkout (URL continua em ${page.url()}). Encontre OUTRO selector — o botão real de finalizar compra deve ser visível agora (no drawer aberto ou na página). Não retorne ${triedList.join(", ")} novamente.`, triedList);
+      if (!recovery)
+        break;
+      checkoutHit = recovery;
+      checkoutRecovered = true;
+      usedSelector = recovery.selector;
+      triedSelectors.add(usedSelector);
+      clickedText = await recovery.locator.innerText().catch(() => "");
+      budget.remaining--;
+    }
+    let step9Validation;
+    if (reachedCheckout && expectedProductTitle) {
+      await waitForCartHydration(page);
       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 = {
+      step9Validation = {
         expectedTitle: expectedProductTitle,
         found: v.found,
         method: v.method,
         observedTitles: v.observedTitles.slice(0, 8),
-        reason: reasonText
+        reason: v.found ? undefined : `expected title not found among ${v.observedTitles.length} observed on checkout`
       };
-      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";
+    const sp9 = screenshotPath(ctx, "pj-9-checkout-reached");
+    await screenshotStable(page, { path: sp9, fullPage: false });
+    const step9Status = !reachedCheckout ? "failed" : step9Validation && !step9Validation.found ? "failed" : "ok";
     steps.push({
-      step: 8,
+      step: 9,
       name: "go-checkout",
       side: ctx.side,
       viewport: ctx.viewport,
-      status: step8Status,
-      durationMs: Date.now() - t8,
-      url: result.url,
-      screenshotPath: result.spAfter,
-      screenshotBeforePath: result.spBefore,
-      beforeUrl: beforeUrl8,
-      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)` : ""}`,
+      status: step9Status,
+      durationMs: Date.now() - t9,
+      url: page.url(),
+      screenshotPath: sp9,
+      screenshotBeforePath: spBefore9,
+      beforeUrl: beforeUrl9,
+      cartValidation: step9Validation,
+      actionDescription: `Clicou em${clickedText ? ` '${clickedText.slice(0, 30).trim()}'` : ""} (\`${usedSelector}\`); URL final: ${page.url()}${reachedCheckout ? " ✓ atingiu checkout" : " ✗ não foi pra checkout"}${attempt > 1 ? ` (após ${attempt} tentativas com recovery LLM)` : ""}${step9Validation ? step9Validation.found ? " ✓ produto persiste no checkout" : ` ✗ produto ESPERADO ausente no checkout (${step9Validation.observedTitles?.length ?? 0} observados)` : ""}`,
       selectorKey: "checkoutButton",
       usedSelector,
       recoveredByLlm: checkoutRecovered || undefined
     });
-    reportEnd(8, "go-checkout", step8Status, Date.now() - t8);
+    reportEnd(9, "go-checkout", step9Status, Date.now() - t9);
     return { pages, steps };
   } finally {
     await page.close();
@@ -5879,15 +6245,10 @@ 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);
@@ -5936,34 +6297,20 @@ 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 withCap(elements.count(), 1000, 0);
+      const count = await elements.count();
       for (let i = 0;i < count && out.length < limit; i++) {
-        if (expired())
-          break;
         const el = elements.nth(i);
-        const visible = await withCap(el.isVisible({ timeout: 250 }).catch(() => false), 400, false);
-        if (!visible)
+        if (!await el.isVisible({ timeout: 250 }).catch(() => false))
           continue;
-        const href = await withCap(el.getAttribute("href").catch(() => null), 400, null);
+        const href = await el.getAttribute("href").catch(() => null);
         if (!href)
           continue;
         let abs = href;
@@ -5975,7 +6322,7 @@ async function collectCandidateLinks(page, selectors, limit = 12) {
         if (seenHrefs.has(abs))
           continue;
         seenHrefs.add(abs);
-        const text = (await withCap(el.innerText().catch(() => ""), 400, "")).slice(0, 60).trim();
+        const text = (await el.innerText().catch(() => "")).slice(0, 60).trim();
         out.push({ text, href: abs, selector: sel });
       }
     } catch {}
@@ -5994,34 +6341,388 @@ 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 selectVariant(page, ctx) {
+  const actions = [];
+  let primarySelectorKey;
+  let primarySelector;
+  const trackPrimary = (key, sel) => {
+    if (!primarySelectorKey) {
+      primarySelectorKey = key;
+      primarySelector = sel;
+    }
+  };
+  try {
+    const rowSelectors = selFor(ctx, "variantRow");
+    const incrementSelectors = selFor(ctx, "quantityIncrement");
+    rowLoop:
+      for (const rowSel of rowSelectors) {
+        const rows = page.locator(rowSel);
+        const count = await rows.count().catch(() => 0);
+        for (let i = 0;i < Math.min(count, 5); i++) {
+          const row = rows.nth(i);
+          if (!await row.isVisible({ timeout: 500 }).catch(() => false))
+            continue;
+          const rowText = (await row.innerText().catch(() => "")).replace(/\s+/g, " ").trim();
+          for (const incSel of incrementSelectors) {
+            const plus = row.locator(incSel).first();
+            if (!await plus.isVisible({ timeout: 500 }).catch(() => false))
+              continue;
+            if (await plus.isDisabled().catch(() => false))
+              continue;
+            await plus.click({ timeout: 2000 }).catch(() => {
+              return;
+            });
+            await page.waitForTimeout(400);
+            actions.push(`Incrementou quantidade da variante \`${rowSel}\`[${i}]${rowText ? ` (${rowText.slice(0, 40)})` : ""} via \`${incSel}\``);
+            trackPrimary("variantRow", rowSel);
+            break rowLoop;
+          }
+        }
+      }
+  } catch {}
+  if (actions.length === 0) {
+    const sizeHit = await firstVisibleLocator(page, selFor(ctx, "sizeSwatch"));
+    if (sizeHit && !await sizeHit.locator.isDisabled().catch(() => false)) {
+      const sizeText = (await sizeHit.locator.innerText().catch(() => "")).slice(0, 20).trim();
+      await sizeHit.locator.click({ timeout: 2000 }).catch(() => {
+        return;
+      });
+      await page.waitForTimeout(400);
+      actions.push(`Selecionou tamanho${sizeText ? ` '${sizeText}'` : ""} (\`${sizeHit.selector}\`)`);
+      trackPrimary("sizeSwatch", sizeHit.selector);
+    }
+  }
+  const colorHit = await firstVisibleLocator(page, selFor(ctx, "colorSwatch"));
+  if (colorHit && !await colorHit.locator.isDisabled().catch(() => false)) {
+    const colorText = (await colorHit.locator.innerText().catch(() => "")).slice(0, 20).trim();
+    const colorLabel = colorText || await colorHit.locator.getAttribute("aria-label").catch(() => null) || "";
+    await colorHit.locator.click({ timeout: 2000 }).catch(() => {
+      return;
+    });
+    await page.waitForTimeout(400);
+    actions.push(`Selecionou cor${colorLabel ? ` '${colorLabel}'` : ""} (\`${colorHit.selector}\`)`);
+    trackPrimary("colorSwatch", colorHit.selector);
+  }
+  if (actions.length === 0) {
+    await scrollPageInChunks(page);
+    const result = await findAndIncrementZeroQtyInput(page, ctx);
+    if (result) {
+      actions.push(result.description);
+      trackPrimary(result.selectorKey, result.usedSelector);
+    }
+  }
+  let variantRequired = false;
+  try {
+    const bodyText = await page.locator("body").innerText({ timeout: 1000 }).catch(() => "");
+    variantRequired = VARIANT_REQUIRED_TEXT_PATTERNS.some((re) => re.test(bodyText));
+  } catch {}
+  return { actions, primarySelectorKey, primarySelector, variantRequired };
 }
-async function extractProductTitle(page) {
-  await page.waitForSelector("h1", { timeout: 2500, state: "attached" }).catch(() => {
+async function scrollPageInChunks(page) {
+  await page.evaluate(async () => {
+    const height = document.body.scrollHeight;
+    const stops = [0.2, 0.4, 0.6, 0.8, 1, 0.4];
+    for (const frac of stops) {
+      window.scrollTo({ top: height * frac, behavior: "instant" });
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    window.scrollTo({ top: 0, behavior: "instant" });
+  }).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"
+  await page.waitForTimeout(1200);
+}
+async function findAndIncrementZeroQtyInput(page, ctx) {
+  const qtySelectors = selFor(ctx, "quantityInput");
+  const scopeSelectors = [
+    "[data-manifest-key*='ProductDetails' i]",
+    "[data-manifest-key*='Product/' i]",
+    "main"
   ];
-  for (const sel of visibleSelectors) {
+  const scopeRoots = [];
+  for (const sel of scopeSelectors) {
+    const cand = page.locator(sel).first();
+    if (await cand.count().then((n) => n > 0).catch(() => false)) {
+      scopeRoots.push({ root: cand, tag: "main" });
+      break;
+    }
+  }
+  scopeRoots.push({ root: null, tag: "page" });
+  for (const { root, tag } of scopeRoots) {
+    for (const sel of qtySelectors) {
+      const all = root ? root.locator(sel) : page.locator(sel);
+      const count = await all.count().catch(() => 0);
+      for (let i = 0;i < Math.min(count, 20); i++) {
+        const el = all.nth(i);
+        if (!await el.isVisible({ timeout: 300 }).catch(() => false))
+          continue;
+        const value = (await el.inputValue().catch(() => "")).trim();
+        if (value !== "" && value !== "0")
+          continue;
+        const plus = await findPlusButtonNear(el);
+        if (plus) {
+          if (await plus.isDisabled().catch(() => false))
+            continue;
+          await plus.click({ timeout: 2000 }).catch(() => {
+            return;
+          });
+          await page.waitForTimeout(500);
+          return {
+            description: `Incrementou variante via botão '+' próximo ao input \`${sel}\` (scope=${tag}, índice ${i})`,
+            selectorKey: "quantityInput",
+            usedSelector: sel
+          };
+        }
+        await el.fill("1", { timeout: 1500 }).catch(() => {
+          return;
+        });
+        await el.dispatchEvent("input").catch(() => {
+          return;
+        });
+        await el.dispatchEvent("change").catch(() => {
+          return;
+        });
+        await page.waitForTimeout(400);
+        return {
+          description: `Ajustou quantidade do input \`${sel}\` para 1 (scope=${tag}, índice ${i})`,
+          selectorKey: "quantityInput",
+          usedSelector: sel
+        };
+      }
+    }
+  }
+  return null;
+}
+async function findPlusButtonNear(input) {
+  const ancestorXPath = "xpath=ancestor::*[self::li or self::tr or self::form or self::fieldset or @data-sku-row or @data-variant-row][1]//button[normalize-space(.)='+']";
+  const inAncestor = input.locator(ancestorXPath).first();
+  if (await inAncestor.isVisible({ timeout: 600 }).catch(() => false)) {
+    return inAncestor;
+  }
+  for (let depth = 1;depth <= 6; depth++) {
+    const climb = `xpath=ancestor::*[${depth}]//button[normalize-space(.)='+']`;
+    const cand = input.locator(climb).first();
+    if (await cand.isVisible({ timeout: 300 }).catch(() => false)) {
+      return cand;
+    }
+  }
+  const sibling = input.locator("xpath=following-sibling::button[1]").first();
+  if (await sibling.isVisible({ timeout: 300 }).catch(() => false)) {
+    const text = (await sibling.innerText().catch(() => "")).trim();
+    if (text === "+")
+      return sibling;
+  }
+  return null;
+}
+async function readCartCount(page, ctx) {
+  const selectors = selFor(ctx, "minicartCount");
+  for (const sel of selectors) {
+    try {
+      const el = page.locator(sel).first();
+      if (!await el.isVisible({ timeout: 500 }).catch(() => false))
+        continue;
+      const raw = (await el.innerText().catch(() => "")).trim();
+      const match = raw.match(/\d+/);
+      if (match)
+        return Number.parseInt(match[0], 10);
+    } catch {}
+  }
+  return 0;
+}
+async function validateAddToCart(page, ctx, cartCountBefore, beforeUrl) {
+  const deadline = Date.now() + 3000;
+  let lastErrorText;
+  while (Date.now() < deadline) {
+    const currentUrl = page.url();
+    if (currentUrl !== beforeUrl && /\/(cart|carrinho|checkout)(\/|$|\?)/i.test(currentUrl)) {
+      return {
+        status: "ok",
+        signal: "url-changed",
+        note: `URL mudou para \`${currentUrl}\` (carrinho/checkout)`
+      };
+    }
+    const cartCountNow = await readCartCount(page, ctx);
+    if (cartCountNow > cartCountBefore) {
+      return {
+        status: "ok",
+        signal: "count-increased",
+        note: `Contador do minicart foi de ${cartCountBefore} para ${cartCountNow}`
+      };
+    }
+    const drawerSelectors = [
+      "[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)) {
+        return {
+          status: "ok",
+          signal: "drawer-open",
+          note: `Drawer/modal do carrinho abriu (\`${sel}\`)`
+        };
+      }
+    }
+    try {
+      const bodyText = await page.locator("body").innerText({ timeout: 500 }).catch(() => "");
+      for (const re of ADD_TO_CART_SUCCESS_PATTERNS) {
+        const match = bodyText.match(re);
+        if (match) {
+          return {
+            status: "ok",
+            signal: "success-toast",
+            note: `Toast de sucesso visível: '${match[0]}'`
+          };
+        }
+      }
+      for (const re of ADD_TO_CART_ERROR_PATTERNS) {
+        const match = bodyText.match(re);
+        if (match) {
+          lastErrorText = match[0];
+          break;
+        }
+      }
+    } catch {}
+    await page.waitForTimeout(250);
+  }
+  if (lastErrorText) {
+    return {
+      status: "failed",
+      signal: "error-text",
+      note: `add-to-cart silenciosamente falhou: '${lastErrorText}' visível na página`,
+      errorText: lastErrorText
+    };
+  }
+  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)"
+  };
+}
+async function attemptRecovery(page, _ctx, stepName, intendedAction, alreadyTried) {
+  let html = "";
+  try {
+    html = await page.content();
+  } catch {
+    return null;
+  }
+  const suggestion = await suggestRecovery({ stepName, intendedAction, html, alreadyTried });
+  if (!suggestion)
+    return null;
+  try {
+    const el = page.locator(suggestion.selector).first();
+    if (await el.isVisible({ timeout: 2000 }).catch(() => false)) {
+      return { locator: el, selector: suggestion.selector };
+    }
+  } catch {}
+  return null;
+}
+async function attemptStepAction(args) {
+  const { page, ctx, stepName, intendedAction, selectorKey, action, value, recoveryBudget } = args;
+  const selectors = selFor(ctx, selectorKey);
+  for (const sel of selectors) {
+    try {
+      const el = page.locator(sel).first();
+      if (!await el.isVisible({ timeout: 800 }).catch(() => false))
+        continue;
+      const ok = await performAction(el, action, value);
+      if (ok) {
+        return { performed: true, selector: sel, action, recoveredByLlm: false };
+      }
+    } catch {}
+  }
+  if (recoveryBudget.remaining <= 0) {
+    return { performed: false, selector: "", action, recoveredByLlm: false };
+  }
+  let html = "";
+  try {
+    html = await page.content();
+  } catch {
+    return { performed: false, selector: "", action, recoveredByLlm: false };
+  }
+  const suggestion = await suggestRecovery({
+    stepName,
+    intendedAction,
+    html,
+    alreadyTried: selectors
+  });
+  if (!suggestion) {
+    return { performed: false, selector: "", action, recoveredByLlm: false };
+  }
+  recoveryBudget.remaining--;
+  const llmAction = suggestion.action ?? action;
+  const llmValue = suggestion.value ?? value;
+  try {
+    const el = page.locator(suggestion.selector).first();
+    if (!await el.isVisible({ timeout: 2000 }).catch(() => false)) {
+      return { performed: false, selector: "", action: llmAction, recoveredByLlm: false };
+    }
+    const ok = await performAction(el, llmAction, llmValue);
+    if (ok) {
+      return {
+        performed: true,
+        selector: suggestion.selector,
+        action: llmAction,
+        recoveredByLlm: true
+      };
+    }
+  } catch {}
+  return { performed: false, selector: "", action: llmAction, recoveredByLlm: false };
+}
+async function performAction(el, action, value) {
+  try {
+    if (action === "click") {
+      await el.click({ timeout: 3000 });
+      return true;
+    }
+    if (action === "fill") {
+      await el.fill(value ?? "", { timeout: 3000 });
+      await el.press("Enter", { timeout: 1500 }).catch(() => {
+        return;
+      });
+      return true;
+    }
+    if (action === "press") {
+      await el.press(value ?? "Enter", { timeout: 1500 });
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  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);
@@ -6077,6 +6778,80 @@ async function isCartUiVisible(page) {
     "[class*='drawer-cart']:visible"
   ]);
 }
+async function detectCartRevealMode(page, trigger, drawerAlreadyOpen, viewport) {
+  if (drawerAlreadyOpen)
+    return "inline-notification";
+  try {
+    const href = await trigger.getAttribute("href").catch(() => null) ?? "";
+    const lower = href.toLowerCase();
+    if (/\/checkout(\b|\/|\?|#)/i.test(lower))
+      return "click-navigate-checkout";
+    if (/\/cart(\b|\/|\?|#)/i.test(lower) || /\/carrinho(\b|\/|\?|#)/i.test(lower)) {
+      return "click-navigate-cart";
+    }
+  } catch {}
+  let hasClickAttr = false;
+  try {
+    const onclick = await trigger.getAttribute("onclick").catch(() => null);
+    if (onclick && onclick.trim().length > 0)
+      hasClickAttr = true;
+  } catch {}
+  if (viewport === "desktop") {
+    try {
+      const observedHoverDrawer = await page.evaluate(async () => {
+        return await new Promise((resolve) => {
+          const selectorMatch = (el) => {
+            if (!(el instanceof HTMLElement))
+              return false;
+            if (el.getAttribute("role") === "dialog")
+              return true;
+            const cls = `${el.className || ""}`;
+            return /minicart|drawer|cart-popup|cart-modal/i.test(cls);
+          };
+          const observer = new MutationObserver((muts) => {
+            for (const m of muts) {
+              for (const n of Array.from(m.addedNodes)) {
+                if (n instanceof Element && selectorMatch(n)) {
+                  observer.disconnect();
+                  resolve(true);
+                  return;
+                }
+              }
+              if (m.type === "attributes" && m.target instanceof Element && selectorMatch(m.target)) {
+                observer.disconnect();
+                resolve(true);
+                return;
+              }
+            }
+          });
+          observer.observe(document.body, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ["class", "style", "aria-expanded", "open"]
+          });
+          setTimeout(() => {
+            observer.disconnect();
+            resolve(false);
+          }, 600);
+        });
+      });
+      const hoverPromise = trigger.hover({ timeout: 1500 }).catch(() => {
+        return;
+      });
+      await hoverPromise;
+      const result = await observedHoverDrawer;
+      await page.mouse.move(0, 0).catch(() => {
+        return;
+      });
+      if (result)
+        return "hover-drawer";
+    } catch {}
+  }
+  if (hasClickAttr)
+    return "click-drawer";
+  return "unknown";
+}
 async function isCartRevealed(page, expectedProductTitle) {
   if (expectedProductTitle) {
     const v = await validateCartContainsTitleQuick(page, expectedProductTitle);
@@ -6246,7 +7021,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       }
     })();
     if (targetUrl) {
-      dlog2(ctx, `  openMinicart: all interactive strategies failed but trigger has cart href, navigating directly to ${targetUrl}`);
+      dlog2(ctx, `  openMinicart: all interactive strategies failed; navigating directly to ${targetUrl}`);
       await page.goto(targetUrl, { waitUntil: "load", timeout: 15000 }).catch(() => {
         return;
       });
@@ -6345,7 +7120,7 @@ async function validateCartContainsTitle(page, expectedTitle, ctx) {
     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 ? " | …" : ""}]` : ""}`);
+  dlog2(ctx, `  validateCartContainsTitle: observed ${observed.length} titles`);
   if (observed.length === 0) {
     return { found: false, observedTitles: [], method: "none" };
   }
@@ -6374,24 +7149,6 @@ async function detectEmptyCartBanner(page) {
   }
   return null;
 }
-async function attemptRecovery(page, _ctx, stepName, intendedAction, alreadyTried) {
-  let html = "";
-  try {
-    html = await page.content();
-  } catch {
-    return null;
-  }
-  const suggestion = await suggestRecovery({ stepName, intendedAction, html, alreadyTried });
-  if (!suggestion)
-    return null;
-  try {
-    const el = page.locator(suggestion.selector).first();
-    if (await el.isVisible({ timeout: 2000 }).catch(() => false)) {
-      return { locator: el, selector: suggestion.selector };
-    }
-  } catch {}
-  return null;
-}
 
 // src/ignore/parser.ts
 import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
@@ -6501,6 +7258,51 @@ function detectFromHtml(html) {
   return "custom";
 }
 
+// src/learned/promote.ts
+function promoteStepsFromFlow(learned, platform, host, flow) {
+  let promoted = 0;
+  let deprecated = 0;
+  let recorded = 0;
+  for (const step of flow.steps ?? []) {
+    if (!step.selectorKey || !step.usedSelector)
+      continue;
+    if (!isReusableSelector(step.usedSelector))
+      continue;
+    const parsed = SelectorKey.safeParse(step.selectorKey);
+    if (!parsed.success)
+      continue;
+    const key = parsed.data;
+    if (step.recoveredByLlm) {
+      promoteFromLlm(learned, platform, key, step.usedSelector, host);
+      promoted++;
+    } else if (step.status === "ok") {
+      recordSuccess(learned, platform, key, step.usedSelector, host);
+      recorded++;
+    } else if (step.status === "failed") {
+      const wasDeprecated = isAlreadyDeprecated(learned, platform, key, step.usedSelector);
+      const after = recordFailure(learned, platform, key, step.usedSelector, host);
+      if (!wasDeprecated && after?.deprecated)
+        deprecated++;
+    }
+  }
+  return { promoted, deprecated, recorded };
+}
+function isReusableSelector(s) {
+  if (s.includes("→"))
+    return false;
+  if (s.includes(" ~ "))
+    return false;
+  return s.trim().length > 0;
+}
+function isAlreadyDeprecated(lib, platform, key, selector) {
+  const platformEntries = lib.platforms[platform];
+  if (!platformEntries)
+    return false;
+  const entries = platformEntries[key] ?? [];
+  const entry = entries.find((e) => e.selector === selector);
+  return !!entry?.deprecated;
+}
+
 // src/llm/discover-selectors.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join6 } from "node:path";
@@ -6526,26 +7328,26 @@ var DISCOVER_SELECTORS_TOOL = {
       },
       minicart_trigger: {
         type: "string",
-        description: "CSS selector for the element that opens the mini-cart drawer/popup (e.g. '[data-minicart-trigger]', or a header cart icon)."
+        description: `CSS selector for the CART ICON / SACOLA icon in the HEADER that opens the mini-cart drawer or navigates to the cart page when clicked (e.g. '[data-minicart-trigger]', or 'header a[aria-label*="sacola" i]', or 'header a[href*="cart"]'). This is the icon ALWAYS visible in the page header.`
       },
       cep_input_pdp: {
         type: "string",
-        description: "CSS selector for the CEP / zipcode <input> on a PDP. Empty string if the PDP has no shipping calculator."
+        description: "CSS selector for the CEP / zipcode <input> on a PDP — the input where the customer types their ADDRESS POSTAL CODE to calculate shipping. Placeholder is typically 'CEP', 'Digite seu CEP', 'Cód. postal'. Do NOT return a coupon input ('Digite o cupom') or email/newsletter field. Empty string if the PDP has no shipping calculator."
       },
       cep_input_cart: {
         type: "string",
-        description: "CSS selector for the CEP / zipcode <input> inside the mini-cart/cart drawer. Empty string if cart has no shipping calculator."
+        description: "CSS selector for the CEP / zipcode <input> inside the mini-cart drawer or cart page — for shipping calculation. Same rules: ADDRESS postal code, NOT coupon, NOT email. Empty string if cart has no shipping calculator."
       },
       checkout_button: {
         type: "string",
-        description: `CSS selector for the 'Go to checkout' / 'Finalizar compra' button inside the mini-cart/cart (e.g. "a:has-text('Finalizar compra')").`
+        description: "CSS selector for the FINAL 'Go to checkout' / 'Finalizar compra' / 'Finalizar' button INSIDE the mini-cart drawer or cart page — the one user clicks AFTER reviewing cart items to proceed to checkout/payment. **IMPORTANT**: this is DIFFERENT from `minicart_trigger` (which is the cart ICON in the header). The checkout button is typically a big colored button at the bottom of the cart drawer or cart page. If you cannot see it on the home page (which is common — it's only rendered after add-to-cart), return EMPTY STRING. NEVER return the same selector as `minicart_trigger`."
       },
       reasoning: {
         type: "string",
         description: "1-2 sentence rationale describing what was inferred from the markup."
       }
     },
-    required: ["category_link", "product_card", "buy_button", "minicart_trigger", "checkout_button"]
+    required: ["category_link", "product_card", "buy_button", "minicart_trigger"]
   }
 };
 var SYSTEM_PROMPT = `
@@ -6582,7 +7384,17 @@ REGRAS:
 4. Para "cep_input_pdp" e "cep_input_cart": retorne string vazia se não existir esse recurso na plataforma.
    Não invente.
 
-5. Sempre teste mentalmente: "este seletor pegaria o elemento certo na home E também em PDPs/cart?"
+5. **NUNCA confunda \`minicart_trigger\` (ícone do carrinho no HEADER) com \`checkout_button\`
+   (botão "Finalizar" DENTRO do drawer ou na página de cart).** Se você só vê o ícone do
+   carrinho na home e não consegue ver o botão de checkout (caso comum — ele só renderiza
+   depois de add-to-cart), retorne STRING VAZIA pra \`checkout_button\`. NUNCA retorne o
+   mesmo seletor para os dois — isso quebra o fluxo de teste.
+
+6. Para CEP: \`cep_input_pdp\` e \`cep_input_cart\` são pra ENDEREÇO (CEP / Postal Code).
+   NÃO confunda com input de CUPOM ('Digite o cupom', 'Insira código', 'Promo code') —
+   cupom é desconto, não frete.
+
+7. Sempre teste mentalmente: "este seletor pegaria o elemento certo na home E também em PDPs/cart?"
 
 Responda SEMPRE via tool_use report_selectors. Não escreva texto livre fora da tool call.
 `.trim();
@@ -6656,12 +7468,24 @@ ${compacted}
     cepInputCart: emptyToUndef(input.cep_input_cart),
     checkoutButton: emptyToUndef(input.checkout_button)
   };
+  if (selectors.checkoutButton && selectors.minicartTrigger && selectorsLikelyConflict(selectors.checkoutButton, selectors.minicartTrigger)) {
+    console.warn(`[discover-selectors] checkout_button == minicart_trigger (\`${selectors.checkoutButton}\`); dropping to avoid step-9 misclick`);
+    selectors.checkoutButton = undefined;
+  }
   if (!existsSync6(cacheDir))
     mkdirSync4(cacheDir, { recursive: true });
   writeFileSync5(cachePath, `${JSON.stringify(selectors, null, 2)}
 `, "utf8");
   return selectors;
 }
+function selectorsLikelyConflict(a, b) {
+  if (a === b)
+    return true;
+  const norm = (s) => s.replace(/\s+/g, "").toLowerCase();
+  const na = norm(a);
+  const nb = norm(b);
+  return na.includes(nb) || nb.includes(na);
+}
 function emptyToUndef(v) {
   if (v == null)
     return;
@@ -6681,11 +7505,12 @@ var STEP_LABELS = {
   "visit-home": "1. visit-home",
   "navigate-plp": "2. navigate-plp",
   "enter-pdp": "3. enter-pdp",
-  "shipping-calc-pdp": "4. shipping-calc-pdp",
-  "add-to-cart": "5. add-to-cart",
-  "open-minicart": "6. open-minicart",
-  "shipping-calc-cart": "7. shipping-calc-cart",
-  "go-checkout": "8. go-checkout"
+  "select-variant": "4. select-variant",
+  "shipping-calc-pdp": "5. shipping-calc-pdp",
+  "add-to-cart": "6. add-to-cart",
+  "open-minicart": "7. open-minicart",
+  "shipping-calc-cart": "8. shipping-calc-cart",
+  "go-checkout": "9. go-checkout"
 };
 var CRITICAL_STEPS = new Set([
   "visit-home",
@@ -6720,7 +7545,7 @@ async function journeyCommand(opts) {
   let platform = "custom";
   try {
     const homeRes = await fetch(opts.prod, {
-      headers: { "User-Agent": "Mozilla/5.0 parity-cli" }
+      headers: { "User-Agent": userAgentFor(viewports[0] ?? "mobile") }
     });
     if (homeRes.ok) {
       const html = await homeRes.text();
@@ -6789,7 +7614,8 @@ async function journeyCommand(opts) {
         learned,
         platform,
         recoveryBudget: 3,
-        onStep: onStepFor(viewport, side)
+        onStep: onStepFor(viewport, side),
+        acceptProdQuirks: opts.acceptProdQuirks
       });
       return cap;
     } finally {
@@ -6814,6 +7640,39 @@ async function journeyCommand(opts) {
     }
     if (!opts.json)
       console.log("");
+    const learnedBefore = JSON.stringify(learned);
+    const prodHost = safeHost2(opts.prod);
+    let totalPromoted = 0;
+    let totalDeprecated = 0;
+    let totalRecorded = 0;
+    for (const cap of flowCaptures) {
+      if (cap.side !== "prod")
+        continue;
+      const result = promoteStepsFromFlow(learned, platform, prodHost, cap);
+      totalPromoted += result.promoted;
+      totalDeprecated += result.deprecated;
+      totalRecorded += result.recorded;
+    }
+    if (JSON.stringify(learned) !== learnedBefore) {
+      try {
+        saveLearned(learned);
+        if (!opts.json) {
+          const bits = [];
+          if (totalPromoted > 0)
+            bits.push(`${totalPromoted} promovido(s) via LLM`);
+          if (totalRecorded > 0)
+            bits.push(`${totalRecorded} reforçado(s)`);
+          if (totalDeprecated > 0)
+            bits.push(`${totalDeprecated} depreciado(s)`);
+          if (bits.length > 0)
+            console.log(chalk6.dim(`  learned-selectors atualizado: ${bits.join(", ")}`));
+        }
+      } catch (err) {
+        if (!opts.json) {
+          console.warn(chalk6.yellow(`  warn: failed to persist learned-selectors: ${err.message}`));
+        }
+      }
+    }
     const rows = buildRows(flowCaptures, viewports);
     const failures = collectFailures(rows);
     writeRunReportJson(paths.runDir, buildJourneyRun(opts, runId, flowCaptures, failures));
@@ -7171,6 +8030,13 @@ function renderSummaryBlock(rows, failures) {
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+function safeHost2(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
 
 // src/commands/learned.ts
 import chalk7 from "chalk";
@@ -7900,6 +8766,17 @@ function normalizeUrl(rawUrl) {
 }
 
 // src/diff/dom.ts
+var BANNER_WIDTH_THRESHOLD = 600;
+var BANNER_SECTION_RE = /(carousel|slider|banner|hero)/i;
+function parseDim(raw) {
+  if (!raw)
+    return null;
+  const trimmed = raw.replace(/px$/i, "").trim();
+  if (!trimmed)
+    return null;
+  const n = Number(trimmed);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
 function snapshotDom(html) {
   const $ = cheerio5.load(html);
   const counts = {
@@ -7947,12 +8824,29 @@ function snapshotDom(html) {
     jsonLdTypes: jsonLdTypes.sort()
   };
   const imgs = $("img");
+  const banners = [];
+  imgs.each((_, el) => {
+    const $el = $(el);
+    const widthAttr = parseDim($el.attr("width"));
+    const heightAttr = parseDim($el.attr("height"));
+    const sectionAncestor = $el.parents("[data-section]").filter((_2, p) => BANNER_SECTION_RE.test($(p).attr("data-section") ?? "")).first();
+    const sectionName = sectionAncestor.length > 0 ? sectionAncestor.attr("data-section") ?? null : null;
+    const looksLikeBanner = sectionName !== null || widthAttr !== null && widthAttr >= BANNER_WIDTH_THRESHOLD;
+    if (!looksLikeBanner)
+      return;
+    const src = $el.attr("src") ?? "";
+    if (!src)
+      return;
+    const aspectRatio = widthAttr && heightAttr && heightAttr > 0 ? widthAttr / heightAttr : null;
+    banners.push({ src, width: widthAttr, height: heightAttr, aspectRatio, sectionName });
+  });
   const imageStats = {
     total: imgs.length,
     withSrcset: imgs.filter((_, el) => Boolean($(el).attr("srcset"))).length,
     withAlt: imgs.filter((_, el) => Boolean($(el).attr("alt"))).length,
     withoutAlt: imgs.filter((_, el) => !$(el).attr("alt")).length,
-    src: imgs.map((_, el) => $(el).attr("src") ?? "").get().filter(Boolean)
+    src: imgs.map((_, el) => $(el).attr("src") ?? "").get().filter(Boolean),
+    banners
   };
   const decoSectionsRendered = [];
   $("[data-section]").each((_, el) => {
@@ -8271,6 +9165,9 @@ function buildContextBlock(input) {
   if (input.sectionsOnlyInProd && input.sectionsOnlyInProd.length > 0) {
     lines.push("", "**Sections detectadas no DOM de prod mas AUSENTES em cand** (provavelmente faltando migrar):", ...input.sectionsOnlyInProd.map((s) => `- ${s}`), "", "Verifique visualmente se essas sections aparecem na 2ª imagem. Se ausentes, reporte como missing-component com severity high ou critical.");
   }
+  if (input.bothHaveCarousel) {
+    lines.push("", "**Ambos os lados expõem um carousel/slider no DOM.** Diferenças no conteúdo do hero (banner diferente, texto diferente, imagem diferente) provavelmente são apenas slides diferentes do mesmo carousel capturados em momentos distintos. NÃO reporte essas diferenças como critical/high. Se o carousel inteiro sumir, ou o layout do hero quebrar, isso sim reporte normalmente.");
+  }
   if (input.prodSections && input.prodSections.length > 0) {
     lines.push("", `Total sections em prod: ${input.prodSections.length}; em cand: ${input.candSections?.length ?? 0}.`);
   }
@@ -8329,6 +9226,32 @@ function pathFromKey(key) {
 function severityForDiff(d) {
   return d.severity;
 }
+var CAROUSEL_SECTION_RE = /(carousel|slider)/i;
+function hasCarouselSection(sections) {
+  return sections.some((s) => CAROUSEL_SECTION_RE.test(s));
+}
+function downgradeCarouselFramingDiffs(diffs, bothHaveCarousel) {
+  if (!bothHaveCarousel)
+    return diffs;
+  const CAROUSEL_FRAME_TYPES = new Set([
+    "different-component",
+    "image-diff",
+    "text-changed"
+  ]);
+  return diffs.map((d) => {
+    if (d.region !== "hero")
+      return d;
+    if (!CAROUSEL_FRAME_TYPES.has(d.type))
+      return d;
+    if (d.severity === "low")
+      return d;
+    return {
+      ...d,
+      severity: "low",
+      description: `${d.description} [downgraded: ambos os lados expõem um carousel/slider — provável diferença só de slide ativo no momento da captura]`
+    };
+  });
+}
 async function visualRegressionKeyframes(ctx) {
   const start = Date.now();
   const { pairs } = pairCaptures(ctx.prodPages, ctx.candPages);
@@ -8372,6 +9295,7 @@ async function visualRegressionKeyframes(ctx) {
     const prodSet = new Set(prodSections);
     const sectionsOnlyInProd = prodSections.filter((s) => !candSet.has(s));
     const sectionsOnlyInCand = candSections.filter((s) => !prodSet.has(s));
+    const bothHaveCarousel = hasCarouselSection(prodSections) && hasCarouselSection(candSections);
     const trivial = pctDiff < PASS_PCT_THRESHOLD && sectionsOnlyInProd.length === 0;
     let differences = [];
     let llmCalled = false;
@@ -8387,13 +9311,17 @@ async function visualRegressionKeyframes(ctx) {
           viewport: pair.viewport,
           prodSections,
           candSections,
-          sectionsOnlyInProd
+          sectionsOnlyInProd,
+          bothHaveCarousel
         });
         differences = diffs ?? [];
       } catch (err) {
         llmError = err.message;
       }
     }
+    if (differences.length > 0) {
+      differences = downgradeCarouselFramingDiffs(differences, bothHaveCarousel);
+    }
     let verdict;
     const hasCritical = differences.some((d) => d.severity === "critical" || d.severity === "high");
     const hasAnyDiff = differences.length > 0 || sectionsOnlyInProd.length > 0;
@@ -8489,6 +9417,7 @@ var STEP_LABELS2 = {
   "visit-home": "Visitar home",
   "navigate-plp": "Navegar para categoria (PLP)",
   "enter-pdp": "Entrar em PDP",
+  "select-variant": "Selecionar variante (tamanho/cor/quantidade)",
   "shipping-calc-pdp": "Cálculo de frete na PDP",
   "add-to-cart": "Adicionar ao carrinho",
   "open-minicart": "Abrir minicart",
@@ -8817,6 +9746,179 @@ function countFailedImageRequests(entries) {
   return entries.filter((e) => e.resourceType === "image" && (e.status === 0 || e.status >= 400)).length;
 }
 
+// src/checks/banner-aspect-ratio.ts
+var ASPECT_RATIO_TOLERANCE = 0.15;
+function bannerAspectRatio(ctx) {
+  const start = Date.now();
+  const { pairs } = pairCaptures(ctx.prodPages, ctx.candPages);
+  const issues = [];
+  let pagesChecked = 0;
+  let pagesWithIssues = 0;
+  for (const pair of pairs) {
+    if (!pair.prod.html || !pair.cand.html)
+      continue;
+    pagesChecked++;
+    const prodBanners = snapshotDom(pair.prod.html).imageStats.banners;
+    const candBanners = snapshotDom(pair.cand.html).imageStats.banners;
+    if (prodBanners.length === 0 && candBanners.length === 0)
+      continue;
+    const pageIssuesBefore = issues.length;
+    const len = Math.min(prodBanners.length, candBanners.length);
+    const comparisons = [];
+    for (let i = 0;i < len; i++) {
+      const prod = prodBanners[i];
+      const cand = candBanners[i];
+      if (prod && cand)
+        comparisons.push({ index: i, prod, cand });
+    }
+    for (const cmp of comparisons) {
+      issues.push(...issuesForPair(pair.key, cmp));
+    }
+    if (prodBanners.length !== candBanners.length) {
+      issues.push({
+        id: `banner-aspect:count:${pair.key}`,
+        severity: "medium",
+        category: "visual",
+        page: pair.key,
+        check: "banner-aspect-ratio",
+        summary: `Banner count divergente em ${pair.key}: prod=${prodBanners.length}, cand=${candBanners.length}`
+      });
+    }
+    if (issues.length > pageIssuesBefore)
+      pagesWithIssues++;
+  }
+  const status = issues.some((i) => i.severity === "high" || i.severity === "critical") ? "fail" : issues.length > 0 ? "warn" : "pass";
+  return {
+    name: "banner-aspect-ratio",
+    status,
+    severity: "medium",
+    durationMs: Date.now() - start,
+    summary: `${pagesChecked} página(s) analisada(s), ${pagesWithIssues} com diferença de aspect ratio em banner`,
+    issues,
+    data: { pagesChecked, pagesWithIssues }
+  };
+}
+function issuesForPair(pageKey, cmp) {
+  const { prod, cand, index } = cmp;
+  const out = [];
+  const label = describeBanner(prod) || describeBanner(cand) || `banner #${index + 1}`;
+  const prodHasDims = prod.width !== null && prod.height !== null;
+  const candHasDims = cand.width !== null && cand.height !== null;
+  if (prodHasDims && !candHasDims) {
+    out.push({
+      id: `banner-aspect:missing-dims:${pageKey}:${index}`,
+      severity: "medium",
+      category: "performance",
+      page: pageKey,
+      check: "banner-aspect-ratio",
+      summary: `Atributos width/height ausentes em cand para ${label} (prod=${prod.width}×${prod.height}). Aumenta CLS porque o navegador não consegue reservar o slot antes da imagem decodificar.`
+    });
+  }
+  if (prod.aspectRatio !== null && cand.aspectRatio !== null) {
+    const ratioDelta = Math.abs(prod.aspectRatio - cand.aspectRatio) / prod.aspectRatio;
+    if (ratioDelta >= ASPECT_RATIO_TOLERANCE) {
+      const shape = (r) => r > 1.5 ? "wide" : r < 0.8 ? "tall" : "near-square";
+      const prodShape = shape(prod.aspectRatio);
+      const candShape = shape(cand.aspectRatio);
+      const orientationFlipped = prodShape === "wide" && candShape === "tall" || prodShape === "tall" && candShape === "wide";
+      out.push({
+        id: `banner-aspect:ratio:${pageKey}:${index}`,
+        severity: orientationFlipped ? "high" : "medium",
+        category: "visual",
+        page: pageKey,
+        check: "banner-aspect-ratio",
+        summary: `Aspect ratio divergente em ${label}: prod=${prod.width}×${prod.height} (${prod.aspectRatio.toFixed(2)}) vs cand=${cand.width}×${cand.height} (${cand.aspectRatio.toFixed(2)}) — Δ${(ratioDelta * 100).toFixed(0)}%${orientationFlipped ? ` (${prodShape} ↔ ${candShape}, provável variante mobile/desktop trocada)` : ""}`
+      });
+    }
+  }
+  return out;
+}
+function describeBanner(b) {
+  if (b.sectionName)
+    return `${b.sectionName} banner`;
+  const fname = b.src.split("?")[0]?.split("/").pop();
+  return fname ? `banner '${fname.slice(0, 40)}'` : null;
+}
+
+// src/checks/cart-reveal-mode.ts
+function cartRevealModeDivergence(ctx) {
+  const start = Date.now();
+  const issues = [];
+  let viewportsChecked = 0;
+  let viewportsDivergent = 0;
+  for (const viewport of ctx.viewports) {
+    const prodMode = readMode(ctx.prodFlows, viewport);
+    const candMode = readMode(ctx.candFlows, viewport);
+    if (prodMode === null && candMode === null)
+      continue;
+    viewportsChecked++;
+    if (prodMode === null || candMode === null) {
+      continue;
+    }
+    if (prodMode === candMode)
+      continue;
+    viewportsDivergent++;
+    issues.push({
+      id: `cart-reveal-mode:${viewport}:divergent`,
+      severity: "critical",
+      category: "functional",
+      check: "cart-reveal-mode-divergence",
+      summary: `[${viewport}] minicart trigger divergente: prod=${prodMode}, cand=${candMode}${explainDivergence(prodMode, candMode)}`,
+      details: detailFor(prodMode, candMode, viewport)
+    });
+  }
+  const status = viewportsDivergent > 0 ? "fail" : viewportsChecked > 0 ? "pass" : "skipped";
+  return {
+    name: "cart-reveal-mode-divergence",
+    status,
+    severity: "critical",
+    durationMs: Date.now() - start,
+    summary: viewportsChecked === 0 ? "purchase-journey não rodou ou step 7 não classificou cart reveal mode" : `${viewportsChecked} viewport(s) checados, ${viewportsDivergent} com markup divergente`,
+    issues,
+    data: { viewportsChecked, viewportsDivergent }
+  };
+}
+function readMode(flows, viewport) {
+  const flow = flows.find((f) => f.flow === "purchase-journey" && f.viewport === viewport);
+  if (!flow)
+    return null;
+  const step7 = flow.steps?.find((s) => s.name === "open-minicart");
+  return step7?.cartRevealMode ?? null;
+}
+function explainDivergence(prod, cand) {
+  const candIsNav = cand === "click-navigate-checkout" || cand === "click-navigate-cart";
+  const prodIsDrawer = prod === "hover-drawer" || prod === "click-drawer" || prod === "inline-notification";
+  if (candIsNav && prodIsDrawer) {
+    return " — usuário em cand é levado direto pra navegação em vez de inspecionar cart inline";
+  }
+  const prodIsNav = prod === "click-navigate-checkout" || prod === "click-navigate-cart";
+  const candIsDrawer = cand === "hover-drawer" || cand === "click-drawer" || cand === "inline-notification";
+  if (prodIsNav && candIsDrawer) {
+    return " — cand expõe um drawer onde prod fazia hard navigation (ganho de UX, mas mudança de fluxo)";
+  }
+  return "";
+}
+function detailFor(prod, cand, viewport) {
+  return [
+    `Viewport: ${viewport}`,
+    `Prod cart reveal mode: ${prod}`,
+    `Cand cart reveal mode: ${cand}`,
+    "",
+    "Os dois lados foram exercitados pelo step 7 (open-minicart). O markup",
+    "do trigger do minicart, porém, indica intenções diferentes:",
+    "  - hover-drawer:          trigger reveala drawer inline ao hover",
+    "  - click-drawer:          trigger tem handler de click que abre drawer inline",
+    "  - click-navigate-*:      trigger é link que NAVEGA pro checkout/cart",
+    "  - inline-notification:   drawer já foi aberto pelo add-to-cart",
+    "",
+    "Causas comuns de divergência em migração Deco Fresh→TanStack:",
+    "  1. Migração trocou o elemento <a href=...> por <button> (ou vice-versa)",
+    "  2. Migração removeu o data-toggle / aria-haspopup que ativava o drawer",
+    "  3. Migração desmontou o handler hover-only mas manteve o link de fallback"
+  ].join(`
+`);
+}
+
 // src/checks/lazy-sections.ts
 var LAZY_URL_PATTERN = /\/(deco\/render|_loader)\b/;
 function lazySectionPresence(ctx) {
@@ -9632,6 +10734,8 @@ var ALL_CHECKS = [
   networkSummaryDelta,
   webVitalsMobile,
   imageLoadingHealth,
+  bannerAspectRatio,
+  cartRevealModeDivergence,
   lazySectionPresence,
   seoDeepAudit,
   cacheCoverage
@@ -10282,7 +11386,8 @@ async function runCommand(rawOpts) {
   const rc = loadParityRc();
   rc.cep = opts.cep || rc.cep;
   const ignore = loadParityIgnore();
-  const preflight = await preflightCheck(opts.prod, opts.cand);
+  const primaryViewport = viewports[0] ?? "mobile";
+  const preflight = await preflightCheck(opts.prod, opts.cand, primaryViewport);
   if (!preflight.ok) {
     console.error(chalk13.red(`
   ✖ pre-flight falhou:`));
@@ -10295,7 +11400,7 @@ async function runCommand(rawOpts) {
   const learned = loadLearned();
   const learnedBefore = JSON.stringify(learned);
   let platform = "custom";
-  const prodHomeHtml = await fetchHomeHtml(opts.prod);
+  const prodHomeHtml = await fetchHomeHtml(opts.prod, primaryViewport);
   if (prodHomeHtml) {
     platform = detectPlatform({ url: opts.prod, html: prodHomeHtml });
     if (platform !== "custom") {
@@ -10309,7 +11414,7 @@ async function runCommand(rawOpts) {
   if (wantsAutoSelectors) {
     const discoverSpinner = ora4("Descobrindo seletores via LLM (analisando home prod)…").start();
     try {
-      const html = prodHomeHtml ?? await fetchHomeHtml(opts.prod);
+      const html = prodHomeHtml ?? await fetchHomeHtml(opts.prod, primaryViewport);
       if (html) {
         const discovered = await discoverSelectorsFromUrl(opts.prod, html, {
           noCache: opts.refreshSelectors === true
@@ -10353,6 +11458,23 @@ async function runCommand(rawOpts) {
   const allPageCaptures = [];
   try {
     browser = await launchBrowser({ headless: true });
+    if (opts.warmup) {
+      const warmupSpinner = ora4("Warmup: bustando cache em prod + cand…").start();
+      const result = await warmupTargets({
+        urls: [opts.prod, opts.cand],
+        viewports,
+        bypassCache: opts.bypassCache !== false
+      });
+      if (result.failed.length === 0) {
+        warmupSpinner.succeed(`Warmup ok — ${result.succeeded}/${result.attempted} workers serviram resposta fresca`);
+      } else if (result.succeeded > 0) {
+        const failureSummary = result.failed.slice(0, 3).map((f) => `${f.viewport}/${hostOf(f.url)} (${f.reason})`).join("; ");
+        warmupSpinner.warn(`Warmup parcial — ${result.succeeded}/${result.attempted} ok; ${result.failed.length} falha(s): ${failureSummary}`);
+      } else {
+        const firstReason = result.failed[0]?.reason ?? "unknown";
+        warmupSpinner.fail(`Warmup falhou — 0/${result.attempted} requests ok. Cache pode estar stale. Primeira falha: ${firstReason}`);
+      }
+    }
     for (const viewport of viewports) {
       for (const side of ["prod", "cand"]) {
         const baseUrl = side === "prod" ? opts.prod : opts.cand;
@@ -10363,7 +11485,8 @@ async function runCommand(rawOpts) {
           viewport,
           harPath,
           tracesDir: paths.tracesDir,
-          cohortCookieValue: "control"
+          cohortCookieValue: "control",
+          noCache: opts.bypassCache
         });
         await installVitalsCollector(ctx);
         for (const flow of flows) {
@@ -10377,27 +11500,16 @@ async function runCommand(rawOpts) {
             outDir: paths.screenshotsDir,
             learned,
             platform,
-            recoveryBudget: 3
+            recoveryBudget: 3,
+            acceptProdQuirks: opts.acceptProdQuirks
           });
           allFlowCaptures.push(cap);
           for (const p of cap.pages)
             allPageCaptures.push(p);
           if (opts.learn !== false) {
-            for (const step of cap.steps ?? []) {
-              if (!step.selectorKey || !step.usedSelector)
-                continue;
-              const key = step.selectorKey;
-              if (step.recoveredByLlm) {
-                promoteFromLlm(learned, platform, key, step.usedSelector, prodHost);
-                promotedCount++;
-              } else if (step.status === "ok") {
-                recordSuccess(learned, platform, key, step.usedSelector, prodHost);
-              } else if (step.status === "failed") {
-                const before = recordFailure(learned, platform, key, step.usedSelector, prodHost);
-                if (before?.deprecated)
-                  deprecatedCount++;
-              }
-            }
+            const result = promoteStepsFromFlow(learned, platform, prodHost, cap);
+            promotedCount += result.promoted;
+            deprecatedCount += result.deprecated;
           }
         }
         await stopTracing(ctx, tracePath).catch(() => {
@@ -10474,7 +11586,7 @@ async function runCommand(rawOpts) {
             const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
             const fullUrl = new URL(task.path, baseUrl).toString();
             try {
-              const ctx = await newContext(browser, { viewport: task.viewport, cohortCookieValue: "control" });
+              const ctx = await newContext(browser, { viewport: task.viewport, cohortCookieValue: "control", noCache: opts.bypassCache });
               await installVitalsCollector(ctx);
               const page = await ctx.newPage();
               try {
@@ -10551,7 +11663,7 @@ async function runCommand(rawOpts) {
             const safePath = task.path.replace(/[/?&=]+/g, "_") || "_root";
             const screenshotPath2 = `${paths.screenshotsDir}/visual-${safePath}-${task.viewport}-${task.side}.png`;
             try {
-              const ctx = await newContext(browser, { viewport: task.viewport, cohortCookieValue: "control" });
+              const ctx = await newContext(browser, { viewport: task.viewport, cohortCookieValue: "control", noCache: opts.bypassCache });
               await installVitalsCollector(ctx);
               const page = await ctx.newPage();
               try {
@@ -10719,9 +11831,10 @@ async function runWithConcurrency3(items, workers, fn) {
     }
   }));
 }
-async function preflightCheck(prodUrl, candUrl) {
+async function preflightCheck(prodUrl, candUrl, viewport) {
   const spinner = ora4("Pre-flight: verificando URLs…").start();
   const errors = [];
+  const ua = userAgentFor(viewport);
   async function probe(label, url) {
     try {
       new URL(url);
@@ -10737,7 +11850,7 @@ async function preflightCheck(prodUrl, candUrl) {
         redirect: "follow",
         signal: controller.signal,
         headers: {
-          "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
+          "User-Agent": ua
         }
       });
       if (res.status >= 500)
@@ -10760,11 +11873,44 @@ async function preflightCheck(prodUrl, candUrl) {
   spinner.succeed("Pre-flight OK");
   return { ok: true, errors: [] };
 }
-async function fetchHomeHtml(url) {
+function addCacheBuster(url) {
+  try {
+    const u = new URL(url);
+    u.searchParams.set("_pcb", String(Date.now()));
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+async function warmupTargets(opts) {
+  const headers = opts.bypassCache ? { "Cache-Control": "no-cache", Pragma: "no-cache" } : {};
+  const jobs = [];
+  for (const url of opts.urls) {
+    for (const viewport of opts.viewports) {
+      const ua = userAgentFor(viewport);
+      const target = addCacheBuster(url);
+      jobs.push(fetch(target, {
+        method: "GET",
+        redirect: "follow",
+        headers: { ...headers, "User-Agent": ua }
+      }).then((res) => res.ok || res.status >= 200 && res.status < 400 ? { ok: true } : { ok: false, url, viewport, reason: `HTTP ${res.status} ${res.statusText}` }).catch((err) => ({
+        ok: false,
+        url,
+        viewport,
+        reason: err.message ?? "fetch failed"
+      })));
+    }
+  }
+  const results = await Promise.all(jobs);
+  const succeeded = results.filter((r) => r.ok).length;
+  const failed = results.filter((r) => !r.ok).map(({ url, viewport, reason }) => ({ url, viewport, reason }));
+  return { attempted: results.length, succeeded, failed };
+}
+async function fetchHomeHtml(url, viewport = "desktop") {
   try {
     const res = await fetch(url, {
       headers: {
-        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+        "User-Agent": userAgentFor(viewport),
         Accept: "text/html,application/xhtml+xml",
         "Accept-Language": "pt-BR,pt;q=0.9,en;q=0.8"
       },
@@ -10824,7 +11970,7 @@ function printSummary4(run, htmlPath, meta) {
 // src/cli.ts
 var program = new Command;
 program.name("parity").description("E2E parity validator for Fresh -> TanStack site migrations").version("0.0.0");
-program.command("run").description("Compare two URLs and produce a parity report").requiredOption("--prod <url>", "Production URL (source of truth, e.g. Fresh site)").requiredOption("--cand <url>", "Candidate URL (migrated site, e.g. TanStack)").option("--preset <name>", "Bundle of defaults: smoke (fast, ~30s, no LLM) | full (deep audit) | ci (CI-tuned)").option("--flows <list>", "Comma-separated flows: homepage,plp,pdp,purchase-journey", "purchase-journey").option("--viewports <list>", "Comma-separated viewports: mobile,desktop", "mobile,desktop").option("--cep <cep>", "CEP for shipping calculation", "01310-100").option("--runs <n>", "Repeat each measurement N times (median)", "1").option("--baseline <name>", "Compare against a saved baseline").option("--output <dir>", "Output directory", "./parity-output").option("--ci", "CI mode: stricter exit codes", false).option("--fail-on <severities>", "Comma-separated severities that cause exit 1", "critical").option("--open", "Open the HTML report after the run completes", false).option("--no-auto-selectors", "Disable LLM-based selector discovery (uses defaults instead)").option("--refresh-selectors", "Bypass selector cache and re-run discovery", false).option("--no-learn", "Don't write to learned-selectors.json (read-only mode)").option("--vitals-pages <n>", "Extra pages from sitemap to crawl for Vitals coverage (default 10)", (v) => Number(v), 10).option("--visual-pages <n>", "Pages to compare visually via LLM (home + sampled PLPs/PDPs from sitemap, default 5)", (v) => Number(v), 5).option("--no-visual-diff", "Skip the visual diff capture pass entirely").action(async (opts) => {
+program.command("run").description("Compare two URLs and produce a parity report").requiredOption("--prod <url>", "Production URL (source of truth, e.g. Fresh site)").requiredOption("--cand <url>", "Candidate URL (migrated site, e.g. TanStack)").option("--preset <name>", "Bundle of defaults: smoke (fast, ~30s, no LLM) | full (deep audit) | ci (CI-tuned)").option("--flows <list>", "Comma-separated flows: homepage,plp,pdp,purchase-journey", "purchase-journey").option("--viewports <list>", "Comma-separated viewports: mobile,desktop", "mobile,desktop").option("--cep <cep>", "CEP for shipping calculation", "01310-100").option("--runs <n>", "Repeat each measurement N times (median)", "1").option("--baseline <name>", "Compare against a saved baseline").option("--output <dir>", "Output directory", "./parity-output").option("--ci", "CI mode: stricter exit codes", false).option("--fail-on <severities>", "Comma-separated severities that cause exit 1", "critical").option("--open", "Open the HTML report after the run completes", false).option("--no-auto-selectors", "Disable LLM-based selector discovery (uses defaults instead)").option("--refresh-selectors", "Bypass selector cache and re-run discovery", false).option("--no-learn", "Don't write to learned-selectors.json (read-only mode)").option("--vitals-pages <n>", "Extra pages from sitemap to crawl for Vitals coverage (default 10)", (v) => Number(v), 10).option("--visual-pages <n>", "Pages to compare visually via LLM (home + sampled PLPs/PDPs from sitemap, default 5)", (v) => Number(v), 5).option("--no-visual-diff", "Skip the visual diff capture pass entirely").option("--bypass-cache", "Bypass CDN/edge caches: append a cache-busting query param and send Cache-Control: no-cache on every request. Use right after a deploy to avoid false failures from stale CF edge content.", false).option("--warmup", "Before measurement, hit each target URL once (per viewport) with a cache-buster so the Worker serves a fresh response. Recommended after deploys.", false).option("--accept-prod-quirks", "Demote prod-side cart-empty journey failures (VTEX session quirk) from failed to skipped. The cart-reveal-mode-divergence check still emits critical if prod/cand markup intents differ, so this flag never masks a real regression. See issue #12.", false).action(async (opts) => {
   const code = await runCommand(opts);
   process.exit(code);
 });
@@ -10853,7 +11999,7 @@ program.command("cache").description("Análise de cache focada em cand. Crawla N
 program.command("vitals").description("Crawleia múltiplas páginas (via sitemap.xml ou --urls) e compara Web Vitals prod vs cand em cada uma. Output HTML com top piores/melhores expandidos.").requiredOption("--prod <url>", "Production URL (base)").requiredOption("--cand <url>", "Candidate URL (base)").option("--urls <list-or-file>", "Comma-separated paths or .txt file (1/line). Overrides sitemap discovery.").option("--limit <n>", "Max pages discovered from sitemap.xml", (v) => Number(v), 20).option("--viewports <list>", "mobile,desktop", "mobile").option("--concurrency <n>", "Parallel workers (1-8)", (v) => Number(v), 4).option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report when done", false).action(async (opts) => {
   process.exit(await vitalsCommand(opts));
 });
-program.command("journey").description("CI-friendly: roda só o purchase-journey (home → PLP → PDP → frete → carrinho → frete carrinho → checkout) e compara prod vs cand step-by-step").requiredOption("--prod <url>", "Production URL").requiredOption("--cand <url>", "Candidate URL").option("--viewports <list>", "mobile,desktop", "mobile").option("--cep <cep>", "CEP for shipping calc", "01310-100").option("--output <dir>", "Output directory for runs/<id>/", "./parity-output").option("--junit <file>", "Write JUnit XML to this path").option("--github", "Emit GitHub Actions annotations (::error, ::warning) for failures").option("--json", "Emit a one-line JSON status object to stdout (machine-readable)").option("--no-report", "Skip writing report.html / report.json").option("--no-auto-selectors", "Skip LLM-based selector discovery").action(async (opts) => {
+program.command("journey").description("CI-friendly: roda só o purchase-journey (home → PLP → PDP → frete → carrinho → frete carrinho → checkout) e compara prod vs cand step-by-step").requiredOption("--prod <url>", "Production URL").requiredOption("--cand <url>", "Candidate URL").option("--viewports <list>", "mobile,desktop", "mobile").option("--cep <cep>", "CEP for shipping calc", "01310-100").option("--output <dir>", "Output directory for runs/<id>/", "./parity-output").option("--junit <file>", "Write JUnit XML to this path").option("--github", "Emit GitHub Actions annotations (::error, ::warning) for failures").option("--json", "Emit a one-line JSON status object to stdout (machine-readable)").option("--no-report", "Skip writing report.html / report.json").option("--no-auto-selectors", "Skip LLM-based selector discovery").option("--accept-prod-quirks", "Demote prod-side cart-empty journey failures (VTEX session quirk) from failed to skipped. The cart-reveal-mode-divergence check still emits critical if prod/cand markup intents differ, so this flag never masks a real regression. See issue #12.", false).action(async (opts) => {
   process.exit(await journeyCommand(opts));
 });
 program.command("prompt").argument("<runId>", "Run ID").description("Generate a Markdown prompt of ranked issues ready to paste into any LLM").option("--output <dir>", "Output directory where runs live", "./parity-output").option("--out <file>", "Write to file instead of stdout").option("--min-severity <sev>", "Only include issues at or above this severity (critical|high|medium|low)", "low").option("--limit <n>", "Cap the number of issues included", (v) => Number(v), 20).action((runId, opts) => {