@unbox-plus/cli 0.20.4

package/template/agents/definitions/05-cart.md

@@ -0,0 +1,116 @@
+# Agente 05 — Cart (Carrinho)
+
+> ⚠️ **Doc de plano (histórico).** A implementação entregue pela foundation difere em nomes e
+> caminhos de arquivo citados abaixo. O mapa REAL de arquivos por área é a tabela "Agentes
+> 00-11" do `agents/MANAGER.md` — em conflito, valem o MANAGER e o código.
+
+## Escopo
+Contexto global do carrinho, drawer lateral, página `/carrinho`, API route server-side e input de cupom.
+
+## Dependências
+- Agente 00 (Scaffold) — `lib/unbox.ts`
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `app/api/cart/route.ts` | Route Handler: create, add, update, remove, get, discount |
+| `components/cart/CartContext.tsx` | Context + Provider + useCart hook (client) |
+| `components/cart/CartDrawer.tsx` | Drawer lateral Base UI Dialog |
+| `components/cart/CartItem.tsx` | Item com imagem, qtd, preço, remover |
+| `components/cart/CartSummary.tsx` | Subtotal, desconto, frete, botão checkout |
+| `components/cart/EmptyCart.tsx` | Estado vazio com CTA para catálogo |
+| `components/cart/DiscountCodeInput.tsx` | Input + aplicar cupom |
+| `app/(loja)/carrinho/page.tsx` | Versão full-page do carrinho |
+
+## Interface do CartContext
+
+```ts
+interface CartContextValue {
+  cartId: string | null
+  cartToken: string | null
+  items: CartLineItem[]
+  totalCount: number        // soma de quantities
+  subtotal: number
+  total: number
+  appliedDiscount?: { code: string; amount: number }
+  isOpen: boolean
+  isLoading: boolean
+  openCart(): void
+  closeCart(): void
+  addItem(params: AddParams): Promise<void>
+  updateQuantity(itemId: string, qty: number): Promise<void>
+  removeItem(itemId: string): Promise<void>
+  applyDiscount(code: string): Promise<{ success: boolean; error?: string }>
+  refreshCart(): Promise<void>
+}
+```
+
+## Persistência de cookies
+
+```ts
+// Browser-side (client component) — cartId e cartToken NÃO são sensíveis
+function saveCartCookies(cartId: string, cartToken: string) {
+  const exp = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toUTCString()
+  document.cookie = `unbox_cart_id=${cartId}; expires=${exp}; path=/; SameSite=Lax`
+  document.cookie = `unbox_cart_token=${cartToken}; expires=${exp}; path=/; SameSite=Lax`
+}
+function readCartCookies() {
+  const get = (n: string) => document.cookie.match(new RegExp(`(?:^|; )${n}=([^;]*)`))?.[1]
+  return { cartId: get("unbox_cart_id") ?? null, cartToken: get("unbox_cart_token") ?? null }
+}
+```
+
+## API Route /api/cart
+
+```ts
+// POST /api/cart — actions: create | add | update | remove | get | discount | clear
+import { getUnboxClient } from "@/lib/unbox"
+
+export async function POST(req: Request) {
+  const client = await getUnboxClient()
+  const body = await req.json()
+
+  switch (body.action) {
+    case "create":
+      return Response.json(await client.createCart({ shopId: client.shopId }))
+    case "add":
+      return Response.json(await client.addCartItems(body.cartId, body.cartToken, [body.item]))
+    case "update":
+      return Response.json(await client.updateCartItem(body.cartId, body.cartToken, body.itemId, body.qty))
+    case "remove":
+      return Response.json(await client.removeCartItem(body.cartId, body.cartToken, body.itemId))
+    case "get":
+      return Response.json(await client.getCart(body.cartId, body.cartToken))
+    case "discount":
+      return Response.json(await client.applyDiscountCode(body.cartId, body.cartToken, body.code))
+    default:
+      return Response.json({ error: "Ação inválida" }, { status: 400 })
+  }
+}
+```
+
+## CartDrawer (Base UI)
+
+```tsx
+import * as Dialog from "@base-ui-components/react/dialog"
+
+<Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Backdrop className="fixed inset-0 bg-black/40" />
+  <Dialog.Popup render={
+    <aside className="fixed inset-y-0 right-0 w-full max-w-md bg-white shadow-2xl flex flex-col" />
+  }>
+    <Dialog.Title>Meu Carrinho ({totalCount})</Dialog.Title>
+    {/* items */}
+    <CartSummary />
+  </Dialog.Popup>
+</Dialog.Root>
+```
+
+## Cupom — regra crítica
+
+```ts
+// discountCodes(first:) recebe ConnectionLimitInt — máximo 20
+// Ao aplicar: mostrar erro via friendlyError() se falhar
+// Erro de cupom inválido: cartEventLabel("COUPON_NOT_APPLICABLE") → "Cupom não aplicável"
+```

