react-lgpd-consent 0.7.0 → 0.7.2

package/API.md

@@ -17,7 +17,9 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
 | `useOpenPreferencesModal`           | Hook       | Retorna uma função para abrir o modal de preferências de forma programática.    |
 | `openPreferencesModal`              | Função     | Versão da função acima para ser usada fora do contexto React.                   |
 | `ConsentGate`                       | Componente | Renderiza componentes filhos apenas se uma categoria de cookie for consentida.  |
-| `ConsentScriptLoader`               | Componente | Carrega scripts de terceiros (como Google Analytics) com base no consentimento. |
+| `ConsentScriptLoader`               | Componente | Carrega scripts de terceiros (como Google Analytics) com base no consentimento. Suporta Consent Mode v2 automático. |
+| `registerScript()`                  | Função     | Registra um script na fila global para execução condicional ao consentimento. Retorna função de cleanup. |
+| `RegisteredScript`                  | Tipo       | Interface para scripts registrados programaticamente (id, category, execute, priority, onConsentUpdate). |
 | `buildConsentStorageKey`            | Função     | (v0.5.2) Gera nomes de cookies `namespace__vX` a partir de namespace/versão.     |
 | `createGoogleAnalyticsIntegration`  | Função     | Factory para integração nativa com o Google Analytics.                           |
 | `createGoogleTagManagerIntegration` | Função     | Factory para integração nativa com o Google Tag Manager.                         |
@@ -28,6 +30,7 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
 | `createClarityIntegration`          | Função     | (v0.4.1) Integração nativa com Microsoft Clarity.                                |
 | `createIntercomIntegration`         | Função     | (v0.4.1) Integração nativa com Intercom (chat).                                  |
 | `createZendeskChatIntegration`      | Função     | (v0.4.1) Integração nativa com Zendesk Chat.                                     |
+| `createSuggestedIntegration`        | Função     | (v0.7.2) Cria integração customizada com categoria sugerida automaticamente.    |
 | `suggestCategoryForScript`          | Função     | (v0.4.1) Sugere categoria(s) LGPD para um script conhecido.                      |
 | `discoverRuntimeCookies`            | Função     | (v0.4.1) Descobre cookies em tempo real no navegador.                            |
 | `categorizeDiscoveredCookies`       | Função     | (v0.4.1) Categoriza cookies descobertos usando padrões LGPD.                     |
@@ -43,10 +46,63 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
 | `createSaaSIntegrations`            | Função     | (v0.4.1) Cria integrações comuns para SaaS.                                      |
 | `createCorporateIntegrations`       | Função     | (v0.4.1) Cria integrações comuns para ambientes corporativos.                    |
 | `INTEGRATION_TEMPLATES`             | Constante  | (v0.4.1) Presets com IDs essenciais/opcionais e categorias por tipo de negócio.  |
+| `SuggestedIntegrationConfig`        | Tipo       | (v0.7.2) Configuração para integração customizada com categoria sugerida.        |
 | `setDebugLogging`                   | Função     | Habilita/desabilita o logging de debug da biblioteca.                           |
 
 ---
 
+## ESM/CJS e Testes (Jest/Vitest)
+
+O pacote publica **dual build** (ESM + CJS) via `exports`:
+
+```json
+{
+  ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" },
+  "./core": { "import": "./dist/core.js", "require": "./dist/core.cjs" },
+  "./mui": { "import": "./dist/mui.js", "require": "./dist/mui.cjs" },
+  "./integrations": { "import": "./dist/integrations.js", "require": "./dist/integrations.cjs" }
+}
+```
+
+### Jest (CJS) com babel-jest
+
+```js
+// jest.config.cjs
+module.exports = {
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': ['babel-jest', { presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'] }],
+  },
+  transformIgnorePatterns: ['/node_modules/(?!react-lgpd-consent|@react-lgpd-consent)/'],
+}
+```
+
+### Vitest (Vite)
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    deps: {
+      inline: ['react-lgpd-consent', '@react-lgpd-consent/core', '@react-lgpd-consent/mui'],
+    },
+  },
+})
+```
+
+### Importações recomendadas
+
+```ts
+import { ConsentProvider } from 'react-lgpd-consent'
+import { ConsentProvider as ConsentProviderHeadless } from 'react-lgpd-consent/core'
+import { createGoogleAnalyticsIntegration } from 'react-lgpd-consent/integrations'
+```
+
+---
+
 ## Componentes
 
 ### `<ConsentProvider />`
@@ -74,7 +130,9 @@ function App() {
 | Prop | Tipo | Descrição |
 | --- | --- | --- |
 | `categories` | `ProjectCategoriesConfig` | **Obrigatório.** Fonte única de verdade sobre as categorias habilitadas; usada por UI, hooks e integrações. |
-| `texts` | `Partial<ConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
+| `texts` | `Partial<AdvancedConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
+| `language` | `'pt' \| 'en' \| 'es' \| 'fr' \| 'de' \| 'it'` | Resolve textos via i18n no Provider. |
+| `textVariant` | `'formal' \| 'casual' \| 'concise' \| 'detailed'` | Aplica variação de tom sobre os textos base. |
 | `designTokens` | `DesignTokens` | Ajuste visual granular (cores, spacing, tipografia, overlays). |
 | `blocking` | `boolean` | Ativa overlay bloqueante até o usuário decidir. Padrão: `false`. |
 | `blockingStrategy` | `'auto' \| 'provider' \| 'component'` | Controla quem desenha o overlay quando `blocking` está ativo. |
@@ -175,12 +233,35 @@ function MyComponent() {
 
 Gerencia o carregamento de scripts de terceiros (ex: Google Analytics) com base no consentimento do usuário. Veja o guia `INTEGRACOES.md` para mais detalhes.
 
+**Novidades v0.7.1:**
+- ✨ **Google Consent Mode v2 automático**: GA4 e GTM agora enviam `consent('default', 'denied')` no bootstrap e `consent('update', 'granted')` após consentimento
+- 🎯 **Sistema de fila com prioridade**: Scripts são executados ordenadamente (necessary → categoria → prioridade → timestamp)
+- 🔄 **Callbacks de atualização**: `onConsentUpdate` dispara quando preferências mudam
+
 ```tsx
