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

package/RELEASE_CANDIDATE.md

@@ -1,21 +1,43 @@
 # Pixel v2 — Release Candidate Notes
 
-**Pacote:** `@agenus-io/pixel`  
-**Versão:** `0.0.15` (release candidate)  
-**Data:** 2026-07-11  
-**Status:** Pronto para publicar RC — **nenhuma pendência P0 conhecida**
+**Pacote:** `@beworke/pixel`  
+**Versão:** consulte `package.json` (fonte de verdade; este arquivo é histórico do RC)  
+**Data:** 2026-07-14  
+**Status 20:** **Concluída** — Runtime Intelligence · [`PLAN_PIXEL/PIXEL_V2_STAGE_20_REPORT.md`](../../../PLAN_PIXEL/PIXEL_V2_STAGE_20_REPORT.md)
 
-> Guia do playground consumidor: [`examples/html-script/RELEASE_CANDIDATE.md`](./examples/html-script/RELEASE_CANDIDATE.md)  
-> Backlog: [`PIXEL_V2_BACKLOG_PENDENCIAS_ISOLADO.md`](./PIXEL_V2_BACKLOG_PENDENCIAS_ISOLADO.md)
+> Runtime e módulos implementados estão prontos para **validação controlada**.  
+> **Próxima etapa oficial: 21 — Commerce lifecycle** (Behavior Runtime Evolution 17–20 concluída).  
+> Privacy Module foi movido para o roadmap **Public SDK Hardening** (etapa 25).  
+> Será desenvolvido antes da primeira distribuição pública da SDK.  
+> **Não** faz parte do Runtime obrigatório da versão 1.0 interna.
+
+> Guia do playground: [`apps/playground-html/RELEASE_CANDIDATE.md`](../../../apps/playground-html/RELEASE_CANDIDATE.md)  
+> Funil completo: [`apps/playground-html/full-funnel/`](../../../apps/playground-html/full-funnel/)  
+> Backlog: [`PLAN_PIXEL/PIXEL_V2_BACKLOG_PENDENCIAS_ISOLADO.md`](../../../PLAN_PIXEL/PIXEL_V2_BACKLOG_PENDENCIAS_ISOLADO.md)
 
 ---
 
 ## 1. Status do RC
 
 ```txt
-Pixel v2 está pronto para release candidate.
-Nenhuma pendência P0 conhecida.
-npm publish NÃO foi executado nesta etapa (13B).
+Pixel v2 RC 0.1.0-rc.5 — Etapas 1–20 concluídas.
+Runtime Intelligence (20): RateLimit + Buffer + StateMachine + SessionSummary → BEHAVIOR_SESSION_SUMMARY via Dispatcher.
+Engagement (19): `modules.behavior.engagement` (score determinístico 0..100 via ManagedScheduler) → `ENGAGEMENT_UPDATE`/`ENGAGEMENT_SUMMARY` via Dispatcher.
+Hardening 19.1 (gate 20): ApiEventType inclui ENGAGEMENT_UPDATE/SUMMARY; ordem init; playground summary; SignalBus reinit.
+Viewport (18): `modules.behavior.trackers.viewport` (targets[] + IntersectionObserver/MutationObserver) → `VIEWPORT_ENTER`/`VIEWPORT_EXIT` via Dispatcher.
+Hardening 18.1: mutation rescan cleanup→scan; Dispatcher listener failure isolation; testes limite/SSR/observers.
+Heartbeat (17): `modules.behavior.heartbeat` (único contrato; `intervalMs` / `hiddenIntervalMs`) → `BEHAVIOR_HEARTBEAT` via Dispatcher.
+Core UrlContext (15A): query_params + url_context em eventos.
+Commerce é root config (cart.initialItems + enrichment) — plano fechado em rc.3.
+Contrato auto oficial: detectors[event].sources[].
+Matriz oficial de testes: PIXEL_V2_VALIDATION_MATRIX.md
+npm publish NÃO executado nesta etapa.
+git tag NÃO criada nesta etapa.
+Breaking vs 0.1.0-rc.5 pré-18: contrato stub `trackers.viewport` (selector/selectorType/visibilityThreshold) removido — nunca esteve wired em produção.
+Breaking vs 0.1.0-rc.5 pré-17: nenhum (adição aditiva Heartbeat).
+Breaking vs 0.1.0-rc.3: nenhum (adição UrlContext apenas).
+Breaking vs 0.1.0-rc.2: modules.conversion.commerce removido; checkout→cart; selectedItems→initialItems.
+Breaking vs 0.1.0-rc.1: detectors usam sources[] (campos soltos no detector removidos).
 ```
 
 Validado em 13A (consumidor real) + 13B (pacote / instalação limpa).