package/template/agents/definitions/06-checkout.md

@@ -0,0 +1,146 @@
+# Agente 06 — Checkout (Pagamento)
+
+> ⚠️ **Doc de plano (histórico).** A implementação entregue pela foundation difere em nomes e
+> caminhos de arquivo citados abaixo. O mapa REAL de arquivos por área é a tabela "Agentes
+> 00-11" do `agents/MANAGER.md` — em conflito, valem o MANAGER e o código.
+
+## Escopo
+Fluxo completo de checkout: endereço → cotação de frete → seleção → pagamento (Pix/Cartão) → pedido.
+
+## Dependências
+- Agente 00 (Scaffold)
+- Agente 05 (Cart) — `cartId` e `cartToken` vêm do CartContext
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `app/api/checkout/route.ts` | Route Handler com lock de idempotência por cartId |
+| `app/(loja)/checkout/page.tsx` | Multi-step checkout (client-heavy) |
+| `app/(loja)/pedido/[referenceId]/page.tsx` | Confirmação de pedido |
+| `components/checkout/AddressForm.tsx` | Formulário de endereço |
+| `components/checkout/ShippingSelector.tsx` | Lista de opções de frete |
+| `components/checkout/PaymentSelector.tsx` | Pix ou Cartão |
+| `components/checkout/PixPayment.tsx` | QR code + copia-e-cola + polling |
+| `components/checkout/CreditCardForm.tsx` | Dados do cartão |
+| `components/checkout/OrderSummary.tsx` | Resumo dos itens (sidebar) |
+| `components/checkout/CheckoutProgress.tsx` | Steps: Endereço → Frete → Pagamento |
+
+## Fluxo da API (ordem obrigatória)
+
+```
+1. setShippingAddressOnCart  →  fulfillmentGroupId
+2. updateFulfillmentOptionsForGroup  →  availableFulfillmentOptions[]
+3. (opcional) applyDiscountCodeToCart
+4. selectFulfillmentOptionForGroup  →  total com frete
+5. placeOrder  →  order (Pix QR | resultado cartão)
+```
+
+## device (antifraude/3DS) — OBRIGATÓRIO no placeOrder
+
+Vai no **nível raiz** do `PlaceOrderInput` (irmão de `order` e `payments`), campo único
+com enum `type`:
+
+- `type: "BROWSER"` — 8 campos reais do navegador (colorDepth, javaEnabled, userAgent,
+  language, screenHeight, screenWidth, timezoneOffset), coletados em
+  `components/checkout/checkout-client.tsx` e repassados pelo BFF (`/api/checkout`).
+- `type: "API"` — fallback para pedidos server-side (scripts) — o SDK aplica
+  automaticamente quando `device` é omitido.
+
+`timezoneOffset` em **minutos** (`getTimezoneOffset()`, BRT → 180) — ponto aberto com a
+Unbox se seria em horas; ver `lib/unbox/types.ts`.
+
+## AddressInput — campos obrigatórios
+
+```ts
+// NON_NULL no schema: fullName, phone, postal, address1, city, region, country
+// Validados ao vivo (obrigatórios na prática): taxPayerId, number, neighborhood
+interface AddressInput {
+  fullName: string; taxPayerId: string; postal: string
+  address1: string; number: string; neighborhood: string
+  city: string; region: string; phone: string
+  country?: string    // default "BR"
+  address2?: string
+  isCommercial?: boolean
+}
+```
+
+## Idempotência (CRÍTICO)
+
+```ts
+// Em memória (dev/single-instance) — em prod usar KV/Redis
+const inFlight = new Map<string, true>()
+
+export async function POST(req: Request) {
+  const { action, cartId, cartToken, ...rest } = await req.json()
+
+  if (action === "place") {
+    if (inFlight.has(cartId)) {
+      return Response.json({ error: "pedido_em_andamento" }, { status: 409 })
+    }
+    inFlight.set(cartId, true)
+    try {
+      const result = await doPlaceOrder(cartId, cartToken, rest)
+      return Response.json(result)
+    } finally {
+      inFlight.delete(cartId)
+    }
+  }
+  // ... outros actions
+}
+```
+
+## Pix — polling de status
+
+```tsx
+// Polling a cada 5s até status !== "new" e !== "processing"
+useEffect(() => {
+  if (!orderId || status === "paid") return
+  const id = setInterval(async () => {
+    const res = await fetch(`/api/checkout?orderId=${orderId}`)
+    const { order } = await res.json()
+    if (order.status !== "new" && order.status !== "processing") {
+      setStatus(order.status)
+      clearInterval(id)
+      if (order.status === "paid") router.push(`/pedido/${order.referenceId}`)
+    }
+  }, 5000)
+  return () => clearInterval(id)
+}, [orderId, status])
+```
+
+## Múltiplos grupos de frete
+
+```ts
+// NUNCA assuma fulfillmentGroups[0] apenas
+// Itere todos os grupos:
+for (const group of cart.checkout.fulfillmentGroups) {
+  await updateFulfillmentOptionsForGroup({ cartId, cartToken, fulfillmentGroupId: group._id })
+}
+// Ao selecionar frete, selecionar para CADA grupo
+// No placeOrder, incluir TODOS os grupos
+```
+
+## Página de confirmação (/pedido/[referenceId])
+
+```ts
+// Buscar pedido por referenceId
+// Status: use orderStatusLabel(order.status) — NUNCA displayStatus(language)
+// Rastreio: order.fulfillmentGroups.data[0].tracking.trackingCode (não trackingUrl)
+```
+
+## Submit do formulário — botão único
+
+```tsx
+// Prevenir duplo clique:
+const [submitting, setSubmitting] = useState(false)
+async function handleSubmit() {
+  if (submitting) return
+  setSubmitting(true)
+  try { await placeOrder() }
+  finally { setSubmitting(false) }
+}
+<button disabled={submitting} aria-busy={submitting}>
+  {submitting ? "Processando..." : "Finalizar Pedido"}
+</button>
+```