-import { ConsentScriptLoader, createGoogleAnalyticsIntegration } from 'react-lgpd-consent'
+import { ConsentScriptLoader, createGoogleAnalyticsIntegration, registerScript } from 'react-lgpd-consent'
 
+// Uso padrão (Consent Mode v2 automático)
 const integrations = [createGoogleAnalyticsIntegration({ measurementId: 'G-XXXXXXXXXX' })]
+<ConsentScriptLoader integrations={integrations} />
+
+// Uso avançado: registro programático com prioridade
+const cleanup = registerScript({
+  id: 'custom-analytics',
+  category: 'analytics',
+  priority: 10, // Maior = executa primeiro
+  execute: async () => {
+    console.log('Script carregado!')
+  },
+  onConsentUpdate: ({ consented, preferences }) => {
+    if (preferences.analytics) {
+      console.log('Analytics habilitado via update!')
+    }
+  }
+})
 
-;<ConsentScriptLoader integrations={integrations} />
+// ℹ️ Estados da fila: pending → running → executed.
+// Scripts só reexecutam se allowReload=true; sempre use o cleanup ao desmontar.
 ```
 
 ---
@@ -561,7 +642,7 @@ Para customizações avançadas e tipagem, você pode importar os seguintes tipo
 - `CustomPreferencesModalProps`: Props passadas para um modal de preferências customizado.
 - `ConsentState`: Objeto que representa o estado completo do consentimento do usuário.
 - `ConsentPreferences`: Objeto com as preferências de consentimento para cada categoria.
-- `ConsentTexts`: Objeto com todos os textos customizáveis da UI.
+- `ConsentTexts`: Tipo base com textos essenciais da UI (pt-BR).
 - `Category`: Objeto que representa a definição de uma categoria de cookie.
 ### Exemplos de categorias (mínimo e completo)
 

package/CHANGELOG.md

@@ -1,5 +1,250 @@
 # Changelog
 
+## 0.7.2
+
+### Patch Changes
+
+- [#134](https://github.com/lucianoedipo/react-lgpd-consent/pull/134) [`44b885b`](https://github.com/lucianoedipo/react-lgpd-consent/commit/44b885b7c81f1cb5822e2dcfde2975e69e8d4893) Thanks [@github-actions](https://github.com/apps/github-actions)! - ### Correções
+  - 1d15920 fix: corrigir formatação da verificação de múltiplas versões do React
+
+  ### Funcionalidades
+  - d641639 feat: adicionar gerenciamento de eventos para categorias obrigatórias no CategoriesProvider
+  - b04c00b feat: add tests for CookieBanner, FloatingPreferencesButton, and PreferencesModal components
+  - b04c00b Introduce interactive changeset script for easier versioning in monorepos.
+
+  ### Refactors e compatibilidade
+  - ef2968a refactor: replace direct document and window references with globalThis for better compatibility
+  - ef2968a Updated scriptLoader, cookieDiscovery, cookieUtils, dataLayerEvents, developerGuidance, peerDepsCheck, scriptIntegrations, and scriptLoader files to use globalThis.document and globalThis.window.
+  - ef2968a Improved cookie handling functions to check for document and window availability using globalThis.
+  - ef2968a Enhanced tests to reference globalThis for consistency.
+  - ef2968a Cleaned up code formatting and comments for clarity.
+  - b04c00b Refactor coverage check script to use node imports.
+  - b04c00b Adjust TypeDoc script for ESM compatibility.
+  - 3af2fcb Fix path resolution in tsconfig for better module imports.
+
+  ### Testes
+  - b04c00b Implement tests for CookieBanner to verify rendering based on consent and debug mode.
+  - b04c00b Enhance FloatingPreferencesButton tests to check for localized text via props.
+  - b04c00b Extend PreferencesModal tests to cover temporary preference resets, active scripts rendering, and custom text application.
+
+  ### Documentação
+  - d430eef docs: atualizar instruções para agentes com visão geral do projeto e comandos essenciais
+  - d430eef Updated documentation to reflect changes in globalThis usage.
+  - d430eef Update API documentation to include new integration functions and ESM/CJS testing configurations.
+
+- Updated dependencies [[`44b885b`](https://github.com/lucianoedipo/react-lgpd-consent/commit/44b885b7c81f1cb5822e2dcfde2975e69e8d4893)]:
+  - @react-lgpd-consent/core@0.7.2
+  - @react-lgpd-consent/mui@0.7.2
+
+## 0.7.1
+
+### Patch Changes
+
+- [#133](https://github.com/lucianoedipo/react-lgpd-consent/pull/133) [`33bc0eb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/33bc0ebcb40ce65c70b02668d3c0a97efb1854f1) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - # 🧩 Fundamento Crítico de Consentimento — SUPER TASK v0.7.1
+
+  **Persistência + Loader + Consent Mode v2**
+
+  Esta release estabelece o **núcleo legal, técnico e funcional** da biblioteca react-lgpd-consent, garantindo um contrato sólido, seguro e auditável para uso institucional e governamental.
+
+  ***
+
+  ## 🔹 Bloco A — Persistência de Consentimento por Cookie
+
+  ### ✨ API Consolidada de Persistência
+
+  Nova API completa no `ConsentProvider`:
+
+  ```typescript
+  <ConsentProvider
+    cookie={{
+      name: 'lgpd-consent',
+      domain: '.example.com',  // Compartilha entre subdomínios
+      path: '/',
+      sameSite: 'Lax',        // Default seguro
+      secure: true,            // Auto em HTTPS
+      maxAge: 31536000,       // Segundos (substitui maxAgeDays)
+    }}
+  >
+  ```
+
+  **Regras Implementadas:**
+  - ✅ Defaults seguros: `SameSite=Lax`, `Secure=true` em HTTPS
+  - ✅ Categoria `necessary` **sempre forçada como true**
+  - ✅ Nenhuma gravação de cookie durante SSR
+  - ✅ Suporte completo a subdomínios via `domain`
+  - ✅ Nova opção `maxAge` (segundos, padrão moderno)
+  - ✅ Opção `maxAgeDays` deprecated mas mantida para compatibilidade
+
+  **Ambientes Suportados:**
+  - ✅ `localhost` (desenvolvimento)
+  - ✅ `dev` / `staging` (domínios customizados)
+  - ✅ `production` (HTTPS obrigatório)
+  - ✅ Comportamento **independente de NODE_ENV**
+
+  ***
+
+  ## 🔹 Bloco B — ConsentScriptLoader com Bloqueio Real
+
+  ### 🚫 Contrato de Bloqueio Garantido
+
+  > **Nenhum script não necessário executa antes do consentimento correspondente.**
+
+  ### ✨ Sistema de Fila e Priorização
+
+  Implementado `ConsentScriptLoader` com:
+
+  ```typescript
+  registerScript({
+    id: 'google-analytics',
+    category: 'analytics',
+    priority: 1, // Ordem de execução
+    execute: () => {
+      // Seu script aqui
+    },
+    onConsentUpdate: (granted) => {
+      // Reagir a mudanças de consentimento
+    },
+  })
+  ```
+
+  **Recursos Implementados:**
+  - ✅ **Fila interna de execução** com ordenação por:
+    - 1. Categoria (`necessary` → `analytics` → `marketing`, etc.)
+    - 2. Prioridade (numérica)
+    - 3. Timestamp (ordem de registro)
+  - ✅ Scripts `necessary` executam **imediatamente**
+  - ✅ Scripts de outras categorias aguardam **consentimento explícito**
+  - ✅ Suporte a `onConsentUpdate` para reconfiguração dinâmica
+  - ✅ Snapshot de consentimento para scripts que precisam do estado atual
+  - ✅ **Otimização anti-duplicação**: integrações não são reexecutadas a cada render quando criadas inline (ex.: `integrations={[createGoogleAnalyticsIntegration(...)]}`). Sistema mantém hash estrutural para detectar mudanças reais e prevenir múltiplas inicializações do mesmo script.
+
+  **Observabilidade em DEV:**
+  - ✅ Logs detalhados de ordem de execução
+  - ✅ Indicação clara de categoria liberada
+  - ✅ Rastreamento de status de cada script
+  - ⚠️ **Silencioso em produção** (performance otimizada)
+
+  ***
+
+  ## 🔹 Bloco C — Integração Nativa Google Consent Mode v2
+
+  ### 🎯 Implementação Automática
+
+  **Zero configuração manual necessária!**
+
+  ```typescript
+  import { createGoogleAnalyticsIntegration } from '@react-lgpd-consent/core'
+
+  const ga4 = createGoogleAnalyticsIntegration({
+    measurementId: 'G-XXXXXXXXXX'
+  })
+
+  <ConsentScriptLoader integrations={[ga4]} />
+  ```
+
+  **O que a biblioteca faz automaticamente:**
+  1. ✅ Inicializa `dataLayer` se não existir
+  2. ✅ Define `gtag('consent', 'default', denied)` **antes** de qualquer tag
+  3. ✅ Mapeia categorias corretamente:
+     - `analytics` → `analytics_storage`
+     - `marketing` → `ad_storage`, `ad_user_data`, `ad_personalization`
+  4. ✅ Envia `gtag('consent', 'update')` quando usuário escolhe preferências
+  5. ✅ Dispara eventos de ciclo de vida:
+     ```javascript
+     { event: 'consent_initialized' }
+     { event: 'consent_updated', preferences: {...} }
+     ```
+
+  **Factories Implementadas:**
+  - ✅ `createGoogleAnalyticsIntegration` (GA4)
+  - ✅ `createGoogleTagManagerIntegration` (GTM)
+  - ✅ Suporte a `bootstrap()` para inicialização pré-consentimento
+  - ✅ Suporte a `onConsentUpdate()` para reconfiguração dinâmica
+
+  ### 🔒 Ordem de Inicialização Segura
+
+  Fluxo garantido pela implementação:
+
+  ```
+  1. dataLayer criado
+  2. gtag('consent', 'default', denied)
+  3. Loader bloqueia tags
+  4. Usuário consente
+  5. gtag('consent', 'update', granted/denied)
+  6. Tags disparam conforme consentimento
+  ```
+
+  ### ⚡ Compatibilidade Next.js (SSR)
+  - ✅ Nenhum acesso a `window` fora de `useEffect`
+  - ✅ App Router (Next.js 13+)
+  - ✅ Pages Router (Next.js 12+)
+  - ✅ **Zero hydration mismatch**
+  - ✅ Estratégia de renderização: `client-only` quando necessário
+
+  ***
+
+  ## 🆕 Novas APIs Públicas
+
+  ### Core Package (`@react-lgpd-consent/core`):
+
+  ```typescript
+  // Registro de scripts
+  registerScript(config: RegisteredScript): void
+
+  // Factories de integrações
+  createGoogleAnalyticsIntegration(config): ScriptIntegration
+  createGoogleTagManagerIntegration(config): ScriptIntegration
+
+  // Utilitários de cookie
+  readConsentCookie(name?: string): ConsentState | null
+  writeConsentCookie(state: ConsentState, options?: CookieOptions): void
+
+  // Novos tipos
+  type RegisteredScript = { ... }
+  type ScriptIntegration = { ... }
+  interface LoadScriptOptions = { ... }
+  ```
+
+  ***
+
+  ## 📚 Documentação Atualizada
+  - ✅ **API.md** - Novas APIs de `registerScript` e Consent Mode v2
+  - ✅ **INTEGRACOES.md** - Guias completos de GA4, GTM, Facebook Pixel
+  - ✅ **MIGRATION.md** - Guia de migração v0.7.0 → v0.7.1
+  - ✅ **SUPER_TASK_VALIDATION.md** - Relatório técnico de validação completo
+
+  ***
+
+  ## 🔄 Breaking Changes
+
+  **Nenhum!** Esta release é 100% backward-compatible:
+  - ✅ Opção `maxAgeDays` deprecated mas funcional
+  - ✅ Comportamento padrão preservado
+  - ✅ APIs antigas continuam funcionando
+  - ✅ Migração gradual suportada
+
+  ***
+
+  ## 🎯 Melhorias Complementares
+
+  ### Sistema de i18n para Diagnósticos
+
+  Sistema básico de internacionalização para mensagens de peer dependencies:
+  - ✅ Suporte a pt-BR (padrão) e en
+  - ✅ API para customização: `setPeerDepsLocale()`, `setPeerDepsMessages()`
+  - ✅ Mensagens extraídas para constantes (melhor manutenibilidade)
+
+  ### Refatorações e Otimizações
+  - ✅ Strings de mensagens extraídas para constantes
+  - ✅ Separação de concerns (lógica vs conteúdo)
+  - ✅ Type safety aprimorado em toda API
+  - ✅ Performance otimizada (sem logs em produção)
+  - ✅ **Fix crítico**: Prevenção de reexecução de integrações a cada render quando `integrations` prop muda referência (inline array). Sistema agora usa hash estrutural para detectar mudanças reais e manter scripts já registrados estáveis.
+
+- Updated dependencies [[`33bc0eb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/33bc0ebcb40ce65c70b02668d3c0a97efb1854f1)]:
+  - @react-lgpd-consent/core@0.7.1
+  - @react-lgpd-consent/mui@0.7.1
+
 ## 0.7.0
 
 ### Minor Changes
@@ -153,7 +398,7 @@
   - **Correção crítica**: `loadScript` agora aguarda dinamicamente o consentimento em vez de rejeitar imediatamente, permitindo que scripts carreguem quando preferências mudarem
   - Cleanup automático do registro ao completar/falhar carregamento
   - Adicionados testes extensivos: `ConsentScriptLoader.strictmode.test.tsx` e `scriptLoader.strictmode.test.ts`
-  - Documentação completa em `docs/REACT19-STRICTMODE.md`
+  - Documentação completa em `REACT19-STRICTMODE.md`
   - Todos os 302 testes passando, incluindo 5 novos testes de StrictMode
 
   **Breaking Changes:** Nenhuma - totalmente retrocompatível

package/INTEGRACOES.md

@@ -6,6 +6,42 @@ A biblioteca oferece integrações nativas para as ferramentas mais comuns, elim
 
 O componente `ConsentScriptLoader` gerencia o carregamento desses scripts automaticamente, disparando-os apenas quando o usuário concede consentimento para a categoria correspondente.
 
+### ✅ Regras de Configuração (RN)
+
+- **Categoria padrão com override**: cada integração define uma categoria padrão, mas o consumidor pode sobrescrever via `category` no config.
+- **Config obrigatória**: se um campo obrigatório estiver vazio (ex.: `measurementId`, `containerId`, `pixelId`), a integração **não executa**. Em **dev** é logado erro; em **prod** não há log.
+- **DataLayer**: se `globalThis.window.dataLayer` não existir, a biblioteca cria `[]`; se existir e tiver `push`, usa como está; se existir sem `push`, não sobrescreve e avisa em dev.
+
+### ✨ Novidades v0.7.1
+
+- **🎯 Google Consent Mode v2 Automático**: GA4 e GTM agora implementam Consent Mode v2 automaticamente:
+  - `bootstrap`: Seta `consent('default', 'denied')` antes de qualquer carregamento
+  - `onConsentUpdate`: Envia `consent('update', 'granted')` quando usuário consente
+  - Zero configuração manual necessária!
+
+- **🔄 Sistema de Fila com Prioridade**: Scripts são executados ordenadamente:
+  1. Categoria `necessary` sempre primeiro
+  2. Dentro da mesma categoria: maior `priority` primeiro
+  3. Mesmo priority: ordem de registro (timestamp)
+
+- **📝 API `registerScript()`**: Registre scripts programaticamente fora do JSX:
+
+  ```tsx
+  import { registerScript } from 'react-lgpd-consent'
+
+  const cleanup = registerScript({
+    id: 'my-script',
+    category: 'analytics',
+    priority: 5,
+    execute: async () => {
+      /* carrega script */
+    },
+    onConsentUpdate: ({ preferences }) => {
+      /* reage a mudanças */
+    },
+  })
+  ```
+
 > 💡 **Procurando exemplos práticos?** Veja [RECIPES.md](../../RECIPES.md) para receitas passo a passo de Google Consent Mode v2, Next.js App Router e CSP/nonce.
 
 ## 🎯 Integrações Nativas Disponíveis
@@ -15,6 +51,7 @@ O componente `ConsentScriptLoader` gerencia o carregamento desses scripts automa
 - **Categoria**: `analytics`
 - **Função**: `createGoogleAnalyticsIntegration(config)`
 - **Descrição**: Integração completa com o Google Analytics 4. Suporta `measurementId` e configurações adicionais para o `gtag`.
+- **✨ Novo v0.7.1**: Google Consent Mode v2 automático (sem configuração manual)
 
 ```tsx
 import { createGoogleAnalyticsIntegration, ConsentScriptLoader } from 'react-lgpd-consent'
@@ -27,20 +64,28 @@ const integrations = [
 ]
 
 <ConsentScriptLoader integrations={integrations} />
+// ✅ Consent Mode v2 implementado automaticamente:
+// - bootstrap: consent('default', 'denied') antes do script
+// - onConsentUpdate: consent('update', 'granted') após consentimento
 ```
 
 ### 2. Google Tag Manager (GTM)
 
 - **Categoria**: `analytics`
 - **Função**: `createGoogleTagManagerIntegration(config)`
-- **Descrição**: Carrega o container do Google Tag Manager. Suporta `gtmId` e `dataLayerName`.
+- **Descrição**: Carrega o container do Google Tag Manager. Suporta `containerId` (ou `gtmId` legado) e `dataLayerName`.
+- **✨ Novo v0.7.1**: Google Consent Mode v2 automático com dataLayer customizado
 
 ```tsx
 import { createGoogleTagManagerIntegration } from 'react-lgpd-consent'
 
 const integrations = [
-  createGoogleTagManagerIntegration({ gtmId: 'GTM-XXXXXXX' })
+  createGoogleTagManagerIntegration({
+    containerId: 'GTM-XXXXXXX',
+    dataLayerName: 'dataLayer', // opcional
+  }),
 ]
+// ✅ Consent Mode v2 no dataLayer customizado automaticamente
 ```
 
 ### 3. Facebook Pixel
@@ -52,9 +97,7 @@ const integrations = [
 ```tsx
 import { createFacebookPixelIntegration } from 'react-lgpd-consent'
 
-const integrations = [
-  createFacebookPixelIntegration({ pixelId: 'YOUR_PIXEL_ID', autoTrack: true })
-]
+const integrations = [createFacebookPixelIntegration({ pixelId: 'YOUR_PIXEL_ID', autoTrack: true })]
 ```
 
 ### 4. Hotjar
@@ -136,13 +179,18 @@ const integrations = [createUserWayIntegration({ accountId: 'USERWAY_ACCOUNT_ID'
 Para simplificar a configuração de múltiplas integrações, a biblioteca oferece templates e funções de ajuda.
 
 - `suggestCategoryForScript(name: string)`: Sugere a categoria LGPD apropriada para um nome de script conhecido.
+- `createSuggestedIntegration(config)`: Cria integração customizada com categoria sugerida automaticamente (pode sobrescrever com `category`).
 - `createECommerceIntegrations`, `createSaaSIntegrations`, `createCorporateIntegrations`: Templates de negócio que agrupam as integrações mais comuns para cada setor.
 - `INTEGRATION_TEMPLATES`: Constante com presets de IDs e categorias para cada template.
 
 ### Exemplo de Template (E-commerce)
 
 ```tsx
-import { ConsentProvider, ConsentScriptLoader, createECommerceIntegrations } from 'react-lgpd-consent'
+import {
+  ConsentProvider,
+  ConsentScriptLoader,
+  createECommerceIntegrations,
+} from 'react-lgpd-consent'
 
 function App() {
   const integrations = createECommerceIntegrations({
@@ -160,6 +208,19 @@ function App() {
 }
 ```
 
+### Exemplo de integração sugerida (custom)
+
+```tsx
+import { createSuggestedIntegration } from 'react-lgpd-consent'
+
+const integrations = [
+  createSuggestedIntegration({
+    id: 'custom-chat',
+    src: 'https://example.com/chat.js',
+  }),
+]
+```
+
 ---
 
 ## 🔎 Descoberta Automática de Cookies (Experimental v0.4.1)
@@ -185,6 +246,7 @@ categorizeDiscoveredCookies(discovered, true)
 ## 🧱 Nota SSR/Next.js (App Router)
 
 Para evitar hydration mismatch e vazamento de scripts:
+
 - Coloque o `ConsentProvider` dentro de um Client Component e carregue-o com `dynamic(..., { ssr: false })` a partir do `RootLayout` (Server Component).
 - Use o `ConsentScriptLoader` para carregar GTM/GA4 somente após consentimento e inicialize o Consent Mode v2 com `gtag('consent','default', denied)` antes de qualquer script.
 - Consulte a seção “SSR/Next.js (App Router) — Padrões seguros” em `QUICKSTART.md` para ordem dos provedores/estilos (MUI/Emotion) e checklist SSR.
@@ -211,6 +273,12 @@ interface ScriptIntegration {
 
 A partir da versão **0.4.5**, a biblioteca dispara automaticamente eventos padronizados no `dataLayer` para facilitar rastreamento, auditoria LGPD e integrações com o Google Tag Manager.
 
+### Comportamento do `dataLayer`
+
+- Se `globalThis.window.dataLayer` não existir, a biblioteca cria `[]`.
+- Se existir e tiver `push`, o array/objeto é usado como está.
+- Se existir sem `push`, a biblioteca não sobrescreve e avisa em dev.
+
 ### Eventos Disponíveis
 
 #### 1. `consent_initialized`
@@ -218,6 +286,7 @@ A partir da versão **0.4.5**, a biblioteca dispara automaticamente eventos padr
 Disparado quando o sistema de consentimento é inicializado (após hidratação).
 
 **Payload:**
+
 ```typescript
 {
   event: 'consent_initialized',
@@ -232,6 +301,7 @@ Disparado quando o sistema de consentimento é inicializado (após hidratação)
 ```
 
 **Exemplo de uso no GTM:**
+
 - **Tipo de acionador**: Evento personalizado
 - **Nome do evento**: `consent_initialized`
 - **Variáveis**: `{{categories.analytics}}`, `{{categories.marketing}}`, etc.
@@ -241,6 +311,7 @@ Disparado quando o sistema de consentimento é inicializado (após hidratação)
 Disparado sempre que o usuário atualiza suas preferências de consentimento.
 
 **Payload:**
+
 ```typescript
 {
   event: 'consent_updated',
@@ -257,6 +328,7 @@ Disparado sempre que o usuário atualiza suas preferências de consentimento.
 ```
 
 **Exemplo de uso no GTM:**
+
 - **Tipo de acionador**: Evento personalizado
 - **Nome do evento**: `consent_updated`
 - **Condição**: `{{changed_categories}}` contém `analytics`
@@ -313,7 +385,7 @@ Crie uma tag para registrar mudanças de consentimento em um sistema de auditori
     categories: {{DLV - Consent Categories}},
     changed: {{DLV - Changed Categories}}
   };
-  
+
   // Enviar para seu sistema de auditoria
   fetch('/api/consent-audit', {
     method: 'POST',
@@ -336,9 +408,9 @@ const handleCustomUpdate = () => {
   const newPreferences = {
     necessary: true,
     analytics: true,
-    marketing: false
+    marketing: false,
   }
-  
+
   pushConsentUpdatedEvent(newPreferences, 'programmatic')
 }
 ```
@@ -350,7 +422,7 @@ import type {
   ConsentEvent,
   ConsentEventOrigin,
   ConsentInitializedEvent,
-  ConsentUpdatedEvent
+  ConsentUpdatedEvent,
 } from 'react-lgpd-consent'
 
 // Origem da ação
@@ -389,7 +461,6 @@ interface ConsentUpdatedEvent {
 | Live Chat          | `functional`          | Funcionalidade de suporte        |
 | YouTube/Vimeo      | `social`              | Conteúdo de redes sociais        |
 
-
 ---
 
 ## 🆕 Recursos Avançados v0.7.0
@@ -402,7 +473,7 @@ Integre sistemas de auditoria monitorando eventos de consentimento:
 import { ConsentProvider, ConsentScriptLoader } from 'react-lgpd-consent'
 import { googleAnalytics4Integration } from './integrations'
 
-<ConsentProvider
+;<ConsentProvider
   categories={{ enabledCategories: ['analytics', 'marketing'] }}
   onConsentInit={(state) => {
     // Disparado na inicialização (útil para analytics)
@@ -411,19 +482,19 @@ import { googleAnalytics4Integration } from './integrations'
   onConsentChange={(current, previous) => {
     // Disparado em toda mudança de preferências
     console.log('Mudança:', { current, previous })
-    
+
     // Exemplo: disparar evento no dataLayer
-    window.dataLayer?.push({
+    globalThis.window?.dataLayer?.push({
       event: 'consent_preferences_updated',
       consent_analytics: current.preferences.analytics,
-      consent_marketing: current.preferences.marketing
+      consent_marketing: current.preferences.marketing,
     })
   }}
   onAuditLog={(entry) => {
     // Enviar para backend de compliance
     fetch('/api/consent-audit', {
       method: 'POST',
-      body: JSON.stringify(entry)
+      body: JSON.stringify(entry),
     })
   }}
 >
@@ -460,6 +531,7 @@ const customConfig = createAnpdCategories({
 ```
 
 **Vantagens dos presets:**
+
 - ✅ Conformidade com diretrizes ANPD
 - ✅ Nomes e descrições em pt-BR revisadas
 - ✅ Tipagem forte para evitar erros

package/QUICKSTART.en.md

@@ -273,13 +273,13 @@ function MyComponent() {
 }
 ```
 
-### Global: `window.openPreferencesModal` (for plain JS)
+### Global: `globalThis.window.openPreferencesModal` (for plain JS)
 
 ```html
-<button onclick="window.openPreferencesModal?.()">Configure cookies</button>
+<button onclick="globalThis.window?.openPreferencesModal?.()">Configure cookies</button>
 
 <script>
-  if (typeof window.openPreferencesModal === 'function') {
+  if (typeof globalThis.window?.openPreferencesModal === 'function') {
     console.log('Consent system available')
   }
 </script>

package/QUICKSTART.md

@@ -257,7 +257,13 @@ function BootstrapConsentMode() {
   React.useEffect(() => {
     const w = window as any
     w.dataLayer = w.dataLayer ?? []
-    w.gtag = w.gtag ?? ((...args: any[]) => w.dataLayer.push(args))
+    w.gtag =
+      w.gtag ??
+      ((...args: any[]) => {
+        if (typeof w.dataLayer?.push === 'function') {
+          w.dataLayer.push(args)
+        }
+      })
     w.gtag('consent', 'default', {
       ad_storage: 'denied',
       ad_user_data: 'denied',
@@ -486,7 +492,11 @@ function ComplianceWrapper({ children }: { children: React.ReactNode }) {
       }}
       onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
         console.info('[consent] versão atualizada', { previousKey, nextKey })
-        window.dataLayer?.push({ event: 'consent_version_bumped', previousKey, nextKey })
+        globalThis.window?.dataLayer?.push({
+          event: 'consent_version_bumped',
+          previousKey,
+          nextKey,
+        })
         localStorage.removeItem('marketing-optins')
         resetConsent()
       }}
@@ -948,24 +958,24 @@ function MeuComponente() {
 }
 ```
 
-### window.openPreferencesModal (JavaScript Puro)
+### globalThis.window.openPreferencesModal (JavaScript Puro)
 
 ```html
 <!-- Em templates HTML, emails ou widgets externos -->
-<button onclick="window.openPreferencesModal?.()">Configurar Cookies</button>
+<button onclick="globalThis.window?.openPreferencesModal?.()">Configurar Cookies</button>
 
 <script>
   // Ou em JavaScript puro
   function abrirConfiguracoesCookies() {
-    if (window.openPreferencesModal) {
-      window.openPreferencesModal()
+    if (globalThis.window?.openPreferencesModal) {
+      globalThis.window.openPreferencesModal()
     } else {
       console.warn('Sistema de consentimento não carregado')
     }
   }
 
   // Verificar se função está disponível
-  if (typeof window.openPreferencesModal === 'function') {
+  if (typeof globalThis.window?.openPreferencesModal === 'function') {
     console.log('✅ Sistema de consentimento disponível')
   }
 </script>

package/README.en.md

@@ -76,7 +76,7 @@ function Analytics() {
       src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
       strategy="afterInteractive"
     >
-      {`window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
+      {`globalThis.window && (globalThis.window.dataLayer = globalThis.window.dataLayer || []); function gtag(){ if (typeof globalThis.window?.dataLayer?.push === 'function') { globalThis.window.dataLayer.push(arguments) } } gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
     </ConsentScriptLoader>
   )
 }
@@ -174,4 +174,3 @@ MIT © Luciano Edipo — see the `LICENSE` file.
 ---
 
 If you want the Portuguese README, see `README.md` in the same package.
-

package/README.md

@@ -13,7 +13,7 @@ Gerenciamento de consentimento de cookies em conformidade com a LGPD — pacote
 
 ## Descrição
 
-`react-lgpd-consent` é o pacote agregador compatível com versões anteriores (v0.4.x → v0.5.x). Ele re-exporta os componentes prontos em MUI e facilita a migração. Para projetos mais otimizados, considere importar diretamente `@react-lgpd-consent/core` (headless) ou `@react-lgpd-consent/mui` (componentes MUI).
+`react-lgpd-consent` é o pacote agregador compatível com versões anteriores (v0.4.x → v0.5.x). Ele re-exporta os componentes prontos em MUI e facilita a migração. Para projetos mais otimizados, considere importar diretamente `@react-lgpd-consent/core` (headless) ou `@react-lgpd-consent/mui/ui` (apenas UI, sem re-export do core).
 
 Principais características:
 
@@ -76,7 +76,7 @@ function Analytics() {
       src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
       strategy="afterInteractive"
     >
-      {`window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
+      {`globalThis.window && (globalThis.window.dataLayer = globalThis.window.dataLayer ?? []); function gtag(){ if (typeof globalThis.window?.dataLayer?.push === 'function') { globalThis.window.dataLayer.push(arguments) } } gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
     </ConsentScriptLoader>
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lgpd-consent",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Biblioteca de consentimento LGPD, integrações nativas e sistema extensível para React.",
   "keywords": [
     "lgpd",
@@ -94,8 +94,8 @@
     }
   },
   "dependencies": {
-    "@react-lgpd-consent/core": "^0.7.0",
-    "@react-lgpd-consent/mui": "^0.7.0"
+    "@react-lgpd-consent/core": "^0.7.2",
+    "@react-lgpd-consent/mui": "^0.7.2"
   },
   "size-limit": [
     {
@@ -117,7 +117,7 @@
       "name": "Complete Package Import",
       "path": "dist/index.js",
       "import": "{ ConsentProvider, useConsent, ConsentScriptLoader }",
-      "limit": "70 KB"
+      "limit": "80 KB"
     }
   ],
   "scripts": {