@beworke/pixel-bemony-react 0.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — `@beworke/pixel-bemony-react`
+
+## 0.1.0-rc.1 — First public RC
+
+Primeira publicação npm para validação em apps React/Next.js.
+
+### Highlights
+
+- `PixelProvider` + `usePixel` sobre `bootstrapBemonyPixel`
+- Peers: `react` / `react-dom` (>=18) e `@beworke/pixel-bemony` (>=0.1.0-rc.1)
+- Tags npm: `rc` + `latest`
+
+## 0.0.0
+
+### Minor Changes
+
+- MVP: `PixelProvider` + `usePixel` sobre `bootstrapBemonyPixel`

package/README.md

@@ -0,0 +1,140 @@
+# @beworke/pixel-bemony-react
+
+Camada React mínima sobre [`@beworke/pixel-bemony`](../pixel-bemony) — Provider + hook, sem instanciar o Core (`@beworke/pixel`).
+
+```text
+App React/Next.js
+      ↓
+@beworke/pixel-bemony-react
+      ↓
+@beworke/pixel-bemony
+      ↓
+@beworke/pixel
+```
+
+## Instalação
+
+```bash
+pnpm add @beworke/pixel-bemony-react@rc
+# ou versão fixa:
+pnpm add @beworke/pixel-bemony-react@0.1.0-rc.1
+```
+
+Peers: `react` / `react-dom` (>=18) e `@beworke/pixel-bemony` (>=0.1.0-rc.1).
+
+## Provider
+
+```tsx
+'use client';
+
+import { PixelProvider } from '@beworke/pixel-bemony-react';
+import type { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony-react';
+
+const options: BootstrapBemonyPixelOptions = {
+  environment: 'production',
+  scenario: 'checkout',
+  platform: {
+    pixelId: 'pix_123',
+    allowedDomains: ['checkout.example.com'],
+  },
+  page: {
+    funnelId: 'fun_123',
+    funnelStepId: 'step_123',
+  },
+};
+
+export function Providers({ children }: React.PropsWithChildren) {
+  return <PixelProvider options={options}>{children}</PixelProvider>;
+}
+```
+
+## Consumo
+
+```tsx
+'use client';
+
+import { usePixel } from '@beworke/pixel-bemony-react';
+
+export function Checkout() {
+  const { pixel, ready, status, error } = usePixel();
+
+  if (status === 'initializing') {
+    return <p>Initializing Pixel...</p>;
+  }
+
+  if (error) {
+    return <p>Pixel initialization failed.</p>;
+  }
+
+  return (
+    <button
+      disabled={!ready}
+      onClick={() => {
+        pixel?.trackPaymentMethod({ paymentMethod: 'CREDIT_CARD' });
+      }}
+    >
+      Continue
+    </button>
+  );
+}
+```
+
+`usePixel` fora do `PixelProvider` lança:
+
+```text
+usePixel must be used within a PixelProvider.
+```
+
+## Next.js App Router
+
+- `PixelProvider` é um Client Component (`'use client'`).
+- O `layout.tsx` pode permanecer Server Component.
+- Envolva `children` com um componente intermediário `Providers`.
+- `usePixel` só em Client Components.
+
+## Lifecycle
+
+1. Estado inicial: `idle` → no efeito do cliente: `initializing`.
+2. Bootstrap via `bootstrapBemonyPixel` (singleton por `window` no `pixel-bemony`).
+3. Sucesso → `ready` + instância; falha → `error` + `Error` normalizado.
+4. Options são capturadas na montagem (`useRef`). Objetos inline a cada render **não** reinicializam.
+5. Mudança semântica das options após o mount: aviso em development; reinit dinâmico fora do MVP.
+
+### Strict Mode
+
+React 18+ Strict Mode (dev) faz mount → cleanup → mount. Estratégia:
+
+- **Ref-count** de ownership no módulo.
+- **Destroy adiado** (`setTimeout(0)`): o cleanup da primeira montagem agenda destroy; o remount imediato cancela o timer e reutiliza pending/instância do store do browser.
+- Não destruir no cleanup de forma síncrona (evita matar a segunda montagem).
+
+### Múltiplos Providers
+
+Na mesma `window`, vários `PixelProvider` **compartilham** a mesma instância bootstrapada (política alinhada ao singleton do `pixel-bemony`). Destroy global só quando o ref-count volta a 0.
+
+## SSR
+
+- Importar o pacote não acessa `window`/`document`.
+- Bootstrap só dentro de `useEffect` (cliente).
+- Render no servidor deixa status `idle` / `ready: false`.
+
+## Limitações do MVP
+
+Ainda **não** existem:
+
+- `useCustomer`, `useCheckout`, `useCatalog`, `useJourney`, `usePageContext`, `useTrack`
+- componentes declarativos de tracking / `PixelScript`
+- integração específica com Server Components / Suspense
+- reinit dinâmico por mudança de options
+- catálogo remoto / seleção automática de price
+- estado comercial duplicado no React
+
+Tipos avançados: importe de `@beworke/pixel-bemony` ou `@beworke/pixel-bemony/browser`.
+
+## Status UI
+
+```ts
+type PixelProviderStatus = 'idle' | 'initializing' | 'ready' | 'error';
+```
+
+`error` no Context é o status de falha do Provider (não confundir com `BemonyPixel.getState() === 'failed'`).