package/template/agents/definitions/07-auth.md

@@ -0,0 +1,130 @@
+# Agente 07 — Auth (OTP Login)
+
+> ⚠️ **Doc de plano (histórico).** A implementação entregue pela foundation difere em nomes e
+> caminhos de arquivo citados abaixo. O mapa REAL de arquivos por área é a tabela "Agentes
+> 00-11" do `agents/MANAGER.md` — em conflito, valem o MANAGER e o código.
+
+## Escopo
+Login passwordless (OTP por e-mail), gestão de sessão via cookie httpOnly, e proteção de rotas.
+
+## Dependências
+- Agente 00 (Scaffold) — `lib/auth.ts` base
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `app/(loja)/conta/entrar/page.tsx` | Página de login (2 steps: email → código) |
+| `app/api/account/otp/route.ts` | Dispara OTP por e-mail |
+| `app/api/account/signin/route.ts` | Troca código OTP pelo token do cliente |
+| `app/api/account/signout/route.ts` | Limpa cookie e redireciona |
+| `lib/auth.ts` | getCustomerToken / setCustomerToken / clearCustomerToken |
+| `middleware.ts` | Protege /conta/pedidos e /conta/assinaturas |
+| `components/auth/OTPForm.tsx` | Formulário em dois steps |
+
+## lib/auth.ts (completo)
+
+```ts
+import "server-only"
+import { cookies } from "next/headers"
+
+const COOKIE_NAME = "unbox_customer_token"
+const COOKIE_OPTS = {
+  httpOnly: true,
+  secure: process.env.NODE_ENV === "production",
+  sameSite: "lax" as const,
+  path: "/",
+}
+
+export async function getCustomerToken(): Promise<string | undefined> {
+  return (await cookies()).get(COOKIE_NAME)?.value
+}
+
+export async function setCustomerToken(token: string, maxAge = 7 * 24 * 60 * 60) {
+  (await cookies()).set(COOKIE_NAME, token, { ...COOKIE_OPTS, maxAge })
+}
+
+export async function clearCustomerToken() {
+  (await cookies()).delete(COOKIE_NAME)
+}
+```
+
+## /api/auth/otp (POST) — CRÍTICO
+
+```ts
+// ⚠️ Manda e-mail REAL — rate-limit obrigatório
+// Rate-limit simples: Map<email, lastSentAt>
+const rateLimitMap = new Map<string, number>()
+
+export async function POST(req: Request) {
+  const { email } = await req.json()
+
+  // Rate-limit: 1 por minuto por email
+  const last = rateLimitMap.get(email) ?? 0
+  if (Date.now() - last < 60_000) {
+    return Response.json({ error: "Aguarde antes de reenviar o código" }, { status: 429 })
+  }
+  rateLimitMap.set(email, Date.now())
+
+  const client = await getUnboxClient()
+  await client.gql(
+    `mutation($i:CustomerOTPRequestInput!){ customerOTPRequest(input:$i){success} }`,
+    { i: { email, shopId: process.env.UNBOX_SHOP_ID } },
+    { captcha: true }  // ⚠️ obrigatório — SDK envia x-captcha-verification
+  )
+  return Response.json({ success: true })
+}
+```
+
+## /api/auth/signin (POST)
+
+```ts
+export async function POST(req: Request) {
+  const { email, code } = await req.json()
+  const client = await getUnboxClient()
+  const data = await client.gql(
+    `mutation($i:CustomerPasswordlessSignInInput){
+      customerPasswordlessSignIn(input:$i){
+        accessToken firstAccess newShopSignIn
+      }
+    }`,
+    { i: { email, otpCode: code, shopId: process.env.UNBOX_SHOP_ID } },
+    { captcha: true }
+  )
+  await setCustomerToken(data.customerPasswordlessSignIn.accessToken)
+  return Response.json({ success: true, firstAccess: data.customerPasswordlessSignIn.firstAccess })
+}
+```
+
+## middleware.ts
+
+```ts
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(req: NextRequest) {
+  const token = req.cookies.get("unbox_customer_token")?.value
+  if (!token) {
+    const url = req.nextUrl.clone()
+    url.pathname = "/conta/entrar"
+    url.searchParams.set("next", req.nextUrl.pathname)
+    return NextResponse.redirect(url)
+  }
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/conta/pedidos/:path*", "/conta/assinaturas/:path*"],
+}
+```
+
+## OTPForm — UX
+
+```
+Step 1: Campo de email + botão "Enviar código"
+Step 2: Campo de 6 dígitos (autofoco) + botão "Entrar"
+        + botão "Reenviar código" (habilitado após 60s)
+
+Erros: via friendlyError() do lib/feedback.ts
+Após sucesso: redirect para ?next ou /conta/pedidos
+```

