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

package/CHANGELOG.md

@@ -1,8 +1,255 @@
-# @agenus-io/pixel
+# @beworke/pixel
 
-## Unreleased
+## Unreleased — Etapa 20 Runtime Intelligence
 
-### Release Candidate (0.0.15)
+### Added
+
+- `modules.behavior.rateLimit` — limitador interno por instância (sliding window, critical bypass para IDLE/ACTIVITY/VISIBLE/HIDDEN/EXIT_INTENT)
+- `modules.behavior.buffer` — agregação interna de sinais (drop_oldest / drop_newest / compress_similar; flush por size/age/hidden/destroy)
+- `modules.behavior.stateMachine` — estados explícitos (NOT_INITIALIZED → … → DESTROYED) com tabela de transições e histórico limitado
+- `modules.behavior.sessionSummary` — resumo consolidado da sessão com `emitOnHidden` / `emitOnDestroy` / `minimumSessionMs`
+- `BehaviorRuntimeCoordinator` — pipeline SignalBus → RateLimit → Buffer → StateMachine → Accumulator → Dispatcher
+- Evento tipado `BEHAVIOR_SESSION_SUMMARY` (categoria `ENGAGEMENT`) + `ApiEventType`
+- Diagnostics: `behavior.rateLimit`, `behavior.buffer`, `behavior.stateMachine`, `behavior.sessionSummary`
+- Health `degraded` isolado (high drop rate, buffer full, invalid transitions)
+- Exemplo `examples/html-script/behavior/example-behavior-runtime-intelligence.html`
+- Testes `src/modules/behavior/runtime-intelligence.test.ts` (38 casos)
+
+### Notes
+
+- Pacote permanece em `0.1.0-rc.5` (sem bump)
+- Behavior Runtime Evolution **17–20 concluída**
+- Próxima etapa oficial: 21 — Commerce lifecycle
+
+## Unreleased — Hardening 19.1 (gate Etapa 20)
+
+### Fixed
+
+- `ApiEventType` agora inclui `ENGAGEMENT_UPDATE` e `ENGAGEMENT_SUMMARY` (contrato HTTP reconhece os eventos; o cast em `EventPayloadBuilder` deixou de mascarar a ausência)
+- Ordem de init do Behavior Runtime reordenada para `bus → Engagement → trackers → Heartbeat`: o Engagement passa a receber os sinais iniciais (`HIDDEN`/`VISIBLE` da inicialização do `VisibilityTracker` e `HEARTBEAT` de `fireImmediately`)
+- `EngagementEngine.init()` faz `reset()` do `BehaviorSignalBus` próprio no reinit (apenas quando `ownsBus`); subscriptions voltam a funcionar após destroy/reinit
+- Playground `example-behavior-engagement.html`: `destroy()` ocorre antes de `unsubscribe()` (captura `ENGAGEMENT_SUMMARY`); painel preserva o último snapshot; reinit mostra o summary anterior sem duplicar listener
+
+### Added
+
+- `src/transport/engagement-transport.test.ts` — contrato HTTP (ApiEventType/EventPayloadBuilder/batch) + guard de compilação
+- Testes de regressão em `engagement.test.ts`: ownership do SignalBus (bus próprio reinit / bus injetado não resetado / duplicate init / duplicate destroy) e ordem de init (HIDDEN/VISIBLE inicial, HEARTBEAT imediato, reinit sem vazamento)
+
+### Notes
+
+- Pacote permanece em `0.1.0-rc.5` (sem bump); 630 testes passando | 2 skipped
+- Etapa 20 — Runtime Intelligence liberada
+
+## Unreleased — Etapa 19 Engagement Runtime
+
+### Added
+
+- `modules.behavior.engagement` — contrato oficial (`enabled`, `evaluationIntervalMs`, `emitOnChange`, `minScoreDelta`, `emitSummaryOnDestroy`, `weights`, `penalties`, `thresholds`; defaults seguros, `enabled: false`)
+- `EngagementEngine` real: consome `BehaviorSignalBus`, produz score determinístico `0..100` via `ManagedScheduler` (sem `setInterval`), com componentes/pesos/penalidades/níveis
+- Componentes: `EngagementSignalAccumulator`, `EngagementScoreCalculator`, `EngagementLevelResolver`, `EngagementEmissionPolicy`, `EngagementSummaryBuilder`
+- Eventos tipados `ENGAGEMENT_UPDATE` / `ENGAGEMENT_SUMMARY` (categoria `ENGAGEMENT`)
+- `resolveEngagementConfig` / `normalizeEngagementConfig` (clamp de intervalo/delta, normalização de pesos para somar 1, clamp de penalidades, validação de thresholds)
+- Diagnostics: `getDebugSnapshot().behavior.engagement` (score/level/contadores/signalCounts, sanitizado) e `configuredEngines` inclui `engagement`
+- Health `degraded` isolado quando o engine opcional tem drift excessivo ou falha de cálculo
+- `ScrollTracker`/`ClickTracker` publicam `SCROLL`/`CLICK`/`RAGE_CLICK` no `BehaviorSignalBus`; `HeartbeatEngine` publica `HEARTBEAT`
+- Exemplo `examples/html-script/behavior/example-behavior-engagement.html`
+- Testes `src/modules/behavior/engagement.test.ts` (48 casos, incl. Hardening 19.1)
+
+### Changed
+
+- Diagnostics: `configuredEngines` reporta `engagement` (antes: `engagement(stub)`)
+
+### Breaking
+
+- `modules.behavior.engagement` migrou do shape legado (`weights.{scroll,click,time}`, `thresholds.{low,medium}`) para o contrato da Etapa 19. Sem migration layer (config legada nunca esteve wired a runtime)
+- Tipos públicos `EngagementWeights` / `EngagementThresholds` mudaram de shape; adicionado `EngagementPenalties`
+
+### Notes
+
+- Pacote permanece em `0.1.0-rc.5` (sem bump)
+- Próxima etapa oficial: 20 — Runtime Intelligence
+
+## Unreleased — Hardening 18.1 (gate Etapa 19)
+
+### Fixed
+
+- Viewport MutationObserver rescan: `cleanupDisconnectedElements` agora ocorre **antes** de `scanAndObserve` — evita regressão com `maxObservedElements` quando A é removido e B é adicionado na mesma batch
+- Dispatcher: falha de um listener não interrompe os demais nem propaga ao produtor; log sanitizado `DISPATCHER_LISTENER_FAILED` (sem payload/PII)
+
+### Added
+
+- Testes explícitos Hardening 18.1: limites, SSR, IntersectionObserver/MutationObserver failures, mutation burst, isolamento Dispatcher ↔ Viewport/Heartbeat
+
+### Notes
+
+- Pacote permanece em `0.1.0-rc.5` (sem bump)
+- Etapa 19 — Engagement liberada após gate 18.1
+
+## Unreleased — Etapa 18 Viewport Runtime
+
+### Added
+
+- `modules.behavior.trackers.viewport` — config aditiva (`targets[]`, `rootMargin`, `observeMutations`, `mutationDebounceMs`, `maxObservedElements`; defaults seguros, `enabled: false`)
+- `ViewportTracker` real com `IntersectionObserver` + `MutationObserver` (DOM dinâmico)
+- Eventos tipados `VIEWPORT_ENTER` / `VIEWPORT_EXIT` (categoria `ENGAGEMENT`)
+- `ViewportObserverFactory`, `ViewportTargetRegistry`, `ViewportStateStore`, `normalizeViewportConfig`, `describeViewportElement`
+- `BehaviorSignalBus.createSignal()` — geração de ID de sinal por instância (sem estado module-level)
+- Diagnostics: `getDebugSnapshot().behavior.viewport` + separação `configuredTrackers` (Scroll/Click/Idle/Visibility/ExitIntent/Viewport) vs `configuredEngines` (Heartbeat/Engagement)
+- Health `degraded` quando `viewport.enabled === true` e `IntersectionObserver` indisponível
+- Exemplo `examples/html-script/example-behavior-viewport.html`
+- Testes `src/modules/behavior/viewport.test.ts`
+
+### Changed
+
+- `getDebugSnapshot().behavior` passa a expor `configuredTrackers` e `configuredEngines` separados (antes: apenas `configuredTrackers` misturando trackers e engines)
+- `IdleTracker` / `VisibilityTracker` passam a usar `signalBus.createSignal()` em vez de sequência interna do bus
+
+### Breaking
+
+- **Removido** o contrato stub de `trackers.viewport` (`selector`, `selectorType`, `visibilityThreshold`) — substituído integralmente por `targets[]` + `rootMargin`/`observeMutations`/`mutationDebounceMs`/`maxObservedElements`. Sem migration layer (stub nunca esteve wired em produção).
+
+### Notes
+
+- Viewport mede visibilidade de elementos e publica via Dispatcher; **não** chama Transport/Queue/Sender
+- Sem polling como fallback: se `IntersectionObserver` está indisponível, o tracker fica `available: false` e não observa nada
+- `SignalBus` deixa de ter `signalSeq` module-level; cada instância de `BehaviorSignalBus` gera seus próprios IDs via `createSignal()`
+- Pacote permanece em `0.1.0-rc.5` (sem bump de versão)
+
+## Unreleased — Etapa 17 Heartbeat Runtime
+
+### Added
+
+- `modules.behavior.heartbeat` — config aditiva (defaults seguros, `enabled: false`)
+- `HeartbeatEngine` + `ManagedScheduler` + `BehaviorSignalBus` + `HeartbeatPolicy` / `HeartbeatSnapshotBuilder`
+- Evento tipado `BEHAVIOR_HEARTBEAT` (categoria `ENGAGEMENT`)
+- Diagnostics: `getDebugSnapshot().behavior.heartbeat`
+- Exemplo `examples/html-script/example-behavior-heartbeat.html`
+- Testes `src/modules/behavior/heartbeat.test.ts`
+
+### Changed (contrato Heartbeat consolidado)
+
+- Removido `trackers.heartbeat` e qualquer fallback/legacy
+- `engagement` movido para `modules.behavior.engagement` (irmão de `trackers`)
+- Adicionado `hiddenIntervalMs` ao contrato oficial de Heartbeat
+
+### Notes
+
+- Heartbeat mede presença e publica via Dispatcher; **não** chama Transport/Queue/Sender
+- Scheduler usa `intervalMs` (visível) ou `hiddenIntervalMs` (escondido); `emitWhenHidden` controla emissão
+- Sequence reinicia a cada `init`
+- Intervalo mínimo normalizado: 1000ms
+
+## 0.1.0-rc.5 — Runtime Diagnostics (Etapa 16)
+
+### Added
+
+- `pixel.getDebugSnapshot()` — snapshot oficial read-only, imutável e sanitizado
+- Módulo `diagnostics` (`RuntimeDiagnosticsModule` + `DebugSnapshotService`)
+- Redaction de secrets/PII em snapshots
+- Health evaluator (`healthy` / `degraded` / `unhealthy` / `unknown`)
+- Exemplo `examples/html-script/example-runtime-diagnostics.html`
+- Testes `src/diagnostics/diagnostics.test.ts`
+
+### Notes
+
+- `subscribeDebug` **não** implementado propositalmente (sem polling/timers); snapshot sob demanda apenas
+- Sem alteração no pipeline de eventos / Transport / Conversion
+- Hardening: sanitização ampliada; `modules[].id` (evita colisão com PII `name`); testes hardening
+
+## 0.1.0-rc.4 — Etapa 15B Validation Hardening
+
+### Added
+
+- `PIXEL_V2_VALIDATION_MATRIX.md` — matriz oficial de validação integrada
+- `PIXEL_V2_STAGE_15B_REPORT.md` — relatório da Etapa 15B
+- Playground `examples/html-script/full-funnel/` (landing → checkout → upsell/downsell → thank-you)
+- Scripts: `validate:15b`, `test:integration`, `test:transport`, `test:full-funnel`, `test:chaos`
+- Teste de matriz de módulos `stage-15b-module-matrix.test.ts`
+
+### Changed
+
+- Documentação alinhada ao runtime real (Transport/Integrations implementados; Privacy stub; Behavior P1 pendente)
+- Roadmap oficial 16–22 documentado (sem implementação)
+- Hierarquia documental registrada em ARCHITECTURE / README / BACKLOG
+
+### Fixed
+
+- Referências “Transport futuro” / Dispatcher sem consumidor real
+- Checklist RC inconsistente
+- `examples/v2` / html-script RELEASE notes apontando rc.3 onde cabia rc.4
+- Full-funnel: `commerce.catalog` + `cart.initialItems[{ productId }]`; `paymentMethod: CREDIT_CARD`; `order_id` antes do init
+- Docs: status **1–15B concluídas** (sem “15B em andamento”)
+
+## 0.1.0-rc.4 — Core UrlContext
+
+### Added
+
+- Core UrlContext module
+- `query_params` / `url_context` on events
+- managed URL params (public `sid`)
+- forward params + link decoration
+- denylist for sensitive params
+- HTML examples for landing/checkout/upsell/allowedDomains
+
+### Changed
+
+- Event builder enriches centrally when `urlContext` enabled
+
+### Fixed / Hardening (15A finalização)
+
+- Decode seguro de query/cookie (`safeDecodeURIComponent`) — URI malformada não quebra init
+- Link decorator idempotente (sem `sid=a&sid=a`); colapsa duplicados
+- Preserva href relativo e ordem `?query#hash`
+- Snapshot / payload com cópias congeladas (sem mutação externa nem refs compartilhadas)
+- Cache de exclude domains/selectors no decorator (perf em milhares de links)
+- `resolveUrlContextConfig` clona nested arrays/objects (defaults imutáveis)
+- `dispose()` alias em engine/service
+
+### Security
+
+- Denylisted params not captured/forwarded
+- Public `sid` ≠ internal `session_id`
+
+## 0.1.0-rc.3 — Global Commerce Config + Hardening 14B/14C
+
+### Changed
+
+- Commerce global no root de `PixelConfig` (`config.commerce`)
+- `commerce.checkout` → `commerce.cart`
+- `selectedItems` na config → `commerce.cart.initialItems`
+- Auto detectors usam `auto.detectors[event].sources[]`
+- `calculateValueFrom: 'selected_items'` → `'cart'`
+- Novo: `commerce.enrichment` por evento (`pageView`, `viewContent`, `lead`, …)
+- Novo: `commerce.cart.mode` inclui `landing_page` e `checkout`
+- Exemplos HTML, Next.js, docs e `example-landing-commerce.html` migrados
+- Removidos aliases públicos `CommerceItem` / `CommerceCheckoutMode` e literais `selected_items` / `event_items` do tipo oficial
+
+### Fixed
+
+- Enrichment respeita `commerce.enabled` e `enrichment[event].enabled`
+- `FormSource` respeita escopo (`selector` / `formSelector`) em todos os triggers
+- `PaymentSource` respeita `formSelector` real do campo
+- Docs normalizadas — removidos resíduos de contratos antigos
+- **14C:** `ADD_TO_CART` sem `productId` usa item principal de `commerce.cart` (initialItems/runtime) quando enrichment permite
+
+### Breaking
+
+- Removido `modules.conversion.commerce`
+- Removidos `selector`, `selectorForm`, `cardDetection`, `autoDispatch`, `paymentMethod` no nível do detector — use apenas dentro de `sources[]`
+
+### 0.1.0-rc.2 — Etapa 14 Auto Sources Contract
+
+- **Breaking (contrato auto):** detectors passam a usar `sources: AutoTrackSource[]`
+  - Removidos do nível do detector: `selector`, `selectorType`, `selectorForm`, `paymentMethod`, `cardDetection`, `autoDispatch`
+  - Types: `selector` | `form` | `payment` | `lifecycle` | `url`
+  - Múltiplas sources independentes por evento (ex.: ADD_TO_CART form + click)
+- `AutoTrackerFactory` cria um detector por source
+- Novo `LifecycleAutoDetector` (INITIATE_CHECKOUT on ready)
+- Payment via `type: 'payment'` → `CardDetector`
+- Defaults: todos os detectors com `sources: []`
+- Exemplos / RC / Next checkout migrados
+
+### Release Candidate (0.1.0-rc.1 / 0.0.15)
 
 - Etapas 12A–12N Commerce + AutoTrack + docs/release readiness
 - Etapa 13A — validação consumidor real (`PixelV2` + Transport Event/Batch)