@@ -27,7 +49,7 @@ Validado em 13A (consumidor real) + 13B (pacote / instalação limpa).
 ```txt
 Runtime v2 + bootstrap
 Core services (visitor, session, fingerprint, storage)
-Behavior tracking
+Behavior tracking (P0 + Heartbeat + Viewport)
 Conversion tracking (manual + auto)
 Transport real Event + Batch (HttpSender)
 Resiliência (retry, offline, circuit breaker, DLQ, …)
@@ -35,7 +57,8 @@ Replay / Ordering / Coordination
 Browser destinations (Meta / Google / TikTok)
 Attribution
 Commerce + AutoTrack avançado (12A–12M)
-Playgrounds examples/html-script/*
+Core UrlContext (15A — query_params, managed/forward, link decoration)
+Playgrounds apps/playground-html/*
 Smoke real opcional (env)
 Release candidate HTML + pack validation (13A–13B)
 ```
@@ -49,25 +72,31 @@ Correção recente (pré-13B): match `text:` leaf-only — evita ADD_TO_CART em
 ### Registry (quando publicado)
 
 ```bash
-pnpm add @agenus-io/pixel
+pnpm add @beworke/pixel
 # ou
-npm install @agenus-io/pixel
+npm install @beworke/pixel
 ```
 
 ### Tarball local (RC sem publish)
 
+Na raiz do monorepo:
+
 ```bash
-npm run build
-npm pack
-npm install ./agenus-io-pixel-0.0.15.tgz
+pnpm pack:pixel
+pnpm validate:pixel-package
+# opcional: instalar o .tgz gerado em artifacts/
+pnpm smoke:pixel-package
 ```
 
-Validar tarball:
+O fluxo oficial é **`pnpm pack:pixel`** (escreve em `artifacts/`).  
+Não use `pnpm --filter @beworke/pixel pack` como fluxo principal.
+
+Validar tarball (usa `artifacts/latest-package.json`):
 
 ```bash
-npm run validate:rc-package
-# ou
-node scripts/validate-rc-package.mjs ./agenus-io-pixel-0.0.15.tgz
+pnpm validate:pixel-package
+# ou caminho explícito:
+node scripts/validate-rc-package.mjs artifacts/beworke-pixel-0.1.0-rc.6.tgz
 ```
 
 ---
@@ -75,109 +104,75 @@ node scripts/validate-rc-package.mjs ./agenus-io-pixel-0.0.15.tgz
 ## 4. Como usar via import (ESM)
 
 ```ts
-import { Pixel, DEFAULT_PIXEL_CONFIG } from '@agenus-io/pixel';
+import { createPixel } from '@beworke/pixel';
 
-const pixel = new Pixel({
-  ...DEFAULT_PIXEL_CONFIG,
-  identity: {
-    ...DEFAULT_PIXEL_CONFIG.identity,
-    pixelId: 'pix_xxx',
-  },
-  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,
-      },
-    },
-    conversion: {
-      ...DEFAULT_PIXEL_CONFIG.modules.conversion,
-      enabled: true,
-      manual: {
-        ...DEFAULT_PIXEL_CONFIG.modules.conversion.manual,
-        lead: { enabled: true },
-        purchase: { enabled: true },
-      },
-    },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.modules.transport,
-      enabled: true,
-      mockSender: { enabled: false },
-      sender: { mode: 'http' },
-    },
-  },
+const pixel = await createPixel({
+  identity: { pixelId: 'pix_xxx' },
 });
 
-await pixel.init();
 // PAGE_VIEW: emitido pelo Core (trackInitialPageView) — não existe pixel.pageView()
 pixel.lead({ email: 'user@example.com' });
 pixel.purchase({ orderId: '1', value: 99.9, currency: 'BRL' });
 await pixel.destroy();
 ```
 
+Overrides parciais e `PixelConfig` completo continuam válidos. `DEFAULT_PIXEL_CONFIG` permanece para inspeção avançada.
+
 ### CJS
 
 ```js
-const { Pixel, DEFAULT_PIXEL_CONFIG } = require('@agenus-io/pixel');
+const { createPixel } = require('@beworke/pixel');
 ```
 
 ### Subpath `/v2`
 
 ```ts
-import { Pixel } from '@agenus-io/pixel/v2';
+import { Pixel } from '@beworke/pixel/v2';
 ```
 
 ---
 
 ## 5. Como usar via script tag
 