package/template/agents/definitions/08-customer.md

@@ -0,0 +1,55 @@
+# Agente 08 — Customer (Área da Conta)
+
+## Escopo
+Área logada do cliente: visão geral, pedidos, assinaturas, endereços e preferências. Tudo
+protegido por sessão via cookie httpOnly (token do **cliente**, distinto do token de loja).
+
+## Dependências
+- Agente 07 (Auth) — `lib/session.ts` (`getCustomerToken`), fluxo de login OTP
+- Agente 00 (Scaffold) — `lib/unbox/customer.ts` (`UnboxCustomerClient`)
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `app/(loja)/conta/page.tsx` | Visão geral (resumo de pedidos/assinaturas recentes) |
+| `app/(loja)/conta/pedidos/page.tsx` + `[referenceId]/page.tsx` | Lista e detalhe de pedidos |
+| `app/(loja)/conta/assinaturas/page.tsx` + `[referenceId]/page.tsx` | Lista e detalhe de assinaturas (pausar/cancelar/pular ciclo) |
+| `app/(loja)/conta/enderecos/page.tsx` | CRUD de endereços salvos |
+| `app/(loja)/conta/preferencias/page.tsx` | Preferências de marketing/notificação |
+| `components/account/account-shell.tsx` | Shell com sidebar de navegação + breadcrumb, usado por todas as páginas acima |
+| `components/account/address-book.tsx` | Lista + formulário de endereços |
+| `components/account/preferences-form.tsx` | Formulário de preferências |
+| `components/account/subscription-actions.tsx` | Ações de assinatura (pausar/cancelar/pular) |
+| `components/account/reorder-button.tsx` | "Comprar novamente" a partir de um pedido |
+| `components/account/signout-button.tsx` | Logout |
+| `lib/customer-session.ts` | `getCustomerClient()` / `requireCustomerClient()` — client autenticado com o token do cliente |
+| `app/api/account/{me,addresses,preferences,signout}/route.ts` | Route Handlers que usam `requireCustomerClient()` |
+
+## Regra de ouro — dois tokens
+`lib/customer-session.ts` usa o token do **cliente** (cookie httpOnly, setado pelo Agente 07),
+nunca o `serverEnv.apiKey`/token de loja do Agente 00 (`lib/unbox/store.ts`). Misturar os dois
+client factories é o erro mais comum nessa área — sempre confirme qual client está sendo importado.
+
+```ts
+// Server Component de página protegida:
+const client = await getCustomerClient();
+if (!client) redirect("/conta/entrar?next=/conta/pedidos");
+```
+
+## Proteção de rotas
+Páginas sob `/conta/*` (exceto `/conta/entrar`) checam `getCustomerClient()` e redirecionam para
+`/conta/entrar?next=<rota>` se não houver sessão — sem `middleware.ts` global, a checagem é feita
+em cada `page.tsx` (Server Component) para poder usar `AccountShell` mesmo no estado deslogado de
+algumas páginas públicas (ex.: rastreio de pedido pelo `/pedido/[referenceId]` não exige login).
+
+## Assinaturas — ações sensíveis
+`subscription-actions.tsx` chama mutations que alteram cobrança recorrente (pausar/cancelar/pular
+ciclo) — sempre exigir confirmação explícita (dialog) antes de disparar, e mostrar o novo estado
+otimisticamente só após resposta 200 da API.
+
+## Link de recuperação e frequência de assinatura
+`recurringItemsFrequencyId` é um campo do pedido (`placeOrder`), não do carrinho, e por isso
+vive em cookie no meio do caminho — ao restaurar um carrinho de assinatura por link (`?id=&token=`, doc 05-cart), é
+obrigatório também repassar `&freq=` (ver `app/api/cart/link/route.ts`), senão o cliente reabre o
+checkout sem frequência selecionada e não consegue finalizar.

