@beworke/pixel 0.1.0-rc.5 → 0.1.0-rc.7

package/docs/public/README.md

@@ -0,0 +1,77 @@
+# Pixel v2 — Documentação pública (RC)
+
+Documentação para desenvolvedores que implementam funis e páginas com `@beworke/pixel`.
+
+**Versão de referência:** `0.1.0-rc.6` · **Etapas concluídas:** 1–20
+
+> Esta pasta é a documentação **pública**. Arquitetura interna, prompts de etapas e relatórios de engenharia ficam em `PLAN_PIXEL/` (`ARCHITECTURE.md`, `PIXEL_V2_*`).
+
+## Onde ler (importante)
+
+| Contexto | URL / caminho |
+|----------|----------------|
+| **GitHub (browser)** | https://github.com/techionext/Pixel-Global/tree/main/packages/pixel/docs/public |
+| **Pacote npm instalado** | `node_modules/@beworke/pixel/docs/public/` |
+| **npmjs.com** | Só renderiza o `README.md` do pacote — **não** abre `.md` individuais |
+
+Instalação: `npm install @beworke/pixel@rc` (público, sem token).
+
+## Começar
+
+| Guia | Descrição |
+|------|-----------|
+| [Instalação](./getting-started/installation.md) | npm, tarball local, validação do pacote |
+| [Quick start](./getting-started/quick-start.md) | Primeiro `init` em ESM/CJS |
+| [Script tag (IIFE)](./getting-started/script-tag.md) | `@beworke/pixel/global` → `window.PixelV2` |
+| [React / Next.js](./getting-started/react-nextjs.md) | Padrão `useEffect` + hooks locais |
+
+## Referência
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [API — Pixel](./api/pixel.md) | Métodos públicos estáveis |
+| [Package exports](./api/exports.md) | Subpaths do `package.json` |
+| [Catálogo de eventos](./events/catalog.md) | Tipos `PixelEvent` por categoria |
+| [Configuração — visão geral](./configuration/overview.md) | `PixelConfig` e defaults |
+| [Módulos](./configuration/modules.md) | `modules.core`, `behavior`, `conversion`, etc. |
+| [Commerce (root)](./configuration/commerce.md) | `commerce.catalog`, `cart`, `enrichment` |
+
+## Funis
+
+| Página | Guia |
+|--------|------|
+| Landing | [guides/funnel-landing.md](./guides/funnel-landing.md) |
+| Checkout | [guides/funnel-checkout.md](./guides/funnel-checkout.md) |
+| Upsell | [guides/funnel-upsell.md](./guides/funnel-upsell.md) |
+| Downsell | [guides/funnel-downsell.md](./guides/funnel-downsell.md) |
+| Thank-you | [guides/funnel-thank-you.md](./guides/funnel-thank-you.md) |
+| Funil completo | [guides/funnel-full.md](./guides/funnel-full.md) |
+
+## Exemplos públicos
+
+Exemplos em `apps/playground-html/public/` usam **somente API pública** (sem `getDebugServices`, sem hooks de debug).
+
+| Exemplo | Caminho no monorepo |
+|---------|---------------------|
+| Landing (HTML) | `apps/playground-html/public/html/landing.html` |
+| Checkout (HTML) | `apps/playground-html/public/html/checkout.html` |
+| Next.js (App Router) | `apps/playground-next/` (hooks locais, não exportados pelo SDK) |
+
+Playgrounds internos de engenharia: `apps/playground-html/` (podem usar APIs `@internal`).
+
+> **Legado:** na estrutura anterior ao monorepo, estes caminhos eram `examples/public/`, `examples/nextjs/` e `examples/html-script/`.
+
+## Privacidade e limitações
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [Privacidade e consentimento](./privacy/limitations.md) | RC sem CMP completo; responsabilidade da aplicação |
+| [Limitações conhecidas do RC](./limitations.md) | O que não está pronto para produção pública |
+| [Troubleshooting](./troubleshooting.md) | Erros comuns |
+
+## Release Candidate
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [Validação do pacote](./release-candidate/validation.md) | `pack:pixel`, smoke, checklist |
+| [RELEASE_CANDIDATE.md](../../RELEASE_CANDIDATE.md) | Notas oficiais do RC |

package/docs/public/api/exports.md