@@ -156,7 +403,7 @@
 - **Configuração Dinâmica**: Atualização de configuração em runtime
 - **Múltiplos Seletores**: Suporte a class, id, attribute, tag, text, url, data-attribute, custom
 - **Extração de Dados**: Seletores configuráveis para extrair dados de produtos/carrinho
-- **Validação**: Sistema de validação de formulários com regras customizadas
+- **Validação**: Sistema de validação de formulários com regras customizáveis
 - **Callbacks Customizados**: Funções de callback para processamento customizado
 
 #### 📊 **Monitoramento e Estatísticas**

package/README.md

@@ -1,163 +1,141 @@
-# Pixel v2
+# Pixel v2 (`@beworke/pixel`)
 
-SDK de analytics e conversão para web — arquitetura modular v2.
+SDK de analytics e conversão para web — implemente funis (landing, checkout, upsell, thank-you) em React, Next.js, SPA ou HTML puro **sem conhecer a arquitetura interna**.
 
-**Documentação:** [`ARCHITECTURE.md`](./ARCHITECTURE.md) · [`README_LEGACY_AUDIT.md`](./README_LEGACY_AUDIT.md) · [`RELEASE_CANDIDATE.md`](./RELEASE_CANDIDATE.md)
+**Versão RC:** `0.1.0-rc.5` · **Etapas concluídas:** 1–20 · **Próxima etapa funcional:** 21 — Commerce Lifecycle
 