-Bundle IIFE: `dist/v2/global.global.js` → **`window.PixelV2`**
+Bundle recomendado: `dist/browser/pixel.global.js` → **`window.Pixel(settings)`**
 
 ```html
-<script src="./node_modules/@agenus-io/pixel/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_xxx' },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.transport,
-      apiEndpoint: 'https://sua-api.example.com',
-    },
+<script src="./node_modules/@beworke/pixel/dist/browser/pixel.global.js"></script>
+<script type="module">
+  const pixel = await Pixel({
+    identity: { pixelId: 'pix_xxx' },
   });
-  pixel.init();
+  pixel.lead({ email: 'user@example.com' });
 </script>
 ```
 
-Export npm: `@agenus-io/pixel/global`.
+`window.PixelV2` permanece como compatibilidade / API de baixo nível.
+
+Export npm: `@beworke/pixel/global`.
 
 ---
 
 ## 6. Transport real
 
 ```ts
-modules: {
-  transport: {
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: {
+    mode: 'internal',
+    baseUrl: process.env.PIXEL_API_ENDPOINT,
+  },
+  batch: {
+    ...DEFAULT_TRANSPORT_CONFIG.batch,
     enabled: true,
-    mockSender: { enabled: false },
-    sender: { mode: 'http' },
-    batch: { enabled: true, batchSize: 1 }, // Event
-    // batchSize: 10 → Batch
+    batchSize: 1, // Event; use 10 para Batch
   },
 },
-transport: {
-  apiEndpoint: process.env.PIXEL_API_ENDPOINT, // não hardcodar em produção
-},
 ```
 
+Para sender `test`, `internal` sem `baseUrl` e `external`, consulte
+[`docs/public/configuration/transport.md`](./docs/public/configuration/transport.md).
+
 Endpoints oficiais do SDK:
 
 ```txt
@@ -187,21 +182,142 @@ POST {apiEndpoint}/pixels/public/event/batch
 
 ---
 
-## 7. Commerce (resumo)
+## 7. Commerce + Auto Sources (resumo)
 
 ```ts
