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

package/CHANGELOG.md

@@ -1,8 +1,307 @@
-# @agenus-io/pixel
+# @beworke/pixel
 
-## Unreleased
+## 0.1.0-rc.10 — presets BuyGoods (landing + checkout)
 
-### Release Candidate (0.0.15)
+### Added
+
+- Bundles drop-in sem configuração: `dist/browser/pixel.buygoods-landing.global.js` e `dist/browser/pixel.buygoods-checkout.global.js`
+- Subpaths `@beworke/pixel/buygoods-landing` e `@beworke/pixel/buygoods-checkout`
+- Landing gera `subid4` e decora todos os links com `subid4` + UTMs / params da URL
+- Checkout sobe para `window.top` (Funnel Pixels / iframe), só lê `subid4`, dispara PAGE_VIEW, ADD_TO_CART (email+phone), ADD_PAYMENT_INFO (`#submit`) e HEARTBEAT
+- `pixelId` e o restante da config são internos — o integrador só inclui o `<script>`
+
+## 0.1.0-rc.9 — app.source livre, platform e payload `app`
+
+### Added
+
+- `app.source` aceita os valores conhecidos (`pageus`, `gomarke`, `bemony`, `custom`) **e qualquer outra string** (ex.: `hwaffiliate`)
+- `app.platform` (default `''`; conhecido: `buygoods`; string livre ok)
+- Payload HTTP inclui `app` (`source`, `target`, `platform`, `environment`) no evento e no batch; os mesmos campos também vão em `meta`
+- Exemplo BuyGoods (`apps/playground-html/buygoods`) sobe o Pixel do iframe de Funnel Pixels para `window.top`
+
+### Changed
+
+- Checkout BuyGoods dispara `PAGE_VIEW` no init e desliga `INITIATE_CHECKOUT`
+
+## 0.1.0-rc.8 — factory, browser bootstrap, global callable
+
+### Added
+
+- `createPixel()` no entry principal (instâncias independentes)
+- Subpath `@beworke/pixel/browser` (`bootstrapPixel`, getters, destroy, `PixelBootstrapError`)
+- Bundle `dist/browser/pixel.global.js` com `window.Pixel(settings)` callable
+- Compatibilidade: `window.PixelV2` ganha `createPixel` / `bootstrap` / `getInstance` / `destroy`
+- Pacote `@beworke/pixel-react` (`PixelProvider` / `usePixel`)
+- `SDK_VERSION` centralizada e validada contra `package.json`
+- `PixelSettings` (input público parcial) + `resolvePixelConfig()` no construtor de `Pixel`
+- AutoTrack `selector` aceita `trigger: 'hover'` e `'visible'`; `viewContent` default liga os 3 em `[data-track="view_content"]`. `data-trigger` no HTML restringe o modo (`click` / `hover` / `visible`); sem o atributo, dispara nos 3
+- `PixelConfigurationError` para `pixelId` inválido
+
+### Fixed
+
+- `REMOVE_FROM_CART` usa a mesma janela de 500ms do `ADD_TO_CART` — add → remove → add → remove do mesmo produto volta a disparar
+- `force: true` durante pending destrói a instância anterior (generation token)
+- `window.PixelV2` continua disponível quando `window.Pixel` estrangeiro bloqueia o global
+
+## 0.1.0-rc.6 — Public RC docs on npm + install fix
+
+### Fixed
+
+- README npm com links **GitHub** (npm não hospeda páginas `.md` individuais)
+- `docs/public/` incluído no tarball npm → `node_modules/@beworke/pixel/docs/public/`
+- Instalação documentada: `npm install @beworke/pixel@rc` (público, sem token)
+- `publish:rc` publica tags `rc` e `latest` juntas
+
+## Unreleased — Etapa 20 Runtime Intelligence
+
+### 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 +455,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,125 @@
-# 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)
+A versão publicada está em `package.json`. Instale a tag `@rc` para receber a release candidate atual.
 
-## Arquitetura
+## Instalação (npm — sem token)
 