package/template/agents/definitions/09-promotions.md

@@ -0,0 +1,62 @@
+# Agente 09 — Promotions (Kits & Combos)
+
+## Escopo
+Sistema de kits/combos promocionais — bundles curados de produtos com desconto, resolvidos
+dinamicamente contra o catálogo real da loja (preço e estoque nunca são hardcoded).
+
+## Dependências
+- Agente 03 (Catalog) — usa o mesmo catálogo (`getCatalog`) e `lib/enrichment` para indexar produtos
+- Agente 02 (Homepage) — consome `<CombosSection>`/`<CombosHome>` na home
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `lib/enrichment/combos.ts` | Define `COMBOS` (specs do kit) e `resolveCombos()` (resolve contra o catálogo) |
+| `components/home/combos-section.tsx` | Seção completa da home: carrossel + CTA "Adicionar combo ao carrinho" |
+| `components/home/combos-home.tsx` | Wrapper que busca o catálogo e chama `resolveCombos()` |
+| `components/home/combo-card-compact.tsx` | Card compacto reusado em outros pontos (ex.: cross-sell) |
+
+## ⚠️ Estado no template base: vazio por padrão
+`COMBOS: ComboDef[] = []` — a infraestrutura está pronta e testada, mas **sem nenhum kit
+configurado**. Sem isso, `<CombosSection>` não renderiza nada (degrada graciosamente, não é erro),
+mas a loja não tem essa alavanca de AOV até alguém preencher `COMBOS` com kits reais.
+
+## Modelo de dados
+Um `ComboDef` referencia **famílias de produto** (`familyCode` do `lib/enrichment/products.json`),
+não SKUs fixos — a resolução escolhe o produto comprável mais barato (ou mais caro, via
+`size: "max"`) daquela família no catálogo atual:
+
+```ts
+// lib/enrichment/combos.ts — popule com os kits reais da loja
+export const COMBOS: ComboDef[] = [
+  {
+    id: "kit-essencial",
+    name: "Kit Essencial",
+    description: "Tudo o que você precisa para começar.",
+    imageUrl: "/brand/combos/kit-essencial.webp",
+    badge: "MAIS VENDIDO",
+    discountPct: 15,
+    highlights: [{ icon: "sparkle", label: "3 itens" }],
+    items: [{ family: "FAMILIA_A" }, { family: "FAMILIA_B" }, { family: "FAMILIA_C", size: "min" }],
+  },
+];
+```
+
+## Regra de ouro — nunca hardcode preço
+`resolveCombos()` calcula `subtotal`/`total`/`save` a partir do preço real do catálogo
+(`resolveProductPrice`) multiplicado por `(1 - discountPct/100)` — **o componente nunca recebe
+preço fixo**. Um combo cujos itens não resolvem no catálogo atual (produto fora de linha, sem
+estoque) é descartado silenciosamente (`items.length < 2` → `continue`), nunca quebra a home.
+
+## Ao configurar pra uma loja nova
+1. Popular `lib/enrichment/products.json` à mão, no formato de `lib/enrichment/index.ts` (não há script gerador)
+2. Definir `familyCode` para os grupos de produto que formarão kits
+3. Preencher `COMBOS` em `combos.ts` com os kits desejados (`items`, `discountPct`, `highlights`)
+4. Adicionar as imagens temáticas em `public/brand/combos/`
+
+## Fora de escopo aqui — não confundir com CRO
+Banners de oferta genéricos ("shopSales" da loja), contadores de urgência e prova social **não**
+são deste agente — isso é escopo do Agente 13 (CRO Package), que hoje só tem o módulo de frete
+grátis (`FREE_SHIPPING_THRESHOLD`) implementado; os outros 9 módulos ainda não existem no template
+base.