-## Arquitetura
+## Documentação pública
 
-```txt
-Pixel → PixelRuntime → Services → Modules → BaseEventBuilder → Dispatcher
-  ├── TransportModule → API própria
-  └── IntegrationsModule → PAGE_VIEW browser (Meta / Google / TikTok)
-```
+**Comece aqui:** [`docs/public/README.md`](./docs/public/README.md)
 
-Attribution é independente: `AttributionService` → `event.identifiers` → Transport/API.
+| Guia | Link |
+|------|------|
+| Instalação | [docs/public/getting-started/installation.md](./docs/public/getting-started/installation.md) |
+| Quick start | [docs/public/getting-started/quick-start.md](./docs/public/getting-started/quick-start.md) |
+| API Pixel | [docs/public/api/pixel.md](./docs/public/api/pixel.md) |
+| Eventos | [docs/public/events/catalog.md](./docs/public/events/catalog.md) |
+| Configuração | [docs/public/configuration/overview.md](./docs/public/configuration/overview.md) |
+| Funis | [docs/public/guides/funnel-full.md](./docs/public/guides/funnel-full.md) |
+| Privacidade (RC) | [docs/public/privacy/limitations.md](./docs/public/privacy/limitations.md) |
+| Limitações | [docs/public/limitations.md](./docs/public/limitations.md) |
 