package/RELEASE_CANDIDATE.md

@@ -0,0 +1,32 @@
+# Release Candidate — `@beworke/pixel-bemony-react`
+
+## Status
+
+| Item | Decisão |
+|---|---|
+| Publish npm | **Sim** — RC pública para validação |
+| Versão | `0.1.0-rc.1` |
+| Naming | `@beworke/pixel-bemony-react` |
+| Tags npm | `rc` + `latest` |
+
+## Compatibilidade
+
+| Pacote | Intervalo |
+|---|---|
+| `@beworke/pixel-bemony` (peer) | `>=0.1.0-rc.1` |
+| `react` / `react-dom` | `>=18` |
+| Dependência no workspace | `workspace:*` (pnpm publish reescreve) |
+
+## Checklist
+
+1. `pnpm --filter @beworke/pixel-bemony-react lint`
+2. `pnpm --filter @beworke/pixel-bemony-react type-check`
+3. `pnpm --filter @beworke/pixel-bemony-react test`
+4. `pnpm --filter @beworke/pixel-bemony-react build`
+5. `pnpm --filter @beworke/pixel-bemony-react publish:rc`
+6. `npm view @beworke/pixel-bemony-react dist-tags` → `rc` e `latest` = `0.1.0-rc.1`
+
+## Fora desta RC
+
+- Versão estável `0.1.0` (sem sufixo)
+- Hooks avançados / SSR helpers extras