-modules.conversion.commerce = {
+// Commerce global (raiz — Etapa 14A)
+commerce: {
+  enabled: true,
   currency: 'BRL',
-  catalog: { products: [{ id: 'main_offer', name: '…', price: 197, … }] },
-  checkout: {
-    selectedItems: [{ productId: 'main_offer', quantity: 1 }],
-    calculateValueFrom: 'selected_items',
+  catalog: { products: [{ id: 'main_offer', price: 197, type: 'main' }] },
+  cart: {
+    mode: 'checkout',
+    initialItems: [{ productId: 'main_offer', quantity: 1 }],
     allowDynamicItems: true,
+    calculateValueFrom: 'cart',
+  },
+  enrichment: {
+    pageView: { enabled: false, source: 'cart' },
+    initiateCheckout: { enabled: true, source: 'cart' },
+  },
+},
+
+modules.conversion.auto = {
+  enabled: true,
+  detectors: {
+    addToCart: {
+      enabled: true,
+      sources: [
+        {
+          name: 'main-product-after-contact',
+          type: 'form',
+          selectorForm: {
+            fields: ['email', 'phone'],
+            mode: 'all',
+            formSelector: '#checkout-form',
+            trigger: 'input',
+            fireOnce: true,
+          },
+        },
+        {
+          name: 'product-or-bump-click',
+          type: 'selector',
+          selector: ['[data-track="add_to_cart"]', 'text:Comprar agora'],
+          selectorType: 'css',
+          trigger: 'click',
+          fireOnce: false,
+        },
+      ],
+    },
+    initiateCheckout: {
+      enabled: true,
+      sources: [
+        {
+          name: 'checkout-loaded',
+          type: 'lifecycle',
+          trigger: 'ready',
+          fireOnce: true,
+        },
+      ],
+    },
+    addPaymentInfo: {
+      enabled: true,
+      sources: [
+        {
+          name: 'credit-card-detection',
+          type: 'payment',
+          paymentMethod: 'CREDIT_CARD',
+          cardDetection: true,
+          autoDispatch: true,
+          fireOnce: true,
+        },
+      ],
+    },
   },
 };
 ```
 
-Detalhes: `PIXEL_V2_COMMERCE_AUTOTRACK_PLAN.md` · playgrounds em `examples/html-script/`.
+Detalhes: `PLAN_PIXEL/PIXEL_V2_COMMERCE_AUTOTRACK_PLAN.md` · playgrounds em `apps/playground-html/`.
+
+---
+
+## Hardening 14B
+
+Etapa final de hardening antes de testes reais em produção:
+
+- **`commerce.enabled`** controla enrichment global — sem `enabled: true`, nenhum evento é enriquecido pelo CommerceResolver
+- **`commerce.enrichment[event]`** controla enriquecimento por evento (`pageView`, `viewContent`, `addToCart`, …)
+- **`FormSource`** respeita `selector` / `formSelector` em todos os triggers (`input`, `change`, `submit`, `click`)
+- **`PaymentSource`** respeita o `formSelector` real do campo de pagamento
+- **API pública** aceita payload opcional onde o cart resolve (ex.: `pixel.initiateCheckout()` sem args)
+- **Docs normalizadas** para rc.3 — removidos resíduos de `commerce.checkout`, `selectedItems`, detector solto
+
+## Fechamento 14C
+
+- ADD_TO_CART por FormSource sem `productId` agora usa `commerce.cart.initialItems` (item principal do cart runtime) como fallback quando enrichment permite.
+- Payload manual continua tendo prioridade.
+- Cart fallback respeita `commerce.enabled` e `commerce.enrichment.addToCart.enabled`.
+- Docs limpas de aliases públicos antigos (`CommerceItem`, `CommerceCheckoutMode`, `selected_items` / `event_items` no tipo oficial).
+- Exemplos CDN ajustados para `@rc` / versão fixa (não `@latest`).
+
+---
+
+## Etapa 15A — Core UrlContext
+
+Checklist de validação (rc.4 — Production Ready):
+
+```txt
+[x] example-url-context.html — checkout + upsell com link decoration
+[x] example-url-context-landing.html — landing gera sid público na URL
+[x] example-url-context-upsell.html — forward params entre páginas do funil
+[x] example-url-context-allowed-domains.html — allowedDomains restringe decoração
+[x] Eventos carregam query_params quando urlContext enabled
+[x] Eventos carregam url_context.managed / forwarded / source
+[x] sid público na URL ≠ session_id interno do Pixel
+[x] Params da denylist (token, password, cvv) não capturados nem encaminhados
+[x] order_id permitido na URL; token de pagamento não exposto no SDK
+[x] Hardening: hash/relativos, encoding, idempotência, snapshot freeze, destroy
+[x] npm run type-check / npm test / npm run build
+[x] npm pack → beworke-pixel-0.1.0-rc.4.tgz
+[x] npm run validate:rc-package
+[ ] npm publish --tag rc   # manual
+[ ] git tag                # manual
+```
+
+---
+
+## Etapa 15B — Validation Matrix (fechamento)
+
+```txt
+[x] PIXEL_V2_VALIDATION_MATRIX.md
+[x] PIXEL_V2_STAGE_15B_REPORT.md
+[x] full-funnel playground (contrato oficial commerce + PaymentMethod)
+[x] validate:15b / module matrix
+[x] docs alinhadas (1–15B concluídas)
+[x] npm run type-check / test / build / smoke / pack / validate:rc-package
+[ ] npm publish --tag rc
+[ ] git tag
+```
 
 ---
 
@@ -226,31 +342,32 @@ npm run test:smoke:real
 [x] npm run type-check
 [x] npm test
 [x] npm run build
-[x] npm run test:smoke:real (skip sem env / ACK com env)
+[x] npm run test:smoke:real
 [x] npm pack --dry-run
-[x] npm pack → agenus-io-pixel-0.0.15.tgz
+[x] npm pack
 [x] npm run validate:rc-package
-[x] dist/v2/global.global.js no tarball
-[x] types .d.ts no tarball
-[x] sem .env / credenciais no tarball
-[ ] npm publish --tag rc   # manual, fora da 13B
-[ ] git tag                # manual, fora da 13B
+[ ] npm publish --tag rc
+[ ] git tag
 ```
 
+Evidências: `PIXEL_V2_STAGE_15B_REPORT.md`.
+
 ---
 
 ## 10. Pendências conhecidas (não bloqueiam RC)
 
-**P1:** PrivacyModule/Consent · Behavior P1 · debug snapshot · limpeza CommerceState pós-purchase · docs públicas  
+**P1 (Runtime):** Heartbeat (17) ✅ · Viewport (18) ✅ · Engagement (19) ✅ · Runtime Intelligence (20) ✅ · Commerce lifecycle (21) · Event contract · Attribution bridge · Observabilidade  
+
+**P2:** destinations extras · CAPI/server-side (**backend**, não SDK) · sampling  
 
-**P2:** destinations extras · CAPI/server-side (**backend**, não SDK) · sampling · observabilidade  
+**Public SDK Hardening (25):** Privacy Module · Consent Gate · CMP · GDPR / LGPD / CCPA — **não** bloqueiam 1.0 interna  
 
 ---
 
-## 11. Fora do SDK
+## 11. Fora do Runtime 1.0 interno
 
 ```txt
 CAPI / enrichments server-side
-Consent gate completo (PrivacyModule ainda stub)
+Public SDK Hardening (Privacy / Consent / CMP / GDPR / LGPD / CCPA)
 Publicação automática npm / CDN
 ```