-O legado `GomarkePixel` (v1) foi **removido na Etapa 11**.
+Exemplos públicos: [`examples/public/`](./examples/public/) · Next.js: [`examples/nextjs/`](./examples/nextjs/)
 
 ## Instalação
 
 ```bash
-pnpm add @agenus-io/pixel
+npm install ./beworke-pixel-0.1.0-rc.5.tgz
+npm run validate:rc-package   # no repo do SDK
 ```
 
-Tarball local (RC):
-
-```bash
-npm pack
-npm install ./agenus-io-pixel-0.0.15.tgz
-npm run validate:rc-package
-```
+## Quick start
 
-## Uso (ESM / CJS)
-
-```ts
-import { Pixel, DEFAULT_PIXEL_CONFIG } from '@agenus-io/pixel';
+```typescript
+import { Pixel, DEFAULT_PIXEL_CONFIG } from '@beworke/pixel';
 
 const pixel = new Pixel({
   ...DEFAULT_PIXEL_CONFIG,
-  identity: {
-    ...DEFAULT_PIXEL_CONFIG.identity,
-    pixelId: 'pix_123',
-  },
+  identity: { pixelId: 'pix_YOUR_ID' },
   transport: {
     ...DEFAULT_PIXEL_CONFIG.transport,
-    apiEndpoint: 'https://sua-api.example.com',
+    apiEndpoint: 'https://your-pixel-api.example.com',
+  },
+  storage: {
+    ...DEFAULT_PIXEL_CONFIG.storage,
+    persistence: {
+      visitor: 'localStorage',
+      session: 'sessionStorage',
+      attribution: 'localStorage',
+    },
   },
   modules: {
     ...DEFAULT_PIXEL_CONFIG.modules,
-    core: {
-      ...DEFAULT_PIXEL_CONFIG.modules.core,
-      enabled: true,
-      pageView: {
-        ...DEFAULT_PIXEL_CONFIG.modules.core.pageView,
-        enabled: true,
-        trackInitialPageView: true, // PAGE_VIEW no init — não há pixel.pageView()
-      },
-    },
-    conversion: {
-      ...DEFAULT_PIXEL_CONFIG.modules.conversion,
-      enabled: true,
-      manual: {
-        ...DEFAULT_PIXEL_CONFIG.modules.conversion.manual,
-        purchase: { enabled: true },
-      },
-    },
+    core: { ...DEFAULT_PIXEL_CONFIG.modules.core, enabled: true },
     transport: {
       ...DEFAULT_PIXEL_CONFIG.modules.transport,
       enabled: true,
-      mockSender: { enabled: false },
-      sender: { mode: 'http' },
+      sender: { mode: 'api' },
     },
   },
 });
 
 await pixel.init();
