@unbox-plus/cli 0.20.4

package/template/scripts/contraste.js

@@ -0,0 +1,177 @@
+/**
+ * contraste.js — mede contraste REAL no navegador, e classifica a paleta da marca.
+ *
+ * Cole no console do DevTools com a loja aberta, ou rode via CDP. Duas funções:
+ *
+ *   contraste()            varre o texto visível da página e lista o que reprova
+ *   classificar("F20A64")  diz se a cor é SUPERFÍCIE (pode ter texto em cima) ou ACENTO
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * OS TRÊS ERROS QUE ESTA VERSÃO NÃO COMETE
+ * A mesma ferramenta foi escrita errada três vezes numa loja, sempre respondendo com
+ * confiança. Os três estão tratados aqui, e cada um está comentado no ponto onde importa:
+ *
+ *   1. `getComputedStyle().color` NÃO é sempre rgb(). Com qualquer opacidade (e o Tailwind v4
+ *      gera isso em todo `text-cor/60`) o navegador devolve `oklab(...)`. Parser de rgb()
+ *      silenciosamente lê 0,0,0 e reprova texto claro sem motivo.
+ *   2. Fundo não é a camada mais próxima. Véu semitransparente empilhado muda a cor efetiva:
+ *      é preciso COMPOR todas as camadas até achar uma opaca.
+ *   3. Alpha entra UMA vez só, na composição sobre o fundo. Medido neste navegador: o
+ *      ImageData do canvas 2D é NÃO pré-multiplicado (`rgba(255,255,255,.5)` volta
+ *      [255,255,255,128]), então "desfazer a pré-multiplicação" dividindo por alpha é o erro,
+ *      não a correção — numa cor fora do sRGB isso estoura a faixa. Aplicar o alpha duas vezes,
+ *      de qualquer um dos dois jeitos, reprova texto claro sobre escuro e APROVA texto escuro
+ *      sobre claro que na verdade falha.
+ *
+ * E duas coisas que a ferramenta NÃO resolve, ditas aqui para ninguém confiar demais:
+ *   • texto sobre foto: é preciso amostrar os pixels da imagem sob o texto e compor o véu por
+ *     cima. Aqui isso é sinalizado como "sobre imagem: medir à mão", nunca aprovado no escuro.
+ *   • captura de tela: esqueleto de carregamento e imagem não pintada já enganaram a leitura.
+ *     Conclusão tirada de screenshot precisa ser confirmada no DOM.
+ */
+
+/** Converte QUALQUER cor que o navegador devolva em [r,g,b,a] 0-255. */
+function corParaRgba(valor) {
+  if (!valor || valor === "transparent") return [0, 0, 0, 0];
+  // Hex direto, sem canvas: é o formato que a paleta da marca usa, e assim `classificar()`
+  // também roda fora do navegador (Node, script de build) sem depender de DOM.
+  const h = String(valor).trim();
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(h)) {
+    const p = h.slice(1);
+    const par = p.length <= 4 ? p.split("").map((c) => c + c) : p.match(/../g);
+    const [r, g, b, a] = par.map((x) => parseInt(x, 16));
+    return [r, g, b, a === undefined ? 1 : a / 255];
+  }
+  // (1) oklab/oklch/color(): o navegador devolve isso sempre que há opacidade. Em vez de
+  // escrever um parser de espaço de cor, deixamos o próprio navegador converter, pintando
+  // 1px num canvas — o resultado volta em RGBA de verdade.
+  if (!/^rgba?\(/.test(valor)) {
+    const c = document.createElement("canvas");
+    c.width = c.height = 1;
+    const ctx = c.getContext("2d", { willReadFrequently: true });
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = valor;
+    ctx.fillRect(0, 0, 1, 1);
+    const d = ctx.getImageData(0, 0, 1, 1).data;
+    // (3) O ImageData do canvas 2D é NÃO pré-multiplicado: `rgba(255,255,255,.5)` volta como
+    // [255,255,255,128], não [128,128,128,128] (medido neste navegador, não suposto). Ou seja,
+    // os canais já são a cor pura e dividir por alpha é o erro, não a correção: numa cor fora
+    // do sRGB isso estourava a faixa (um oklch deu R=404). O alpha entra uma vez só, na
+    // composição sobre o fundo.
+    return [d[0], d[1], d[2], d[3] / 255];
+  }
+  const n = valor.match(/[\d.]+/g).map(Number);
+  return [n[0], n[1], n[2], n[3] === undefined ? 1 : n[3]];
+}
+
+/** Compõe `frente` (com alpha) sobre `fundo` (opaco). */
+function compor([r, g, b, a], [R, G, B]) {
+  return [r * a + R * (1 - a), g * a + G * (1 - a), b * a + B * (1 - a), 1];
+}
+
+function luminancia([r, g, b]) {
+  const f = (v) => {
+    v /= 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+
+function razao(corA, corB) {
+  const [L1, L2] = [luminancia(corA), luminancia(corB)].sort((x, y) => y - x);
+  return (L1 + 0.05) / (L2 + 0.05);
+}
+
+/** Fundo efetivo de um elemento: sobe a árvore COMPONDO cada camada até achar uma opaca. */
+function fundoEfetivo(el) {
+  const camadas = [];
+  let n = el;
+  let sobreImagem = false;
+  while (n && n !== document.documentElement.parentNode) {
+    const s = getComputedStyle(n);
+    if (s.backgroundImage && s.backgroundImage !== "none") sobreImagem = true;
+    const c = corParaRgba(s.backgroundColor);
+    if (c[3] > 0) {
+      camadas.push(c);
+      // (2) só paramos numa camada OPACA: véu translúcido continua subindo, porque a cor
+      // efetiva depende de tudo o que está atrás dele.
+      if (c[3] === 1) break;
+    }
+    n = n.parentElement;
+  }
+  let fundo = [255, 255, 255, 1]; // o branco do papel, só se nada opaco apareceu
+  for (const c of camadas.reverse()) fundo = compor(c, fundo);
+  return { fundo, sobreImagem };
+}
+
+const MIN_GRANDE = 3.0; // >=24px, ou >=18.66px em negrito
+const MIN_NORMAL = 4.5;
+
+/** Varre o texto visível e devolve o que reprova. */
+function contraste({ apenasFalhas = true } = {}) {
+  const saida = [];
+  for (const el of document.querySelectorAll("body *")) {
+    const texto = [...el.childNodes].filter((n) => n.nodeType === 3 && n.textContent.trim()).map((n) => n.textContent.trim()).join(" ");
+    if (!texto) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || r.height === 0) continue;
+    const s = getComputedStyle(el);
+    if (s.visibility === "hidden" || s.display === "none" || Number(s.opacity) === 0) continue;
+
+    const { fundo, sobreImagem } = fundoEfetivo(el);
+    const frente = compor(corParaRgba(s.color), fundo);
+    const px = parseFloat(s.fontSize);
+    const grande = px >= 24 || (px >= 18.66 && Number(s.fontWeight) >= 700);
+    const minimo = grande ? MIN_GRANDE : MIN_NORMAL;
+    const valor = razao(frente, fundo);
+    const passa = valor >= minimo;
+    if (apenasFalhas && passa && !sobreImagem) continue;
+    saida.push({
+      texto: texto.slice(0, 60),
+      razao: Number(valor.toFixed(2)),
+      minimo,
+      passa,
+      // Texto sobre foto NÃO é aprovado por esta conta: o fundo real são os pixels da imagem.
+      aviso: sobreImagem ? "sobre imagem: medir à mão (amostrar os pixels sob o texto)" : undefined,
+      seletor: el.tagName.toLowerCase() + (el.className && typeof el.className === "string" ? "." + el.className.split(/\s+/).slice(0, 2).join(".") : ""),
+    });
+  }
+  console.table(saida);
+  return saida;
+}
+
+/**
+ * Classifica uma cor da marca. É o uso principal: define se a cor pode receber texto.
+ *   superfície = passa contra tinta OU contra branco (>=4.5) → pode ser fundo de texto
+ *   acento     = não passa em nenhum → contorno, ícone, faixa. NUNCA fundo de texto.
+ *
+ * O CLI não "corrige" cor de marca sozinho para passar no WCAG: isso descaracteriza a marca.
+ * Ele mede, aplica o que a marca pediu, e escreve o número ao lado do token com a alternativa.
+ */
+function classificar(hex, { tinta = "#18181B", claro = "#FFFFFF" } = {}) {
+  const c = corParaRgba(hex);
+  const contraTinta = razao(c, corParaRgba(tinta));
+  const contraClaro = razao(c, corParaRgba(claro));
+  const papel = Math.max(contraTinta, contraClaro) >= 4.5 ? "superfície" : "acento";
+  const r = {
+    cor: hex,
+    contraTinta: Number(contraTinta.toFixed(2)),
+    contraBranco: Number(contraClaro.toFixed(2)),
+    papel,
+    textoPorCima: papel === "superfície" ? (contraTinta > contraClaro ? "tinta" : "branco") : "NENHUM",
+    recomendacao:
+      papel === "superfície"
+        ? `use como fundo com texto ${contraTinta > contraClaro ? "escuro" : "branco"} por cima`
+        : "contorno, sombra, ícone ou faixa decorativa. Para usar como fundo de texto, gere a versão funda (-deep) e ponha branco em cima",
+  };
+  console.log(`${hex}: ${papel} (tinta ${r.contraTinta} · branco ${r.contraBranco}) — ${r.recomendacao}`);
+  return r;
+}
+
+// Sem `export`: o arquivo é feito para ser COLADO NO CONSOLE do DevTools, e `export` quebra
+// isso com "Unexpected token". No navegador as funções ficam em window; em Node, no module.
+if (typeof window !== "undefined") {
+  Object.assign(window, { contraste, classificar, razao });
+  console.log("contraste.js pronto: contraste() varre a página · classificar('#HEX') define o papel da cor");
+}
+if (typeof module !== "undefined") module.exports = { contraste, classificar, razao };

package/template/scripts/dump-catalog.ts

@@ -0,0 +1,95 @@
+// Raio-X da loja real: imprime promoções (shopSales), cupons, política de assinatura,
+// formas de pagamento e catálogo, direto do backend Unbox. Use ANTES de preencher
+// lib/store-config.ts — a regra de ouro da loja é só prometer o que aparece aqui.
+//
+//   npm run unbox:dump
+import "./load-env"; // SEMPRE o primeiro import — parser de env idêntico ao do app
+import { UnboxClient } from "../lib/unbox/client";
+
+const client = new UnboxClient({
+  apiKey: process.env.UNBOX_API_KEY ?? "",
+  shopId: process.env.UNBOX_SHOP_ID ?? "",
+  partnerApiKey: process.env.UNBOX_PARTNER_API_KEY,
+  partnerGqlUrl: process.env.UNBOX_PARTNER_GRAPHQL_URL,
+  captchaBypass: process.env.UNBOX_CAPTCHA_BYPASS,
+});
+
+const brl = (n: number) => `R$${n.toFixed(2).replace(".", ",")}`;
+const h = (title: string) => console.log(`\n═══ ${title} ═══`);
+
+async function main() {
+  await client.signIn(process.env.UNBOX_USER!, process.env.UNBOX_PASS!);
+  const shop = await client.getShop(process.env.UNBOX_SHOP_SLUG ?? "");
+
+  h("LOJA");
+  console.log(`${shop.name} (slug: ${shop.slug}, id: ${shop._id})`);
+  console.log(`Pagamentos: cartão ${shop.acceptsCreditCard ? "sim" : "não"} · boleto ${shop.acceptsBoleto ? "sim" : "não"}`);
+
+  h("PROMOÇÕES AUTOMÁTICAS (shopSales)");
+  const sales: any[] = shop.shopSales ?? [];
+  if (!sales.length) console.log("Nenhuma. NÃO exiba desconto, brinde ou régua de frete na loja.");
+  for (const s of sales) {
+    console.log(`• ${s.label ?? s.code ?? s._id} [${s.calculation?.__typename ?? "?"}] ${s.enabled ? "ATIVA" : "desativada"}`);
+    for (const t of s.calculation?.tiers ?? []) {
+      console.log(`    a partir de ${brl(t.cartSubtotalGTE)} → brinde: ${t.catalogProductVariant?.title ?? t.catalogProductVariant?._id}`);
+    }
+  }
+  const tierSale = sales.find((s) => s.enabled && s.calculation?.__typename === "CalculationFreeItemByTier");
+  if (tierSale?.calculation?.tiers?.length) {
+    console.log(`  → GIFT_TIERS sugerido p/ lib/store-config.ts:`);
+    console.log(`    ${JSON.stringify(tierSale.calculation.tiers.map((t: any) => ({ name: t.catalogProductVariant?.title ?? "Brinde", threshold: t.cartSubtotalGTE })))}`);
+  }
+  if (sales.some((s) => s.enabled && s.calculation?.__typename === "CalculationDiscountByPaymentMethod")) {
+    console.log(`  → Existe desconto por forma de pagamento: confirme o percentual no painel e preencha PIX_DISCOUNT_PCT.`);
+  } else {
+    console.log(`  → Sem CalculationDiscountByPaymentMethod: mantenha PIX_DISCOUNT_PCT = 0.`);
+  }
+
+  h("CUPONS (discountCodes)");
+  try {
+    const codes = await client.listDiscountCodes(50);
+    if (!codes.nodes?.length) console.log("Nenhum cupom cadastrado.");
+    for (const c of codes.nodes ?? []) {
+      console.log(`• ${c.code ?? c.label} [${c.calculation?.__typename ?? "?"}] ${c.enabled ? "ativo" : "inativo"}`);
+    }
+  } catch (e: any) {
+    console.log(`(indisponível: ${e.message})`);
+  }
+
+  h("ASSINATURA (recurringOrdersPolicy)");
+  const pol = shop.recurringOrdersPolicy;
+  if (!pol?.enabled) {
+    console.log("Desabilitada. NÃO exiba oferta de assinatura.");
+  } else {
+    const pp = pol.pricingPolicy;
+    console.log(`Habilitada. Desconto de assinante: ${pp ? `${pp.value}${pp.type === "PERCENTAGE_OFF" ? "%" : ""} (${pp.type})` : "nenhum"}`);
+    for (const f of pol.allowedFrequencies ?? []) console.log(`  • ${f.title} (${f._id})`);
+  }
+
+  h("FORMAS DE PAGAMENTO");
+  try {
+    // Consulta direto no core com o _id que acabamos de buscar (o shopId do .env é opcional).
+    const d = await client.gql<{ availablePaymentMethods: any[] }>(
+      `query($s:ID!){availablePaymentMethods(shopId:$s){name displayName isEnabled}}`, { s: shop._id },
+    );
+    for (const m of d.availablePaymentMethods) console.log(`• ${m.displayName ?? m.name} ${m.isEnabled ? "" : "(desabilitada)"}`);
+  } catch (e: any) {
+    console.log(`(indisponível: ${e.message})`);
+  }
+
+  h("CATÁLOGO (até 50 itens)");
+  const cat = await client.getCatalog({ first: 50 });
+  console.log(`Total na loja: ${cat.totalCount}`);
+  for (const n of cat.nodes ?? []) {
+    const p: any = (n as any).product ?? n;
+    if (!p?.title) continue;
+    const flags = [p.isVisible === false && "OCULTO", p.isSoldOut && "ESGOTADO"].filter(Boolean).join(" ");
+    const price = p.pricing?.[0]?.displayPrice ?? p.variants?.[0]?.pricing?.[0]?.displayPrice ?? "sem preço";
+    console.log(`• ${p.title} — ${price} · ${p.variants?.length ?? 0} variação(ões) ${flags}`.trim());
+  }
+
+  console.log(`\nRegra de ouro: lib/store-config.ts só recebe o que apareceu acima.`);
+  console.log(`O que não está aqui não existe no backend e não pode ser prometido na loja.`);
+}
+
+main().catch((e) => { console.error(`Falha no dump: ${e.message}`); process.exit(1); });

package/template/scripts/load-env.ts

@@ -0,0 +1,13 @@
+// Carrega .env.local/.env com o MESMO parser do Next (@next/env).
+//
+// Por que não `tsx --env-file=.env.local`? O parser do Node e o do Next divergem no
+// escaping de valores com `#`, `$` e aspas — a mesma senha funcionava no `next dev` e
+// falhava no `npm run unbox:test` (ou vice-versa). Importando este módulo PRIMEIRO em
+// todo script, o valor que o script enxerga é idêntico ao que o app enxerga.
+//
+// Regra prática pro .env.local: valores com caracteres especiais (#, $, &, *, espaço)
+// sempre entre aspas duplas — ex.: UNBOX_PASS="#minhaSenha$123".
+import path from "node:path";
+import { loadEnvConfig } from "@next/env";
+
+loadEnvConfig(path.join(import.meta.dirname, ".."));

package/template/scripts/medir-sistema.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Roda os medidores de sistema visual (sistema.py e vocabulario.py) em MODO RELATÓRIO:
+// imprime e sai 0, sempre. Ainda não é gate.
+//
+// Por que relatório e não gate: os tetos dos scripts (8 tamanhos de tipo, 5 raios, 0 hex solto)
+// vieram de uma medição só. Medido aqui contra cinco lojas geradas e contra a própria foundation,
+// TODAS estouram, a foundation inclusive: ligar como gate hoje reprovaria o build de todo mundo,
+// inclusive de um scaffold recém-criado que ninguém tocou. A régua se escolhe depois de ver a
+// distribuição, e é isso que este comando serve para acumular.
+//
+// Python: os medidores são .py. Onde não houver python3 (imagem de build enxuta), este wrapper
+// AVISA e segue. Um medidor que não rodou não pode derrubar deploy de loja.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RAIZ = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MEDIDORES = [
+  { arquivo: "sistema.py", args: [], titulo: "Orçamento de sistema visual" },
+  { arquivo: "vocabulario.py", args: [], titulo: "Cobertura do vocabulário gráfico" },
+];
+
+function acharPython() {
+  for (const cmd of ["python3", "python"]) {
+    const r = spawnSync(cmd, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) return cmd;
+  }
+  return null;
+}
+
+const python = acharPython();
+if (!python) {
+  console.log("\nℹ️  medição de sistema visual pulada: python3 não encontrado nesta máquina.");
+  console.log("   Os medidores são opcionais e não bloqueiam o build. Para rodar localmente:");
+  console.log("   npm run unbox:sistema   ·   npm run unbox:vocabulario\n");
+  process.exit(0);
+}
+
+for (const { arquivo, args, titulo } of MEDIDORES) {
+  const script = path.join(RAIZ, "scripts", arquivo);
+  if (!fs.existsSync(script)) continue;
+  console.log(`\n── ${titulo} (relatório, não bloqueia) ──`);
+  const r = spawnSync(python, [script, RAIZ, ...args], { encoding: "utf8" });
+  if (r.stdout) process.stdout.write(r.stdout);
+  if (r.status === 2) {
+    // 2 é "o gate não rodou". Em modo relatório isso não derruba nada, mas precisa APARECER:
+    // medidor que varre o vazio e diz "limpo" aprova sem ter olhado.
+    process.stdout.write(r.stderr || "");
+    console.log("   (o medidor não rodou: o resultado acima não vale como aprovação)");
+  } else if (r.stderr) {
+    process.stdout.write(r.stderr);
+  }
+}
+console.log("\n   Números acima são linha de base, não reprovação. Régua ainda não definida.\n");
+process.exit(0);