-```txt
-Pixel → PixelRuntime → Services → Modules → BaseEventBuilder → Dispatcher
-  ├── TransportModule → API própria
-  └── IntegrationsModule → PAGE_VIEW browser (Meta / Google / TikTok)
+Pacote **público**. Qualquer dev instala **sem login** no npm:
+
+```bash
+npm install @beworke/pixel@rc
 ```
 
-Attribution é independente: `AttributionService` → `event.identifiers` → Transport/API.
+> **Importante:** `npm install @beworke/pixel` sem tag usa `latest`. Use `@rc` até alinhar tags.
 
-O legado `GomarkePixel` (v1) foi **removido na Etapa 11**.
+## Documentação pública
 
-## Instalação
+O **npm não hospeda** arquivos `.md` como site (URLs tipo `npmjs.com/.../installation.md` **não existem**).
 
-```bash
-pnpm add @agenus-io/pixel
+| Onde ler | Link |
+|----------|------|
+| **GitHub (recomendado no browser)** | [docs/public/README.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/README.md) |
+| **Após `npm install`** | `node_modules/@beworke/pixel/docs/public/` |
+
+| Guia | GitHub |
+|------|--------|
+| Instalação | [getting-started/installation.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/installation.md) |
+| Quick start | [getting-started/quick-start.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/quick-start.md) |
+| API Pixel | [api/pixel.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md) |
+| Eventos | [events/catalog.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/events/catalog.md) |
+| Configuração | [configuration/overview.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/configuration/overview.md) |
+| Funis | [guides/funnel-full.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/guides/funnel-full.md) |
+| Privacidade (RC) | [privacy/limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/privacy/limitations.md) |
+| Limitações | [limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md) |
+
+Repositório: https://github.com/beworke-apps/Pixel-Global
+
+## Três níveis de uso
+
+### HTML simples (script tag)
+
+Carregar o bundle **apenas registra** `window.Pixel`. Nada é inicializado até `Pixel(settings)` resolver. Top-level `await` exige `type="module"` (ou um IIFE/`then`).
+
+```html
+<script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
+<script type="module">
+  const pixel = await Pixel({
+    identity: { pixelId: 'pix_YOUR_ID' },
+  });
+  pixel.lead({ email: 'user@example.com' });
+</script>
 ```
 
-Tarball local (RC):
+`Pixel(settings)` usa o bootstrap (uma instância por `window`). `window.PixelV2` permanece como compatibilidade / API de baixo nível.
 
-```bash
-npm pack
-npm install ./agenus-io-pixel-0.0.15.tgz
-npm run validate:rc-package
+### NPM com factory
+
+`createPixel` cria **instâncias independentes** (não é singleton).
+
+```typescript
+import { createPixel } from '@beworke/pixel';
+
+const pixel = await createPixel({
+  identity: { pixelId: 'pix_YOUR_ID' },
+});
+
+pixel.lead({ email: 'user@example.com' });
 ```
 
-## Uso (ESM / CJS)
+A classe continua disponível:
 
-```ts
-import { Pixel, DEFAULT_PIXEL_CONFIG } from '@agenus-io/pixel';
+```typescript
+import { Pixel } from '@beworke/pixel';
 
 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, // 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 },
-      },
-    },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.modules.transport,
-      enabled: true,
-      mockSender: { enabled: false },
-      sender: { mode: 'http' },
-    },
-  },
+  identity: { pixelId: 'pix_YOUR_ID' },
 });
-
 await pixel.init();
-pixel.purchase({ orderId: '1', value: 99.9, currency: 'BRL' });
-await pixel.destroy();
 ```
 
-```js
-const { Pixel, DEFAULT_PIXEL_CONFIG } = require('@agenus-io/pixel');
-```
+### Browser avançado
 
-## CDN (bundle global)
+`bootstrapPixel` gerencia **uma instância por `window`**. Para trocar a configuração, destrua explicitamente ou use `force`. Chamadas concorrentes compartilham a configuração da primeira chamada.
 
-```html
-<script src="https://unpkg.com/@agenus-io/pixel@latest/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>
+```typescript
+import { bootstrapPixel } from '@beworke/pixel/browser';
+
+const pixel = await bootstrapPixel(
+  {
+    identity: { pixelId: 'pix_YOUR_ID' },
+  },
+  {
+    waitForConsent: () => window.consentGranted === true,
+  }
+);
 ```
 
-Nome global oficial: **`PixelV2`**.
+React: use [`@beworke/pixel-react`](../pixel-react/README.md) (`PixelProvider` / `usePixel`).
 
-## Package exports
+## Métodos públicos
 
-| Export | Descrição |
+| Método | 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 |
+| `init()` / `destroy()` / `isInitialized()` | Ciclo de vida |
+| `getDebugSnapshot()` | Snapshot read-only (dev/QA) |
+| `purchase`, `lead`, `addToCart`, `removeFromCart` | Conversão |
+| `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search` | Conversão |
 
-## Playgrounds
+Detalhes: [api/pixel.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md)
 
-Exemplos oficiais em `examples/html-script/` (copiados para `dist/examples/html-script/` no build):
+Métodos internos de playground (`@internal`) **não** são API pública.
 
-- `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/`, …
+## Limitações do RC
 
-Índice: [`examples/html-script/README.md`](./examples/html-script/README.md)  
-Release notes: [`RELEASE_CANDIDATE.md`](./RELEASE_CANDIDATE.md)
+- O bundle **não** auto-inicializa; a aplicação controla quando chamar `Pixel(settings)` / `init()`
+- Consent gate opcional no bootstrap — a aplicação decide quando há consentimento suficiente
+- Não declarar GDPR/LGPD/CCPA compliant com este RC
+- Sem eventos dedicados upsell/downsell — use `VIEW_CONTENT` + `PURCHASE`
 
-## Scripts
+Lista: [limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md)
 
-```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
-```
+## Contribuidores
 
-## 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 |
+Arquitetura interna: [PLAN_PIXEL/ARCHITECTURE.md](https://github.com/beworke-apps/Pixel-Global/blob/main/PLAN_PIXEL/ARCHITECTURE.md) · Playgrounds: `apps/playground-html/` no monorepo.