package/dist/index.cjs.js

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  PixelProvider: () => PixelProvider,
+  usePixel: () => usePixel
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/provider/PixelProvider.tsx
+var import_browser2 = require("@beworke/pixel-bemony/browser");
+var import_react2 = require("react");
+
+// src/provider/bootstrapOwnership.ts
+var import_browser = require("@beworke/pixel-bemony/browser");
+var ownerCount = 0;
+var destroyTimer = null;
+function acquireBootstrapOwnership() {
+  if (destroyTimer !== null) {
+    clearTimeout(destroyTimer);
+    destroyTimer = null;
+  }
+  ownerCount += 1;
+}
+function releaseBootstrapOwnership() {
+  ownerCount = Math.max(0, ownerCount - 1);
+  if (ownerCount > 0) {
+    return;
+  }
+  if (destroyTimer !== null) {
+    clearTimeout(destroyTimer);
+  }
+  destroyTimer = setTimeout(() => {
+    destroyTimer = null;
+    if (ownerCount === 0) {
+      void (0, import_browser.destroyBootstrappedBemonyPixel)().catch(() => {
+      });
+    }
+  }, 0);
+}
+function warnIfOptionsChanged(initial, next) {
+  if (initial === next) {
+    return;
+  }
+  console.warn?.(
+    "[PixelProvider] options mudaram ap\xF3s o mount. Reinit din\xE2mico est\xE1 fora do MVP; a inst\xE2ncia atual permanece."
+  );
+}
+
+// src/provider/normalizeError.ts
+function normalizeError(cause) {
+  if (cause instanceof Error) {
+    return cause;
+  }
+  return new Error(String(cause));
+}
+
+// src/provider/PixelContext.ts
+var import_react = require("react");
+var PixelContext = (0, import_react.createContext)(null);
+
+// src/provider/PixelProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function PixelProvider({
+  children,
+  options
+}) {
+  const optionsRef = (0, import_react2.useRef)(options);
+  const [pixel, setPixel] = (0, import_react2.useState)(null);
+  const [status, setStatus] = (0, import_react2.useState)("idle");
+  const [error, setError] = (0, import_react2.useState)(null);
+  (0, import_react2.useEffect)(() => {
+    warnIfOptionsChanged(optionsRef.current, options);
+  }, [options]);
+  (0, import_react2.useEffect)(() => {
+    let active = true;
+    acquireBootstrapOwnership();
+    setStatus("initializing");
+    setError(null);
+    const existing = (0, import_browser2.getBootstrappedBemonyPixel)();
+    if (existing && existing.getState() === "ready") {
+      setPixel(existing);
+      setStatus("ready");
+    }
+    const boot = (0, import_browser2.getBootstrappedBemonyPixelPending)() ?? (0, import_browser2.bootstrapBemonyPixel)(optionsRef.current);
+    boot.then((instance) => {
+      if (!active) {
+        return;
+      }
+      setPixel(instance);
+      setStatus("ready");
+      setError(null);
+    }).catch((cause) => {
+      if (!active) {
+        return;
+      }
+      setPixel(null);
+      setStatus("error");
+      setError(normalizeError(cause));
+    });
+    return () => {
+      active = false;
+      releaseBootstrapOwnership();
+    };
+  }, []);
+  const value = (0, import_react2.useMemo)(
+    () => ({
+      pixel,
+      status,
+      ready: status === "ready" && pixel !== null,
+      error
+    }),
+    [pixel, status, error]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PixelContext.Provider, { value, children });
+}
+
+// src/hooks/usePixel.ts
+var import_react3 = require("react");
+function usePixel() {
+  const value = (0, import_react3.useContext)(PixelContext);
+  if (!value) {
+    throw new Error("usePixel must be used within a PixelProvider.");
+  }
+  return value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PixelProvider,
+  usePixel
+});
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/provider/PixelProvider.tsx","../src/provider/bootstrapOwnership.ts","../src/provider/normalizeError.ts","../src/provider/PixelContext.ts","../src/hooks/usePixel.ts"],"sourcesContent":["export { PixelProvider } from './provider/PixelProvider';\nexport { usePixel } from './hooks/usePixel';\n\nexport type {\n  PixelContextValue,\n  PixelProviderProps,\n  PixelProviderStatus,\n  UsePixelResult,\n} from './types';\n\nexport type { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony/browser';\nexport type { BemonyPixel } from '@beworke/pixel-bemony';\n","'use client';\n\nimport {\n  bootstrapBemonyPixel,\n  getBootstrappedBemonyPixel,\n  getBootstrappedBemonyPixelPending,\n} from '@beworke/pixel-bemony/browser';\nimport type { BemonyPixel } from '@beworke/pixel-bemony';\nimport { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';\nimport type { PixelProviderProps, PixelProviderStatus } from '../types';\nimport {\n  acquireBootstrapOwnership,\n  releaseBootstrapOwnership,\n  warnIfOptionsChanged,\n} from './bootstrapOwnership';\nimport { normalizeError } from './normalizeError';\nimport { PixelContext } from './PixelContext';\n\nexport function PixelProvider({\n  children,\n  options,\n}: PixelProviderProps): ReactElement {\n  const optionsRef = useRef(options);\n  const [pixel, setPixel] = useState<BemonyPixel | null>(null);\n  const [status, setStatus] = useState<PixelProviderStatus>('idle');\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    warnIfOptionsChanged(optionsRef.current, options);\n  }, [options]);\n\n  useEffect(() => {\n    let active = true;\n    acquireBootstrapOwnership();\n    setStatus('initializing');\n    setError(null);\n\n    const existing = getBootstrappedBemonyPixel();\n    if (existing && existing.getState() === 'ready') {\n      setPixel(existing);\n      setStatus('ready');\n    }\n\n    const boot =\n      getBootstrappedBemonyPixelPending() ??\n      bootstrapBemonyPixel(optionsRef.current);\n\n    boot\n      .then(instance => {\n        if (!active) {\n          return;\n        }\n        setPixel(instance);\n        setStatus('ready');\n        setError(null);\n      })\n      .catch((cause: unknown) => {\n        if (!active) {\n          return;\n        }\n        setPixel(null);\n        setStatus('error');\n        setError(normalizeError(cause));\n      });\n\n    return () => {\n      active = false;\n      releaseBootstrapOwnership();\n    };\n  }, []);\n\n  const value = useMemo(\n    () => ({\n      pixel,\n      status,\n      ready: status === 'ready' && pixel !== null,\n      error,\n    }),\n    [pixel, status, error]\n  );\n\n  return (\n    <PixelContext.Provider value={value}>{children}</PixelContext.Provider>\n  );\n}\n","/**\n * Ownership compartilhado do bootstrap Bemony na mesma `window`.\n *\n * - Vários Providers / Strict Mode mount→cleanup→mount compartilham a instância.\n * - Destroy global só quando o ref-count volta a 0 (com defer para Strict Mode).\n */\n\nimport {\n  destroyBootstrappedBemonyPixel,\n  type BootstrapBemonyPixelOptions,\n} from '@beworke/pixel-bemony/browser';\n\nlet ownerCount = 0;\nlet destroyTimer: ReturnType<typeof setTimeout> | null = null;\n\n/** @internal — testes */\nexport function getBootstrapOwnerCountForTests(): number {\n  return ownerCount;\n}\n\n/** @internal — testes */\nexport function resetBootstrapOwnershipForTests(): void {\n  ownerCount = 0;\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n    destroyTimer = null;\n  }\n}\n\nexport function acquireBootstrapOwnership(): void {\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n    destroyTimer = null;\n  }\n  ownerCount += 1;\n}\n\n/**\n * Libera ownership. Se ninguém mais possui, agenda destroy após um tick\n * (cancela se Strict Mode remountar imediatamente).\n */\nexport function releaseBootstrapOwnership(): void {\n  ownerCount = Math.max(0, ownerCount - 1);\n  if (ownerCount > 0) {\n    return;\n  }\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n  }\n  destroyTimer = setTimeout(() => {\n    destroyTimer = null;\n    if (ownerCount === 0) {\n      void destroyBootstrappedBemonyPixel().catch(() => {\n        // cleanup isolado\n      });\n    }\n  }, 0);\n}\n\n/**\n * Options de montagem — o Provider não reage a mudanças de referência.\n * Em development, avisa se as options mudarem após o mount.\n */\nexport function warnIfOptionsChanged(\n  initial: BootstrapBemonyPixelOptions,\n  next: BootstrapBemonyPixelOptions\n): void {\n  if (initial === next) {\n    return;\n  }\n  // Development-only hint; safe no-op if console is unavailable.\n  console.warn?.(\n    '[PixelProvider] options mudaram após o mount. Reinit dinâmico está fora do MVP; a instância atual permanece.'\n  );\n}\n","export function normalizeError(cause: unknown): Error {\n  if (cause instanceof Error) {\n    return cause;\n  }\n  return new Error(String(cause));\n}\n","'use client';\n\nimport { createContext } from 'react';\nimport type { PixelContextValue } from '../types';\n\n/**\n * `null` = fora do Provider (usePixel lança).\n * Valor válido sempre vem do PixelProvider.\n */\nexport const PixelContext = createContext<PixelContextValue | null>(null);\n","'use client';\n\nimport { useContext } from 'react';\nimport { PixelContext } from '../provider/PixelContext';\nimport type { UsePixelResult } from '../types';\n\n/**\n * Consome a instância `BemonyPixel` do `PixelProvider`.\n * Deve ser usado apenas em Client Components.\n */\nexport function usePixel(): UsePixelResult {\n  const value = useContext(PixelContext);\n  if (!value) {\n    throw new Error('usePixel must be used within a PixelProvider.');\n  }\n  return value;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,IAAAA,kBAIO;AAEP,IAAAC,gBAAwE;;;ACDxE,qBAGO;AAEP,IAAI,aAAa;AACjB,IAAI,eAAqD;AAgBlD,SAAS,4BAAkC;AAChD,MAAI,iBAAiB,MAAM;AACzB,iBAAa,YAAY;AACzB,mBAAe;AAAA,EACjB;AACA,gBAAc;AAChB;AAMO,SAAS,4BAAkC;AAChD,eAAa,KAAK,IAAI,GAAG,aAAa,CAAC;AACvC,MAAI,aAAa,GAAG;AAClB;AAAA,EACF;AACA,MAAI,iBAAiB,MAAM;AACzB,iBAAa,YAAY;AAAA,EAC3B;AACA,iBAAe,WAAW,MAAM;AAC9B,mBAAe;AACf,QAAI,eAAe,GAAG;AACpB,eAAK,+CAA+B,EAAE,MAAM,MAAM;AAAA,MAElD,CAAC;AAAA,IACH;AAAA,EACF,GAAG,CAAC;AACN;AAMO,SAAS,qBACd,SACA,MACM;AACN,MAAI,YAAY,MAAM;AACpB;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,EACF;AACF;;;AC1EO,SAAS,eAAe,OAAuB;AACpD,MAAI,iBAAiB,OAAO;AAC1B,WAAO;AAAA,EACT;AACA,SAAO,IAAI,MAAM,OAAO,KAAK,CAAC;AAChC;;;ACHA,mBAA8B;AAOvB,IAAM,mBAAe,4BAAwC,IAAI;;;AHyEpE;AAhEG,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AACF,GAAqC;AACnC,QAAM,iBAAa,sBAAO,OAAO;AACjC,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAA6B,IAAI;AAC3D,QAAM,CAAC,QAAQ,SAAS,QAAI,wBAA8B,MAAM;AAChE,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,+BAAU,MAAM;AACd,yBAAqB,WAAW,SAAS,OAAO;AAAA,EAClD,GAAG,CAAC,OAAO,CAAC;AAEZ,+BAAU,MAAM;AACd,QAAI,SAAS;AACb,8BAA0B;AAC1B,cAAU,cAAc;AACxB,aAAS,IAAI;AAEb,UAAM,eAAW,4CAA2B;AAC5C,QAAI,YAAY,SAAS,SAAS,MAAM,SAAS;AAC/C,eAAS,QAAQ;AACjB,gBAAU,OAAO;AAAA,IACnB;AAEA,UAAM,WACJ,mDAAkC,SAClC,sCAAqB,WAAW,OAAO;AAEzC,SACG,KAAK,cAAY;AAChB,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AACA,eAAS,QAAQ;AACjB,gBAAU,OAAO;AACjB,eAAS,IAAI;AAAA,IACf,CAAC,EACA,MAAM,CAAC,UAAmB;AACzB,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AACA,eAAS,IAAI;AACb,gBAAU,OAAO;AACjB,eAAS,eAAe,KAAK,CAAC;AAAA,IAChC,CAAC;AAEH,WAAO,MAAM;AACX,eAAS;AACT,gCAA0B;AAAA,IAC5B;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,YAAQ;AAAA,IACZ,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,OAAO,WAAW,WAAW,UAAU;AAAA,MACvC;AAAA,IACF;AAAA,IACA,CAAC,OAAO,QAAQ,KAAK;AAAA,EACvB;AAEA,SACE,4CAAC,aAAa,UAAb,EAAsB,OAAe,UAAS;AAEnD;;;AIlFA,IAAAC,gBAA2B;AAQpB,SAAS,WAA2B;AACzC,QAAM,YAAQ,0BAAW,YAAY;AACrC,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,MAAM,+CAA+C;AAAA,EACjE;AACA,SAAO;AACT;","names":["import_browser","import_react","import_react"]}

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import { ReactNode, ReactElement } from 'react';
+import { BemonyPixel } from '@beworke/pixel-bemony';
+export { BemonyPixel } from '@beworke/pixel-bemony';
+import { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony/browser';
+export { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony/browser';
+
+/**
+ * Estado do Provider React (UI).
+ * Diferente de `BemonyPixel.getState()` (`failed` no wrapper).
+ * Aqui usamos `error` para falha de bootstrap no Context.
+ */
+type PixelProviderStatus = 'idle' | 'initializing' | 'ready' | 'error';
+type PixelContextValue = {
+    pixel: BemonyPixel | null;
+    status: PixelProviderStatus;
+    ready: boolean;
+    error: Error | null;
+};
+type PixelProviderProps = {
+    children: ReactNode;
+    /**
+     * Opções de bootstrap (`BootstrapBemonyPixelOptions`).
+     * Capturadas na montagem — mudanças posteriores não reinicializam (MVP).
+     */
+    options: BootstrapBemonyPixelOptions;
+};
+type UsePixelResult = PixelContextValue;
+
+declare function PixelProvider({ children, options, }: PixelProviderProps): ReactElement;
+
+/**
+ * Consome a instância `BemonyPixel` do `PixelProvider`.
+ * Deve ser usado apenas em Client Components.
+ */
+declare function usePixel(): UsePixelResult;
+
+export { type PixelContextValue, PixelProvider, type PixelProviderProps, type PixelProviderStatus, type UsePixelResult, usePixel };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode, ReactElement } from 'react';
+import { BemonyPixel } from '@beworke/pixel-bemony';
+export { BemonyPixel } from '@beworke/pixel-bemony';
+import { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony/browser';
+export { BootstrapBemonyPixelOptions } from '@beworke/pixel-bemony/browser';
+
+/**
+ * Estado do Provider React (UI).
+ * Diferente de `BemonyPixel.getState()` (`failed` no wrapper).
+ * Aqui usamos `error` para falha de bootstrap no Context.
+ */
+type PixelProviderStatus = 'idle' | 'initializing' | 'ready' | 'error';
+type PixelContextValue = {
+    pixel: BemonyPixel | null;
+    status: PixelProviderStatus;
+    ready: boolean;
+    error: Error | null;
+};
+type PixelProviderProps = {
+    children: ReactNode;
+    /**
+     * Opções de bootstrap (`BootstrapBemonyPixelOptions`).
+     * Capturadas na montagem — mudanças posteriores não reinicializam (MVP).
+     */
+    options: BootstrapBemonyPixelOptions;
+};
+type UsePixelResult = PixelContextValue;
+
+declare function PixelProvider({ children, options, }: PixelProviderProps): ReactElement;
+
+/**
+ * Consome a instância `BemonyPixel` do `PixelProvider`.
+ * Deve ser usado apenas em Client Components.
+ */
+declare function usePixel(): UsePixelResult;
+
+export { type PixelContextValue, PixelProvider, type PixelProviderProps, type PixelProviderStatus, type UsePixelResult, usePixel };

package/dist/index.esm.js

@@ -0,0 +1,128 @@
+// src/provider/PixelProvider.tsx
+import {
+  bootstrapBemonyPixel,
+  getBootstrappedBemonyPixel,
+  getBootstrappedBemonyPixelPending
+} from "@beworke/pixel-bemony/browser";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+// src/provider/bootstrapOwnership.ts
+import {
+  destroyBootstrappedBemonyPixel
+} from "@beworke/pixel-bemony/browser";
+var ownerCount = 0;
+var destroyTimer = null;
+function acquireBootstrapOwnership() {
+  if (destroyTimer !== null) {
+    clearTimeout(destroyTimer);
+    destroyTimer = null;
+  }
+  ownerCount += 1;
+}
+function releaseBootstrapOwnership() {
+  ownerCount = Math.max(0, ownerCount - 1);
+  if (ownerCount > 0) {
+    return;
+  }
+  if (destroyTimer !== null) {
+    clearTimeout(destroyTimer);
+  }
+  destroyTimer = setTimeout(() => {
+    destroyTimer = null;
+    if (ownerCount === 0) {
+      void destroyBootstrappedBemonyPixel().catch(() => {
+      });
+    }
+  }, 0);
+}
+function warnIfOptionsChanged(initial, next) {
+  if (initial === next) {
+    return;
+  }
+  console.warn?.(
+    "[PixelProvider] options mudaram ap\xF3s o mount. Reinit din\xE2mico est\xE1 fora do MVP; a inst\xE2ncia atual permanece."
+  );
+}
+
+// src/provider/normalizeError.ts
+function normalizeError(cause) {
+  if (cause instanceof Error) {
+    return cause;
+  }
+  return new Error(String(cause));
+}
+
+// src/provider/PixelContext.ts
+import { createContext } from "react";
+var PixelContext = createContext(null);
+
+// src/provider/PixelProvider.tsx
+import { jsx } from "react/jsx-runtime";
+function PixelProvider({
+  children,
+  options
+}) {
+  const optionsRef = useRef(options);
+  const [pixel, setPixel] = useState(null);
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    warnIfOptionsChanged(optionsRef.current, options);
+  }, [options]);
+  useEffect(() => {
+    let active = true;
+    acquireBootstrapOwnership();
+    setStatus("initializing");
+    setError(null);
+    const existing = getBootstrappedBemonyPixel();
+    if (existing && existing.getState() === "ready") {
+      setPixel(existing);
+      setStatus("ready");
+    }
+    const boot = getBootstrappedBemonyPixelPending() ?? bootstrapBemonyPixel(optionsRef.current);
+    boot.then((instance) => {
+      if (!active) {
+        return;
+      }
+      setPixel(instance);
+      setStatus("ready");
+      setError(null);
+    }).catch((cause) => {
+      if (!active) {
+        return;
+      }
+      setPixel(null);
+      setStatus("error");
+      setError(normalizeError(cause));
+    });
+    return () => {
+      active = false;
+      releaseBootstrapOwnership();
+    };
+  }, []);
+  const value = useMemo(
+    () => ({
+      pixel,
+      status,
+      ready: status === "ready" && pixel !== null,
+      error
+    }),
+    [pixel, status, error]
+  );
+  return /* @__PURE__ */ jsx(PixelContext.Provider, { value, children });
+}
+
+// src/hooks/usePixel.ts
+import { useContext } from "react";
+function usePixel() {
+  const value = useContext(PixelContext);
+  if (!value) {
+    throw new Error("usePixel must be used within a PixelProvider.");
+  }
+  return value;
+}
+export {
+  PixelProvider,
+  usePixel
+};
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider/PixelProvider.tsx","../src/provider/bootstrapOwnership.ts","../src/provider/normalizeError.ts","../src/provider/PixelContext.ts","../src/hooks/usePixel.ts"],"sourcesContent":["'use client';\n\nimport {\n  bootstrapBemonyPixel,\n  getBootstrappedBemonyPixel,\n  getBootstrappedBemonyPixelPending,\n} from '@beworke/pixel-bemony/browser';\nimport type { BemonyPixel } from '@beworke/pixel-bemony';\nimport { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';\nimport type { PixelProviderProps, PixelProviderStatus } from '../types';\nimport {\n  acquireBootstrapOwnership,\n  releaseBootstrapOwnership,\n  warnIfOptionsChanged,\n} from './bootstrapOwnership';\nimport { normalizeError } from './normalizeError';\nimport { PixelContext } from './PixelContext';\n\nexport function PixelProvider({\n  children,\n  options,\n}: PixelProviderProps): ReactElement {\n  const optionsRef = useRef(options);\n  const [pixel, setPixel] = useState<BemonyPixel | null>(null);\n  const [status, setStatus] = useState<PixelProviderStatus>('idle');\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    warnIfOptionsChanged(optionsRef.current, options);\n  }, [options]);\n\n  useEffect(() => {\n    let active = true;\n    acquireBootstrapOwnership();\n    setStatus('initializing');\n    setError(null);\n\n    const existing = getBootstrappedBemonyPixel();\n    if (existing && existing.getState() === 'ready') {\n      setPixel(existing);\n      setStatus('ready');\n    }\n\n    const boot =\n      getBootstrappedBemonyPixelPending() ??\n      bootstrapBemonyPixel(optionsRef.current);\n\n    boot\n      .then(instance => {\n        if (!active) {\n          return;\n        }\n        setPixel(instance);\n        setStatus('ready');\n        setError(null);\n      })\n      .catch((cause: unknown) => {\n        if (!active) {\n          return;\n        }\n        setPixel(null);\n        setStatus('error');\n        setError(normalizeError(cause));\n      });\n\n    return () => {\n      active = false;\n      releaseBootstrapOwnership();\n    };\n  }, []);\n\n  const value = useMemo(\n    () => ({\n      pixel,\n      status,\n      ready: status === 'ready' && pixel !== null,\n      error,\n    }),\n    [pixel, status, error]\n  );\n\n  return (\n    <PixelContext.Provider value={value}>{children}</PixelContext.Provider>\n  );\n}\n","/**\n * Ownership compartilhado do bootstrap Bemony na mesma `window`.\n *\n * - Vários Providers / Strict Mode mount→cleanup→mount compartilham a instância.\n * - Destroy global só quando o ref-count volta a 0 (com defer para Strict Mode).\n */\n\nimport {\n  destroyBootstrappedBemonyPixel,\n  type BootstrapBemonyPixelOptions,\n} from '@beworke/pixel-bemony/browser';\n\nlet ownerCount = 0;\nlet destroyTimer: ReturnType<typeof setTimeout> | null = null;\n\n/** @internal — testes */\nexport function getBootstrapOwnerCountForTests(): number {\n  return ownerCount;\n}\n\n/** @internal — testes */\nexport function resetBootstrapOwnershipForTests(): void {\n  ownerCount = 0;\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n    destroyTimer = null;\n  }\n}\n\nexport function acquireBootstrapOwnership(): void {\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n    destroyTimer = null;\n  }\n  ownerCount += 1;\n}\n\n/**\n * Libera ownership. Se ninguém mais possui, agenda destroy após um tick\n * (cancela se Strict Mode remountar imediatamente).\n */\nexport function releaseBootstrapOwnership(): void {\n  ownerCount = Math.max(0, ownerCount - 1);\n  if (ownerCount > 0) {\n    return;\n  }\n  if (destroyTimer !== null) {\n    clearTimeout(destroyTimer);\n  }\n  destroyTimer = setTimeout(() => {\n    destroyTimer = null;\n    if (ownerCount === 0) {\n      void destroyBootstrappedBemonyPixel().catch(() => {\n        // cleanup isolado\n      });\n    }\n  }, 0);\n}\n\n/**\n * Options de montagem — o Provider não reage a mudanças de referência.\n * Em development, avisa se as options mudarem após o mount.\n */\nexport function warnIfOptionsChanged(\n  initial: BootstrapBemonyPixelOptions,\n  next: BootstrapBemonyPixelOptions\n): void {\n  if (initial === next) {\n    return;\n  }\n  // Development-only hint; safe no-op if console is unavailable.\n  console.warn?.(\n    '[PixelProvider] options mudaram após o mount. Reinit dinâmico está fora do MVP; a instância atual permanece.'\n  );\n}\n","export function normalizeError(cause: unknown): Error {\n  if (cause instanceof Error) {\n    return cause;\n  }\n  return new Error(String(cause));\n}\n","'use client';\n\nimport { createContext } from 'react';\nimport type { PixelContextValue } from '../types';\n\n/**\n * `null` = fora do Provider (usePixel lança).\n * Valor válido sempre vem do PixelProvider.\n */\nexport const PixelContext = createContext<PixelContextValue | null>(null);\n","'use client';\n\nimport { useContext } from 'react';\nimport { PixelContext } from '../provider/PixelContext';\nimport type { UsePixelResult } from '../types';\n\n/**\n * Consome a instância `BemonyPixel` do `PixelProvider`.\n * Deve ser usado apenas em Client Components.\n */\nexport function usePixel(): UsePixelResult {\n  const value = useContext(PixelContext);\n  if (!value) {\n    throw new Error('usePixel must be used within a PixelProvider.');\n  }\n  return value;\n}\n"],"mappings":";AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,SAAS,WAAW,SAAS,QAAQ,gBAAmC;;;ACDxE;AAAA,EACE;AAAA,OAEK;AAEP,IAAI,aAAa;AACjB,IAAI,eAAqD;AAgBlD,SAAS,4BAAkC;AAChD,MAAI,iBAAiB,MAAM;AACzB,iBAAa,YAAY;AACzB,mBAAe;AAAA,EACjB;AACA,gBAAc;AAChB;AAMO,SAAS,4BAAkC;AAChD,eAAa,KAAK,IAAI,GAAG,aAAa,CAAC;AACvC,MAAI,aAAa,GAAG;AAClB;AAAA,EACF;AACA,MAAI,iBAAiB,MAAM;AACzB,iBAAa,YAAY;AAAA,EAC3B;AACA,iBAAe,WAAW,MAAM;AAC9B,mBAAe;AACf,QAAI,eAAe,GAAG;AACpB,WAAK,+BAA+B,EAAE,MAAM,MAAM;AAAA,MAElD,CAAC;AAAA,IACH;AAAA,EACF,GAAG,CAAC;AACN;AAMO,SAAS,qBACd,SACA,MACM;AACN,MAAI,YAAY,MAAM;AACpB;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,EACF;AACF;;;AC1EO,SAAS,eAAe,OAAuB;AACpD,MAAI,iBAAiB,OAAO;AAC1B,WAAO;AAAA,EACT;AACA,SAAO,IAAI,MAAM,OAAO,KAAK,CAAC;AAChC;;;ACHA,SAAS,qBAAqB;AAOvB,IAAM,eAAe,cAAwC,IAAI;;;AHyEpE;AAhEG,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AACF,GAAqC;AACnC,QAAM,aAAa,OAAO,OAAO;AACjC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA6B,IAAI;AAC3D,QAAM,CAAC,QAAQ,SAAS,IAAI,SAA8B,MAAM;AAChE,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,YAAU,MAAM;AACd,yBAAqB,WAAW,SAAS,OAAO;AAAA,EAClD,GAAG,CAAC,OAAO,CAAC;AAEZ,YAAU,MAAM;AACd,QAAI,SAAS;AACb,8BAA0B;AAC1B,cAAU,cAAc;AACxB,aAAS,IAAI;AAEb,UAAM,WAAW,2BAA2B;AAC5C,QAAI,YAAY,SAAS,SAAS,MAAM,SAAS;AAC/C,eAAS,QAAQ;AACjB,gBAAU,OAAO;AAAA,IACnB;AAEA,UAAM,OACJ,kCAAkC,KAClC,qBAAqB,WAAW,OAAO;AAEzC,SACG,KAAK,cAAY;AAChB,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AACA,eAAS,QAAQ;AACjB,gBAAU,OAAO;AACjB,eAAS,IAAI;AAAA,IACf,CAAC,EACA,MAAM,CAAC,UAAmB;AACzB,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AACA,eAAS,IAAI;AACb,gBAAU,OAAO;AACjB,eAAS,eAAe,KAAK,CAAC;AAAA,IAChC,CAAC;AAEH,WAAO,MAAM;AACX,eAAS;AACT,gCAA0B;AAAA,IAC5B;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,QAAQ;AAAA,IACZ,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,OAAO,WAAW,WAAW,UAAU;AAAA,MACvC;AAAA,IACF;AAAA,IACA,CAAC,OAAO,QAAQ,KAAK;AAAA,EACvB;AAEA,SACE,oBAAC,aAAa,UAAb,EAAsB,OAAe,UAAS;AAEnD;;;AIlFA,SAAS,kBAAkB;AAQpB,SAAS,WAA2B;AACzC,QAAM,QAAQ,WAAW,YAAY;AACrC,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,MAAM,+CAA+C;AAAA,EACjE;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@beworke/pixel-bemony-react",
+  "version": "0.1.0-rc.1",
+  "description": "Camada React/Next.js sobre @beworke/pixel-bemony — PixelProvider e usePixel",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE_CANDIDATE.md"
+  ],
+  "dependencies": {
+    "@beworke/pixel-bemony": "0.1.0-rc.1"
+  },
+  "peerDependencies": {
+    "@beworke/pixel-bemony": ">=0.1.0-rc.1",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^8.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "happy-dom": "^20.0.0",
+    "prettier": "^3.0.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src tests --ext .ts,.tsx",
+    "clean": "rimraf dist coverage",
+    "publish:rc": "pnpm publish --access public --tag rc --no-git-checks && npm dist-tag add @beworke/pixel-bemony-react@$(node -p \"require('./package.json').version\") latest"
+  }
+}