-pixel.purchase({ orderId: '1', value: 99.9, currency: 'BRL' });
+// PAGE_VIEW automático
+
+pixel.lead({ email: 'user@example.com' });
+pixel.purchase({ transactionId: 'ord_1', value: 197, currency: 'BRL' });
+
 await pixel.destroy();
 ```
 
-```js
-const { Pixel, DEFAULT_PIXEL_CONFIG } = require('@agenus-io/pixel');
-```
+## Métodos públicos
 
-## CDN (bundle global)
+| Método | Descrição |
+|--------|-----------|
+| `init()` / `destroy()` / `isInitialized()` | Ciclo de vida |
+| `getDebugSnapshot()` | Snapshot read-only (dev/QA) |
+| `purchase`, `lead`, `addToCart`, `removeFromCart` | Conversão |
+| `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search` | Conversão |
+
+Exports: `DEFAULT_PIXEL_CONFIG`, `PixelConfig`, `PixelDebugSnapshot`, `resolveStorageAdapterName`.
+
+Detalhes: [docs/public/api/pixel.md](./docs/public/api/pixel.md)
+
+## Eventos (resumo)
+
+Core · Session · Behavior · Conversion — 24 tipos em `PixelEvent`. Catálogo completo: [docs/public/events/catalog.md](./docs/public/events/catalog.md).
+
+## Script tag (CDN / IIFE)
 
 ```html