@@ -0,0 +1,47 @@
+# Package exports
+
+Auditado contra `package.json` do RC `0.1.0-rc.5`.
+
+## Entry principal
+
+| Subpath | Import | Conteúdo principal |
+|---------|--------|-------------------|
+| `@beworke/pixel` | ESM / CJS | `Pixel`, `DEFAULT_PIXEL_CONFIG`, `PixelConfig`, `PixelDebugSnapshot`, `resolveStorageAdapterName` |
+| `@beworke/pixel/v2` | ESM / CJS | Alias do entry principal (mesmos exports) |
+
+## Global (IIFE)
+
+| Subpath | Formato | Global |
+|---------|---------|--------|
+| `@beworke/pixel/global` | IIFE | `window.PixelV2` |
+
+Arquivo build: `dist/v2/global.global.js`
+
+## Subpaths avançados
+
+Úteis para tipos, eventos ou integrações custom — **não** necessários para funis básicos.
+
+| Subpath | Uso típico |
+|---------|------------|
+| `@beworke/pixel/config` | Tipos e helpers de config |
+| `@beworke/pixel/events` | Tipos `PixelEvent`, payloads de conversão |
+| `@beworke/pixel/runtime` | Runtime interno (uso avançado) |
+| `@beworke/pixel/services` | Serviços compartilhados |
+| `@beworke/pixel/logger` | Logger do SDK |
+
+## Não exportado
+
+| Subpath | Status |
+|---------|--------|
+| `@beworke/pixel/diagnostics` | **Não existe** no `package.json` RC |
+
+`PixelDebugSnapshot` é exportado pelo entry principal, não por subpath separado.
+
+## Validar tarball
+
+```bash
+npm pack --dry-run
+npm run validate:rc-package
+```
+
+Arquivos publicados (`files`): `dist/`, `README.md`, `CHANGELOG.md`, `RELEASE_CANDIDATE.md`.

package/docs/public/api/pixel.md

@@ -0,0 +1,65 @@
+# API — classe `Pixel`
+
+Superfície pública estável do RC `0.1.0-rc.5`. Métodos marcados `@internal` no código **não** fazem parte desta referência.
+
+## Construtor
+
+```typescript
+import { Pixel, type PixelConfig } from '@beworke/pixel';
+
+const pixel = new Pixel(config);
+```
+
+## Ciclo de vida
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `init()` | `Promise<void>` | Inicializa runtime, módulos e emite `PAGE_VIEW` quando core habilitado |
+| `destroy()` | `Promise<void>` | Remove listeners, flush parcial e marca snapshot como destruído |
+| `isInitialized()` | `boolean` | `true` após `init()` concluir com sucesso |
+
+## Diagnóstico (público)
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `getDebugSnapshot()` | `Readonly<PixelDebugSnapshot>` | Snapshot read-only sanitizado; seguro antes/depois de init e após destroy |
+
+Use em desenvolvimento para validar sessão, fila de transport e módulos. Não substitui observabilidade de produção.
+
+## Conversão (manual)
+
+Todos retornam `void`. Dados opcionais enriquecem payload; commerce config pode calcular `value`/`items`.
+
+| Método | Dados | Evento emitido |
+|--------|-------|----------------|
+| `purchase(data?)` | `PurchaseData` | `PURCHASE` |
+| `lead(data)` | `LeadData` (obrigatório) | `LEAD` |
+| `addToCart(data?)` | `AddToCartData` | `ADD_TO_CART` |
+| `removeFromCart(data?)` | `RemoveFromCartData` | `REMOVE_FROM_CART` |
+| `initiateCheckout(data?)` | `InitiateCheckoutData` | `INITIATE_CHECKOUT` |
+| `addPaymentInfo(data?)` | `AddPaymentInfoEvent` | `ADD_PAYMENT_INFO` |
+| `viewContent(data?)` | `ViewContentData` | `VIEW_CONTENT` |
+| `search(data)` | `SearchData` (obrigatório) | `SEARCH` |
+
+Tipos de dados: importe de `@beworke/pixel/events` se necessário.
+
+## Exports relacionados (entry principal)
+
+| Export | Uso |
+|--------|-----|
+| `DEFAULT_PIXEL_CONFIG` | Defaults auditados — base para merge |
+| `PixelConfig` | Tipo da configuração |
+| `PixelDebugSnapshot` | Tipo do snapshot |
+| `resolveStorageAdapterName` | Resolve nome do adapter de persistência |
+
+## Não usar em produção / exemplos públicos
+
+Estes existem no código para playgrounds internos:
+
+- `getDebugServices()`
+- `debugPublishBehaviorSignal()`
+- `flushBehaviorBuffer()`
+- `simulateTransport*`, `manualTransportReplay`, etc.
+- `getDebugDedupeKeys`, `getDebugIntegrationState`, …
+
+Veja `apps/playground-html/` apenas para engenharia interna.

