@decocms/parity 0.4.0 → 0.5.4

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
@@ -302,7 +286,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([])
 });
@@ -4469,6 +4459,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 +4488,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 +4501,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 +4522,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 +4539,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 +4553,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 +4979,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 +5179,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 +5277,7 @@ function isResolutionContext(v) {
 }
 
 // src/engine/flows.ts
-var PURCHASE_JOURNEY_TOTAL_STEPS = 8;
+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 +5287,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 +5329,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 +5366,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 +5374,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 +5482,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 +5492,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 +5516,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 +5547,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 +5584,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 +5598,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,115 +5612,211 @@ 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 page.screenshot({ path: spBefore4, fullPage: false }).catch(() => {
+      return;
+    });
+    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 page.screenshot({ path: sp4, fullPage: false }).catch(() => {
+      return;
+    });
+    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(() => {
+      const t5 = Date.now();
+      const beforeUrl5 = page.url();
+      const spBefore5 = screenshotPath(ctx, "pj-5-shipping-pdp-before");
+      await page.screenshot({ path: spBefore5, fullPage: false }).catch(() => {
         return;
       });
       const ok = await fillCep(page, cepInputPdp, ctx.rc.cep);
-      const sp = screenshotPath(ctx, "pj-4-shipping-pdp");
+      const sp = screenshotPath(ctx, "pj-5-shipping-pdp");
       await page.screenshot({ path: sp, fullPage: false }).catch(() => {
         return;
       });
-      const step4Status = ok ? "ok" : "failed";
+      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(() => {
+    const t6 = Date.now();
+    const beforeUrl6 = page.url();
+    const spBefore6 = screenshotPath(ctx, "pj-6-add-cart-before");
+    await page.screenshot({ path: spBefore6, fullPage: false }).catch(() => {
       return;
     });
+    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(() => {
+    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 page.screenshot({ path: sp6, fullPage: false }).catch(() => {
       return;
     });
+    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
+      recoveredByLlm: buyRecovered || undefined,
+      note: validation.status === "ok" ? undefined : validation.note,
+      detail: { signal: validation.signal, errorText: validation.errorText, variantRetry: variantRetryNote }
     });
-    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(() => {
+    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 page.screenshot({ path: spBefore7, fullPage: false }).catch(() => {
       return;
     });
     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";
@@ -5585,281 +5829,235 @@ async function flowPurchaseJourney(ctx) {
       const alreadyOpen = await isCartRevealed(page, expectedProductTitle);
       if (alreadyOpen) {
         cartOpenMethod = "already-open";
-        dlog2(ctx, `step 6 open-minicart: no trigger, but drawer already visible (matched ${alreadyOpen})`);
+        dlog2(ctx, `step 7 open-minicart: no trigger, drawer already visible (${alreadyOpen})`);
       }
     }
-    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");
+      dlog2(ctx, `step 7 open-minicart: validation → found=${v.found} (${v.method})${reasonText ? ` — ${reasonText.slice(0, 80)}` : ""}`);
     }
-    const sp6 = screenshotPath(ctx, "pj-6-minicart");
-    await page.screenshot({ path: sp6, fullPage: false }).catch(() => {
+    const sp7 = screenshotPath(ctx, "pj-7-minicart");
+    await page.screenshot({ path: sp7, fullPage: false }).catch(() => {
       return;
     });
-    const step6Status = cartOpenMethod === "failed" ? "failed" : step6Validation && !step6Validation.found ? "failed" : "ok";
+    const step7Status = cartOpenMethod === "failed" ? "failed" : step7Validation && !step7Validation.found ? "failed" : "ok";
     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",
+      cartValidation: step7Validation,
+      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);
+    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(() => {
+      const t8 = Date.now();
+      const beforeUrl8 = page.url();
+      const spBefore8 = screenshotPath(ctx, "pj-8-shipping-cart-before");
+      await page.screenshot({ path: spBefore8, fullPage: false }).catch(() => {
         return;
       });
       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(() => {
+      const sp8 = screenshotPath(ctx, "pj-8-shipping-cart");
+      await page.screenshot({ path: sp8, fullPage: false }).catch(() => {
         return;
       });
-      const step7Status = ok ? "ok" : "failed";
+      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 page.screenshot({ path: sp9early, fullPage: false }).catch(() => {
+        return;
+      });
+      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 page.screenshot({ path: spBefore9, fullPage: false }).catch(() => {
+      return;
+    });
+    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 page.screenshot({ path: sp9, fullPage: false }).catch(() => {
+      return;
+    });
+    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 +6077,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 +6129,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 +6154,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,6 +6173,360 @@ async function fillCep(page, selector, cep) {
     return false;
   }
 }
+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 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;
+  });
+  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"
+  ];
+  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,
@@ -6246,7 +6779,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 +6878,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 +6907,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 +7016,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 +7086,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 +7142,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 +7226,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 +7263,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",
@@ -6814,6 +7397,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 +7787,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";
@@ -8489,6 +9112,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",
@@ -10383,21 +11007,9 @@ async function runCommand(rawOpts) {
           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(() => {