-<script src="https://unpkg.com/@agenus-io/pixel@latest/dist/v2/global.global.js"></script>
+<script src="https://unpkg.com/@beworke/pixel@0.1.0-rc.5/dist/v2/global.global.js"></script>
 <script>
   const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
-  const pixel = new Pixel({
-    ...DEFAULT_PIXEL_CONFIG,
-    identity: { ...DEFAULT_PIXEL_CONFIG.identity, pixelId: 'pix_123' },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.transport,
-      apiEndpoint: 'https://sua-api.example.com',
-    },
-    modules: {
-      ...DEFAULT_PIXEL_CONFIG.modules,
-      core: {
-        ...DEFAULT_PIXEL_CONFIG.modules.core,
-        enabled: true,
-        pageView: {
-          ...DEFAULT_PIXEL_CONFIG.modules.core.pageView,
-          enabled: true,
-          trackInitialPageView: true,
-        },
-      },
-    },
-  });
-  pixel.init();
 </script>
 ```
 
-Nome global oficial: **`PixelV2`**.
+Global oficial: **`window.PixelV2`**. Prefira tarball fixo `0.1.0-rc.5` em testes reprodutíveis.
 
 ## Package exports
 
-| Export | Descrição |
-|--------|-----------|
-| `@agenus-io/pixel` | `Pixel`, `DEFAULT_PIXEL_CONFIG`, `PixelConfig` |
-| `@agenus-io/pixel/global` | IIFE `window.PixelV2` |
-| `@agenus-io/pixel/v2` | Alias do entry principal |
-| `@agenus-io/pixel/config` | Tipos e defaults de configuração |
-| `@agenus-io/pixel/events` | Eventos tipados |
-| `@agenus-io/pixel/services` | Services (attribution, session, etc.) |
-| `@agenus-io/pixel/runtime` | Runtime e bootstrap |
-| `@agenus-io/pixel/logger` | Logger |
+| Export | Uso |
+|--------|-----|
+| `@beworke/pixel` | Entry principal |
+| `@beworke/pixel/global` | IIFE |
+| `@beworke/pixel/v2` | Alias |
+| `@beworke/pixel/config`, `/events`, `/services`, `/runtime`, `/logger` | Avançado |
+
+Não existe `@beworke/pixel/diagnostics` no RC.
 
-## Playgrounds
+## Limitações do RC
 
-Exemplos oficiais em `examples/html-script/` (copiados para `dist/examples/html-script/` no build):
+- **Sem Consent Gate / CMP completo** — a aplicação controla quando chamar `init()` ([privacidade](./docs/public/privacy/limitations.md))
+- **Não declarar GDPR/LGPD/CCPA compliant** com este RC
+- Sem eventos dedicados upsell/downsell — use `VIEW_CONTENT` + `PURCHASE`
+- Etapa 21 (Commerce Lifecycle) e Etapa 25 (Privacy) ainda no roadmap
 
-- `release-candidate.html` — consumidor real (`window.PixelV2` + Transport)
-- `RELEASE_CANDIDATE.md` — como testar o playground RC
-- `example-basic.html`, `example-behavior.html`, `example-conversion.html`, …
-- pastas por evento: `lead/`, `add-to-cart/`, …
+Lista completa: [docs/public/limitations.md](./docs/public/limitations.md) · [RELEASE_CANDIDATE.md](./RELEASE_CANDIDATE.md)
 
-Índice: [`examples/html-script/README.md`](./examples/html-script/README.md)  
-Release notes: [`RELEASE_CANDIDATE.md`](./RELEASE_CANDIDATE.md)
+## Validação
 
-## Scripts
+670 testes passando (2 skipped). Comandos:
 
 ```bash