package/docs/public/configuration/commerce.md

@@ -0,0 +1,44 @@
+# Commerce (`commerce`)
+
+Configuração root-level (não dentro de `modules`).
+
+## Campos principais
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` (via shared default) | Habilita enrichment commerce |
+| `currency` | conforme `DEFAULT_COMMERCE_CONFIG` | Moeda padrão |
+| `catalog.products` | `[]` | Produtos da oferta (main, bump, upsell) |
+| `cart.mode` | `'custom'` | Carrinho gerenciado pelo app |
+| `cart.allowDynamicItems` | `true` | Itens dinâmicos no carrinho |
+| `cart.calculateValueFrom` | `'cart'` | Cálculo de `value` |
+| `mappings` | `{}` | Mapeamento de atributos/campos |
+| `enrichment` | defaults | Enriquece payloads de conversão |
+
+## Quando usar
+
+- **Checkout:** catálogo com produto principal + order bumps
+- **Upsell/downsell:** produtos adicionais no `catalog`; dispare `viewContent` / `purchase` manualmente
+- **Thank-you:** `purchase` com `transactionId` do pedido
+
+## Exemplo (checkout)
+
+```typescript
+commerce: {
+  enabled: true,
+  currency: 'BRL',
+  catalog: {
+    products: [
+      { id: 'main', name: 'Oferta', type: 'main', price: 197, currency: 'BRL', quantity: 1 },
+    ],
+  },
+  cart: {
+    mode: 'custom',
+    initialItems: [],
+    allowDynamicItems: true,
+    calculateValueFrom: 'cart',
+  },
+},
+```
+
+Referência completa: `apps/playground-next/lib/pixel-config.ts`.

package/docs/public/configuration/modules.md

@@ -0,0 +1,66 @@
+# Módulos (`modules.*`)
+
+Referência resumida auditada contra `DEFAULT_PIXEL_CONFIG`.
+
+## `modules.core`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `true` | Módulo core ativo |
+| `pageView.enabled` | `true` | Emite `PAGE_VIEW` |
+| `pageView.trackInitialPageView` | `true` | No `init()` |
+| `pageView.spa` | `true` | Suporte SPA |
+| `visitor.enabled` | `true` | Gera/persiste visitor |
+| `session.enabled` | `true` | Sessão com TTL 3h |
+| `consent.enabled` | `false` | Gate de consentimento **off** no default |
+
+**Quando usar:** sempre em páginas web. Desligue apenas em testes headless sem DOM.
+
+## `modules.behavior`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | Behavior off por default |
+| `trackers.scroll/click/...` | `enabled: false` | Habilitar por tracker |
+| `heartbeat.enabled` | `false` | `BEHAVIOR_HEARTBEAT` |
+| `engagement.enabled` | `false` | Score + `ENGAGEMENT_*` |
+| `rateLimit/buffer/stateMachine/sessionSummary` | `enabled: false` | Runtime intelligence (Etapa 20) |
+
+**Quando usar:** landing e páginas de conteúdo para scroll, cliques, engagement.
+
+**Limitação RC:** muitos sub-recursos exigem config explícita; defaults conservadores.
+
+## `modules.conversion`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | Flag do módulo |
+| `manual.*` | `enabled: false` | Wrappers manuais internos |
+| `auto.enabled` | `false` | AutoTrack off |
+| `rules.enabled` | `false` | Regras por seletor/URL |
+
+**Quando usar:** habilite `auto` + detectors para AutoTrack; ou use API `pixel.purchase()` etc. sem auto.
+
+## `modules.transport`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | **Deve ser `true` + `sender.mode: 'api'` para API real** |
+| `sender.mode` | `'mock'` | RC local usa mock até configurar API |
+| `batch.enabled` | `true` | Agrupa envios |
+| `retry`, `circuitBreaker`, `offline` | habilitados | Resiliência |
+
+**Quando usar:** produção/staging com `transport.apiEndpoint` e `sender.mode: 'api'`.
+
+## `modules.integrations`
+
+Destinos browser (GA, Meta, etc.) — ver defaults em `@beworke/pixel/config`. Off por default no RC de funil API-first.
+
+## `modules.privacy`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | Módulo privacy off |
+| `consent.enabled` | `false` | Sem CMP integrado |
+
+**Limitação RC:** consentimento completo previsto para Etapa 25. Ver [privacidade](../privacy/limitations.md).

package/docs/public/configuration/overview.md

@@ -0,0 +1,66 @@
+# Configuração — visão geral
+
+`PixelConfig` é o objeto passado ao construtor `new Pixel(config)`.
+
+Use `DEFAULT_PIXEL_CONFIG` como base e sobrescreva apenas o necessário.
+
+## Top-level
+
+| Seção | Descrição |
+|-------|-----------|
+| `app` | Ambiente, debug, source/target |
+| `identity` | `pixelId`, IDs de funil, visitor, user |
+| `transport` | API endpoint, batch, timeout, retry |
+| `storage` | Prefixo, namespace, fila, persistência |
+| `attribution` | UTM, cookies, persistência de atribuição |
+| `commerce` | Catálogo, carrinho, enrichment |
+| `modules` | Feature flags por módulo |
+
+## Defaults críticos (`DEFAULT_PIXEL_CONFIG`)
+
+| Campo | Default | Nota |
+|-------|---------|------|
+| `app.environment` | `'production'` | Use `'development'` + `debug: true` localmente |
+| `app.debug` | `false` | |
+| `identity.pixelId` | `''` | **Obrigatório** em produção |
+| `transport.apiEndpoint` | `''` | **Obrigatório** para enviar eventos |
+| `transport.timeoutMs` | `10000` | |
+| `storage.prefix` | `'__gmk'` | |
+| `storage.namespace` | `'pixel'` | |
+| `storage.queue.enabled` | `true` | |
+| `storage.queue.persistence` | `'memory'` | |
+| `commerce.cart.mode` | `'custom'` | |
+| `modules.core.enabled` | ver [modules](./modules.md) | Emite `PAGE_VIEW` |
+| `modules.behavior.enabled` | `false` | Trackers off por default |
+| `modules.conversion.enabled` | `false` | Manual API ainda funciona quando módulo registrado |
+| `modules.transport.enabled` | ver modules | |
+| `modules.privacy.enabled` | ver modules | Sem CMP completo no RC |
+
+## Persistência recomendada (funis)
+
+```typescript
+storage: {
+  ...DEFAULT_PIXEL_CONFIG.storage,
+  persistence: {
+    visitor: 'localStorage',
+    session: 'sessionStorage',
+    attribution: 'localStorage',
+  },
+},
+```
+
+Sem `persistence.session`, a sessão usa `memory` e some em reload/destroy React.
+
+## Identity para funis
+
+Campos úteis em `identity`:
+
+- `pixelId` — ID do pixel na API
+- `funnelId`, `funnelStepId` — etapa do funil
+- `pageId`, `offerId`, `checkoutId`
+- `visitorId`, `userId` — opcionais se gerenciados pelo backend
+
+## Próximo
+
+- [Módulos](./modules.md)
+- [Commerce](./commerce.md)

package/docs/public/events/catalog.md

@@ -0,0 +1,65 @@
+# Catálogo de eventos
+
+Fonte: union `PixelEvent` (`src/events/types.ts`) — **24 tipos** no RC.
+
+Todos os eventos listados abaixo passam pelo pipeline de transport quando `modules.transport.enabled` e `transport.apiEndpoint` estão configurados.
+
+> `ApiEventType` (HTTP) inclui tipos legados/históricos que **não** fazem parte de `PixelEvent`. Use esta tabela como catálogo público.
+
+## Core
+
+| Tipo | Disparo | Transport |
+|------|---------|-----------|
+| `PAGE_VIEW` | Automático no `init()` (core habilitado) | Sim |
+
+## Session
+
+| Tipo | Disparo | Transport |
+|------|---------|-----------|
+| `SESSION_RENEWED` | Renovação de sessão | Sim |
+| `SESSION_EXPIRED` | Expiração de sessão | Sim |
+
+## Behavior
+
+Requer `modules.behavior.enabled` e trackers/config correspondentes.
+
+| Tipo | Disparo típico | Transport |
+|------|----------------|-----------|
+| `SCROLL` | Thresholds de scroll | Sim |
+| `PAGE_CLICK` | Clique na página | Sim |
+| `RAGE_CLICK` | Cliques repetidos (rage detector) | Sim |
+| `VISIBILITY_CHANGE` | Tab hidden/visible | Sim |
+| `USER_IDLE` | Usuário inativo | Sim |
+| `USER_ACTIVE` | Retorno da inatividade | Sim |
+| `EXIT_INTENT` | Intenção de saída | Sim |
+| `BEHAVIOR_HEARTBEAT` | Intervalo configurado | Sim |
+| `VIEWPORT_ENTER` | Elemento entra no viewport | Sim |
+| `VIEWPORT_EXIT` | Elemento sai do viewport | Sim |
+| `ENGAGEMENT_UPDATE` | Score de engagement muda | Sim |
+| `ENGAGEMENT_SUMMARY` | Resumo (ex.: destroy) | Sim |
+| `BEHAVIOR_SESSION_SUMMARY` | Resumo agregado da sessão (Etapa 20) | Sim |
+
+## Conversion
+
+Disparados por métodos públicos `pixel.*` ou auto-detectors quando habilitados.
+
+| Tipo | API manual | Transport |
+|------|------------|-----------|
+| `PURCHASE` | `purchase()` | Sim |
+| `LEAD` | `lead()` | Sim |
+| `ADD_TO_CART` | `addToCart()` | Sim |
+| `REMOVE_FROM_CART` | `removeFromCart()` | Sim |
+| `INITIATE_CHECKOUT` | `initiateCheckout()` | Sim |
+| `ADD_PAYMENT_INFO` | `addPaymentInfo()` | Sim |
+| `VIEW_CONTENT` | `viewContent()` | Sim |
+| `SEARCH` | `search()` | Sim |
+
+## Eventos inexistentes (RC)
+
+Não há tipos dedicados `UPSELL_*` ou `DOWNSELL_*`. Use `VIEW_CONTENT`, `PAGE_VIEW` e conversões commerce (`PURCHASE`, etc.) conforme [guias de funil](../guides/funnel-upsell.md).
+
+## Importar tipos
+
+```typescript
+import type { PixelEvent, PurchaseEvent } from '@beworke/pixel/events';
+```

package/docs/public/getting-started/installation.md

@@ -0,0 +1,78 @@
+# Instalação
+
+## Requisitos
+
+- Node.js 18+ (para npm/ESM)
+- Navegador moderno (Chrome, Firefox, Safari, Edge)
+
+## npm (registry — recomendado para o time)
+
+Pacote **público** — **não precisa de token** nem login npm para instalar:
+
+```bash
+npm install @beworke/pixel@rc
+```
+
+Versão fixa:
+
+```bash
+npm install @beworke/pixel@0.1.0-rc.6
+```
+
+Confirme a versão instalada:
+
+```bash
+node -e "console.log(require('@beworke/pixel/package.json').version)"
+```
+
+> Evite `npm install @beworke/pixel` sem tag até a tag `latest` apontar para a RC atual. Use `@rc` ou `@0.1.0-rc.6`.
+
+## Onde ler a documentação
+
+| Contexto | Caminho |
+|----------|---------|
+| **Browser (GitHub)** | https://github.com/techionext/Pixel-Global/tree/main/packages/pixel/docs/public |
+| **Após npm install** | `node_modules/@beworke/pixel/docs/public/` |
+
+O site **npmjs.com não abre** arquivos `.md` individuais (ex.: `npmjs.com/package/@beworke/docs/...` → 404). Isso é normal.
+
+## Tarball local (opcional)
+
+```bash
+npm install ./beworke-pixel-0.1.0-rc.6.tgz
+```
+
+## Validar instalação limpa
+
+Na raiz do monorepo:
+
+```bash
+pnpm pack:pixel
+pnpm validate:pixel-package
+```
+
+O tarball fica em `artifacts/` (não use `pnpm --filter @beworke/pixel pack` como fluxo principal).
+
+## Imports recomendados
+
+```typescript
+import { Pixel, DEFAULT_PIXEL_CONFIG, type PixelConfig } from '@beworke/pixel';
+```
+
+Subpaths adicionais: [Package exports](../api/exports.md).
+
+## CDN / script tag
+
+```html
+<script src="https://unpkg.com/@beworke/pixel@rc/dist/v2/global.global.js"></script>
+<script>
+  const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
+</script>
+```
+
+Detalhes: [Script tag](./script-tag.md).
+
+## O que não instalar
+
+- Não importe de `src/` — use apenas exports do pacote publicados no tarball.
+- Não dependa de `./diagnostics` — não é subpath público no `package.json` RC.

package/docs/public/getting-started/quick-start.md

@@ -0,0 +1,77 @@
+# Quick start
+
+## 1. Config mínima
+
+```typescript
+import { Pixel, DEFAULT_PIXEL_CONFIG } from '@beworke/pixel';
+
+const pixel = new Pixel({
+  ...DEFAULT_PIXEL_CONFIG,
+  identity: {
+    pixelId: 'pix_YOUR_ID',
+  },
+  transport: {
+    ...DEFAULT_PIXEL_CONFIG.transport,
+    apiEndpoint: 'https://your-pixel-api.example.com',
+  },
+  storage: {
+    ...DEFAULT_PIXEL_CONFIG.storage,
+    persistence: {
+      visitor: 'localStorage',
+      session: 'sessionStorage',
+      attribution: 'localStorage',
+    },
+  },
+});
+```
+
+## 2. Inicializar
+
+```typescript
+await pixel.init();
+```
+
+`init()` é assíncrono. Aguarde antes de disparar conversões manuais se depender de sessão/visitor prontos.
+
+## 3. Eventos automáticos
+
+Com `modules.core.enabled` e `modules.behavior.enabled` (defaults), após `init()`:
+
+- `PAGE_VIEW` (core)
+- Sinais de behavior (scroll, cliques, heartbeat, etc.) conforme config
+
+## 4. Conversão manual
+
+```typescript
+await pixel.purchase({
+  transactionId: 'order_123',
+  value: 197,
+  currency: 'BRL',
+});
+```
+
+Outros métodos: `lead`, `addToCart`, `removeFromCart`, `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search`.
+
+## 5. Encerrar (SPA / navegação)
+
+```typescript
+await pixel.destroy();
+```
+
+Em React/Next, chame `destroy()` no cleanup do `useEffect`.
+
+## 6. Debug (somente desenvolvimento)
+
+```typescript
+if (pixel.isInitialized()) {
+  console.log(pixel.getDebugSnapshot());
+}
+```
+
+`getDebugSnapshot()` é público; não use `getDebugServices()` (interno).
+
+## Próximos passos
+
+- [Configuração](../configuration/overview.md)
+- [Catálogo de eventos](../events/catalog.md)
+- [Funil checkout](../guides/funnel-checkout.md)

package/docs/public/getting-started/react-nextjs.md

@@ -0,0 +1,55 @@
+# React e Next.js (App Router)
+
+O SDK não exporta hooks React. O padrão recomendado é um hook **local** no app.
+
+## Hook local (`usePixel`)
+
+Referência: `apps/playground-next/lib/use-pixel.ts`
+
+```typescript
+'use client';
+
+import { Pixel } from '@beworke/pixel';
+import { useEffect, useRef, useState } from 'react';
+import { createPixelConfig } from './pixel-config';
+
+export function usePixel() {
+  const pixelRef = useRef<Pixel | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const pixel = new Pixel(createPixelConfig());
+    pixelRef.current = pixel;
+
+    pixel.init().then(() => setReady(true));
+
+    return () => {
+      void pixel.destroy();
+      pixelRef.current = null;
+      setReady(false);
+    };
+  }, []);
+
+  return { pixel: pixelRef, ready };
+}
+```
+
+## Config por página/funil
+
+Centralize em `createPixelConfig()` (`apps/playground-next/lib/pixel-config.ts`):
+
+- `identity.funnelId`, `funnelStepId`, `pageId` por etapa do funil
+- `commerce.catalog` para produtos da oferta
+- `storage.persistence` com `sessionStorage` para sessão sobreviver a reloads
+
+## SSR
+
+- Instancie `Pixel` apenas no cliente (`'use client'`).
+- Não chame `init()` no servidor.
+- `destroy()` no unmount evita listeners duplicados.
+
+## Checkout
+
+`apps/playground-next/app/checkout/page.tsx` demonstra `initiateCheckout`, `addPaymentInfo`, `purchase` com catálogo commerce.
+
+Guia: [Funil checkout](../guides/funnel-checkout.md).