package/template/agents/definitions/10-feedback.md

@@ -0,0 +1,128 @@
+# Agente 10 — Feedback / UX
+
+> ⚠️ **Doc de plano (histórico).** A implementação entregue pela foundation difere em nomes e
+> caminhos de arquivo citados abaixo. O mapa REAL de arquivos por área é a tabela "Agentes
+> 00-11" do `agents/MANAGER.md` — em conflito, valem o MANAGER e o código.
+
+## Escopo
+Padrões de UX compartilhados: toasts, skeletons, estados de loading, error boundaries e páginas
+especiais (error.tsx, not-found.tsx).
+
+## Dependências
+- Agente 00 (Scaffold) — `lib/feedback.ts` base
+- Reutilizado por todos os outros agentes
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `components/ui/Toast.tsx` | Componente de toast |
+| `components/ui/ToastProvider.tsx` | Provider global com useToast hook |
+| `components/ui/skeleton.tsx` | Skeleton polimórfico com animate-pulse |
+| `components/ui/LoadingSpinner.tsx` | Spinner SVG com aria-label |
+| `components/ui/ErrorBoundary.tsx` | Client error boundary |
+| `components/ui/EmptyState.tsx` | Estado vazio genérico |
+| `app/error.tsx` | Erro global (client component obrigatório) |
+| `app/not-found.tsx` | 404 |
+| `app/loading.tsx` | Fallback de Suspense global |
+| `lib/feedback.ts` | Re-exports + mapa de erros de pagamento |
+
+## lib/feedback.ts (completo)
+
+```ts
+export { friendlyError, cartEventLabel, ERROR_MESSAGES, CART_EVENT_LABELS } from "@payflows/unbox-sdk"
+
+export const CHECKOUT_STEPS = {
+  address: "Endereço",
+  shipping: "Frete",
+  payment: "Pagamento",
+  confirmation: "Confirmação",
+} as const
+
+export function getPaymentErrorMessage(code: string): string {
+  const map: Record<string, string> = {
+    INSUFFICIENT_FUNDS_ERROR: "Cartão sem limite disponível",
+    CARD_DECLINED: "Cartão recusado pela operadora",
+    INVALID_CARD: "Dados do cartão inválidos",
+    EXPIRED_CARD: "Cartão expirado",
+    PAYMENT_PROCESSING_ERROR: "Erro ao processar pagamento. Tente novamente.",
+  }
+  return map[code] ?? "Erro no pagamento. Tente outro cartão ou método de pagamento."
+}
+```
+
+## ToastProvider + useToast
+
+```tsx
+// Não depender de Radix/shadcn toast — usar Base UI ou implementação própria
+type ToastType = "success" | "error" | "info" | "warning"
+interface ToastItem { id: string; title: string; description?: string; type: ToastType }
+
+const ToastContext = createContext<{
+  toast(params: Omit<ToastItem, "id">): void
+  dismiss(id: string): void
+}>()
+
+export function useToast() { return useContext(ToastContext) }
+
+// Toast com auto-dismiss em 5s, acessível com role="status" aria-live="polite"
+```
+
+## Skeleton — uso
+
+```tsx
+// Genérico (polimórfico):
+<Skeleton className="h-4 w-32" />           // linha de texto
+<Skeleton className="aspect-square w-full" /> // imagem
+
+// Compostos:
+export function ProductCardSkeleton() {
+  return (
+    <div>
+      <Skeleton className="aspect-square w-full rounded-lg" />
+      <Skeleton className="mt-2 h-4 w-3/4" />
+      <Skeleton className="mt-1 h-4 w-1/2" />
+    </div>
+  )
+}
+export function ProductGridSkeleton({ count = 8 }: { count?: number }) {
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
+      {Array.from({ length: count }).map((_, i) => <ProductCardSkeleton key={i} />)}
+    </div>
+  )
+}
+```
+
+## app/error.tsx (CRÍTICO)
+
+```tsx
+"use client"  // ← obrigatório pelo Next.js
+import { useEffect } from "react"
+
+export default function Error({ error, reset }: { error: Error & { digest?: string }; reset(): void }) {
+  useEffect(() => {
+    // Log interno — nunca exibir ao usuário
+    console.error("[Error Boundary]", error.message)
+  }, [error])
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4">
+      <h2>Algo deu errado</h2>
+      <p>Ocorreu um erro inesperado. Tente novamente.</p>
+      <button onClick={reset}>Tentar novamente</button>
+    </div>
+  )
+}
+```
+
+## Acessibilidade — checklist obrigatório
+
+```
+- aria-live="polite" nos toasts (não "assertive" para não interromper)
+- aria-busy="true" em botões durante loading
+- role="status" em mensagens de feedback
+- Não remover outline/foco visível (apenas customizar cor)
+- Focus trap em drawers e dialogs (Base UI já cuida)
+- Skip link: <a href="#main-content" className="sr-only focus:not-sr-only">Pular para conteúdo</a>
+```