-pnpm build                 # dist/
-pnpm test                  # testes v2
-pnpm type-check            # tsc --noEmit
-pnpm test:smoke:real       # smoke Event/Batch (skip sem .env)
-pnpm validate:rc-package   # instalação limpa do .tgz
+npm run type-check && npm test && npm run build
+npm run validate:public-docs && npm run validate:public-examples
+npm run validate:rc-package
 ```
 
-## Migração v1 → v2
-
-| v1 (removido) | v2 |
-|---------------|-----|
-| `GomarkePixel` | `Pixel` |
-| `window.gomarkePixel` | `window.PixelV2` |
-| `dist/index.global.js` | `dist/v2/global.global.js` |
-| `src/core/**` | `modules/core` + `transport` |
-| `src/behavior/**` | `modules/behavior` |
-| `src/conversion/**` | `modules/conversion` |
-| `getTrackingCookies` | `AttributionService` |
-| `loadFacebookPixel` / `loadGoogleTag` | `IntegrationEngine` browser destinations |
+Matriz: [`PIXEL_V2_VALIDATION_MATRIX.md`](./PIXEL_V2_VALIDATION_MATRIX.md)
+
+---
+
+## Contribuidores e arquitetura interna
+
+Documentação de engenharia (não necessária para implementar funis):
+
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+- [`README_LEGACY_AUDIT.md`](./README_LEGACY_AUDIT.md)
+- Playgrounds internos: [`examples/html-script/`](./examples/html-script/)
+
+Migração v1 → v2: `GomarkePixel` → `Pixel`, `window.gomarkePixel` → `window.PixelV2`.