package/template/scripts/place-order-pix.ts

@@ -0,0 +1,61 @@
+// ⚠️ EFEITO REAL: cria um pedido PENDING via Pix na loja de produção (gera QR; NÃO cobra até o pagamento).
+// Exige o argumento --confirm para evitar execução acidental.
+//
+//   npm run unbox:order:pix -- --confirm
+import "./load-env"; // SEMPRE o primeiro import — parser de env idêntico ao do app
+import { UnboxClient } from "../lib/unbox/client";
+
+if (!process.argv.includes("--confirm")) {
+  console.error("Recusado. Isto cria um pedido REAL (Pix PENDING). Rode com: npm run unbox:order:pix -- --confirm");
+  process.exit(1);
+}
+
+const ADDR = {
+  fullName: "Cliente Teste", taxPayerId: "08383142951", postal: "04551-080",
+  address1: "Rua São Tomé", number: "73", neighborhood: "Vila Olímpia",
+  city: "São Paulo", region: "SP", phone: "11999990000",
+};
+
+(async () => {
+  const client = new UnboxClient({
+    apiKey: process.env.UNBOX_API_KEY ?? "",
+    shopId: process.env.UNBOX_SHOP_ID!,
+    // API de parceiros: presente = signIn e leituras compativeis roteiam pra ela
+    partnerApiKey: process.env.UNBOX_PARTNER_API_KEY,
+    partnerGqlUrl: process.env.UNBOX_PARTNER_GRAPHQL_URL,
+    captchaBypass: process.env.UNBOX_CAPTCHA_BYPASS,
+  });
+  await client.signIn(process.env.UNBOX_USER!, process.env.UNBOX_PASS!);
+
+  const cat = await client.getCatalog({ first: 20 });
+  const picked = (cat.nodes as any[]).map((n) => n.product).find((p) => !p.isSoldOut && p.variants?.[0]?.pricing?.[0]?.price);
+  if (!picked) throw new Error("nenhum produto vendável encontrado");
+  const v = picked.variants[0];
+  console.log(`Produto: ${picked.title} @ ${v.pricing[0].displayPrice}`);
+
+  const cart = await client.createCart([{ productId: picked.productId, productVariantId: v._id, price: v.pricing[0].price, quantity: 1 }]);
+  const fgId = await client.setShippingAddress(cart.cartId, cart.cartToken, ADDR as any);
+  const opts = await client.quoteShipping(cart.cartId, cart.cartToken, fgId);
+  const finalCart = await client.selectShipping(cart.cartId, cart.cartToken, fgId, opts[0].fulfillmentMethod._id);
+
+  const order = await client.placeOrder({
+    cartId: cart.cartId,
+    email: process.env.UNBOX_TEST_EMAIL ?? "teste@example.com",
+    address: ADDR as any,
+    fulfillmentMethodId: opts[0].fulfillmentMethod._id,
+    total: finalCart.checkout.summary.total.amount,
+    items: client.buildOrderItems(finalCart),
+    payment: { type: "pix" },
+    // antifraude: pedido originado no servidor (sem navegador) → device API no ROOT.
+    // Se a Unbox aceitar (pedido criado), o root placement do device está confirmado.
+    device: { type: "API" },
+  });
+
+  const o = order.orders[0];
+  console.log(`✅ Pedido criado: #${o.referenceId} (status ${o.status})`);
+  const qr = o.payments?.find((p: any) => p?.data?.qrCode)?.data?.qrCode;
+  console.log(qr ? `QR Pix (copia-e-cola):\n${qr}` : "sem QR retornado");
+})().catch((e) => {
+  console.error("❌", e.message);
+  process.exit(1);
+});

package/template/scripts/qa-screenshots.mjs

@@ -0,0 +1,150 @@
+// ═══════════════════════════════════════════════════════════════════════════════════════
+// CAPTURA DE TELA DO QA VISUAL — npm run unbox:qa
+//
+// POR QUE ESTE SCRIPT EXISTE, e por que NÃO use `chrome --screenshot --window-size=390,844`:
+//
+// No macOS o Chrome trava a largura mínima da janela. Pedindo 390 de largura, o PNG SAI
+// com 390 — e é por isso que ninguém percebe — mas a página renderizou a 500. Medido nesta
+// máquina, nos dois modos headless:
+//
+//     --window-size=390,844  →  window.innerWidth = 500
+//
+// Ou seja: o "mobile" do QA era o layout de 500px reduzido. Metade da revisão visual de
+// toda loja aprovava uma tela que nenhum usuário vê.
+//
+// A emulação de dispositivo do CDP (Emulation.setDeviceMetricsOverride) é independente do
+// tamanho da janela e devolve 390x844 dpr=2 de verdade, com user agent e eventos de toque
+// de celular. Sem dependência nova: Node 22+ tem WebSocket e fetch nativos.
+// ═══════════════════════════════════════════════════════════════════════════════════════
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const BASE = process.env.QA_BASE ?? "http://localhost:3000";
+const OUT = process.env.QA_OUT ?? "qa";
+const PORTA = 9333;
+
+// Orçamento de frames — ver agents/definitions/16-qa-visual.md. O que pega defeito é dobra,
+// transição entre seções e extremos, não o meio de um bloco. Cobrir "toda região" custa 70+
+// frames por rodada e a maioria mostra o que a anterior já mostrou.
+const PLANO = [
+  { nome: "home",      url: "/",          frames: 4 },
+  { nome: "catalogo",  url: "/produtos",  frames: 1 },
+  { nome: "carrinho",  url: "/carrinho",  frames: 1 },
+  { nome: "checkout",  url: "/checkout",  frames: 1 },
+  // PDP: o script não sabe o slug; passe QA_PDP=/produto/<slug> (2 frames: dobra + conteúdo).
+  ...(process.env.QA_PDP ? [{ nome: "pdp", url: process.env.QA_PDP, frames: 2 }] : []),
+];
+
+const PERFIS = [
+  { nome: "1440", width: 1440, height: 900, dpr: 1, mobile: false },
+  { nome: "390",  width: 390,  height: 844, dpr: 2, mobile: true  },
+];
+
+function acharChrome() {
+  const cands = [
+    process.env.CHROME_PATH,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser",
+  ].filter(Boolean);
+  const achado = cands.find((c) => { try { return fs.existsSync(c); } catch { return false; } });
+  if (!achado) {
+    console.error("✗ Chrome não encontrado. Instale o Google Chrome ou aponte CHROME_PATH=/caminho/do/chrome");
+    process.exit(1);
+  }
+  return achado;
+}
+
+async function conectar(chrome) {
+  const perfil = path.join(process.env.TMPDIR ?? "/tmp", `unbox-qa-${process.pid}`);
+  const proc = spawn(chrome, [
+    "--headless=new", "--disable-gpu", "--hide-scrollbars",
+    `--remote-debugging-port=${PORTA}`, `--user-data-dir=${perfil}`,
+    "--no-first-run", "--no-default-browser-check", "about:blank",
+  ], { stdio: "ignore" });
+
+  let alvos = null;
+  for (let i = 0; i < 60; i++) {
+    try { alvos = await (await fetch(`http://127.0.0.1:${PORTA}/json/list`)).json(); break; }
+    catch { await new Promise((r) => setTimeout(r, 250)); }
+  }
+  if (!alvos) { proc.kill(); throw new Error("Chrome não abriu a porta de depuração"); }
+
+  const alvo = alvos.find((t) => t.type === "page");
+  const ws = new WebSocket(alvo.webSocketDebuggerUrl);
+  const pend = new Map();
+  let id = 0;
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pend.has(m.id)) { pend.get(m.id)(m); pend.delete(m.id); }
+  };
+  await new Promise((r, rej) => { ws.onopen = r; ws.onerror = rej; });
+
+  const cdp = (method, params = {}) => new Promise((res, rej) => {
+    const i = ++id;
+    pend.set(i, (m) => (m.error ? rej(new Error(`${method}: ${m.error.message}`)) : res(m.result)));
+    ws.send(JSON.stringify({ id: i, method, params }));
+  });
+  return { cdp, fechar: () => { ws.close(); proc.kill(); fs.rmSync(perfil, { recursive: true, force: true }); } };
+}
+
+const esperar = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  fs.mkdirSync(OUT, { recursive: true });
+  const { cdp, fechar } = await conectar(acharChrome());
+  let n = 0;
+  const avisos = [];
+
+  try {
+    await cdp("Page.enable");
+    for (const perfil of PERFIS) {
+      await cdp("Emulation.setDeviceMetricsOverride", {
+        width: perfil.width, height: perfil.height,
+        deviceScaleFactor: perfil.dpr, mobile: perfil.mobile,
+      });
+      // Confere que a emulação PEGOU. Sem esta checagem o script poderia repetir em
+      // silêncio exatamente o bug que ele existe para corrigir.
+      for (const alvoPagina of PLANO) {
+        await cdp("Page.navigate", { url: BASE + alvoPagina.url });
+        await esperar(1400);
+
+        const { result: larg } = await cdp("Runtime.evaluate", { expression: "window.innerWidth" });
+        if (larg.value !== perfil.width) {
+          avisos.push(`${alvoPagina.nome}@${perfil.nome}: viewport renderizou ${larg.value}px, não ${perfil.width}px`);
+        }
+
+        const { result: alt } = await cdp("Runtime.evaluate", {
+          expression: "Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)",
+        });
+        const total = Math.max(alt.value ?? perfil.height, perfil.height);
+        const passos = alvoPagina.frames;
+        // Distribui os frames pela página: dobra, transições e o fim (rodapé).
+        const max = Math.max(0, total - perfil.height);
+
+        for (let i = 0; i < passos; i++) {
+          const y = passos === 1 ? 0 : Math.round((max * i) / (passos - 1));
+          await cdp("Runtime.evaluate", { expression: `window.scrollTo(0, ${y})` });
+          await esperar(450);
+          const { data } = await cdp("Page.captureScreenshot", { format: "png" });
+          const arq = path.join(OUT, `${alvoPagina.nome}-${perfil.nome}-${i}.png`);
+          fs.writeFileSync(arq, Buffer.from(data, "base64"));
+          n++;
+        }
+        process.stdout.write(`  ✓ ${alvoPagina.nome} @ ${perfil.nome}px — ${passos} frame(s)\n`);
+      }
+    }
+  } finally {
+    fechar();
+  }
+
+  console.log(`\n${n} frames em ${OUT}/`);
+  if (avisos.length) {
+    console.log("\n⚠ Emulação divergiu do pedido — NÃO avalie estes frames como mobile:");
+    for (const a of avisos) console.log(`   • ${a}`);
+    process.exit(1);
+  }
+}
+
+main().catch((e) => { console.error("✗", e.message); process.exit(1); });