react-lgpd-consent 0.4.1 → 0.4.4

package/CHANGELOG.md

@@ -4,9 +4,109 @@ Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
 
 O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/), e este projeto segue [Semantic Versioning](https://semver.org/lang/pt-BR/).
 
+## [0.4.4] - 2025-10-06 — Correções de CI/CD e Publicação
+
+### 🔧 **Correções de CI/CD**
+
+- **Workflow de Publicação npm**: Corrigido bug que impedia publicação mesmo quando tag estava na `main`
+  - **Problema**: `git fetch --depth=1` limitava histórico e falhava verificação de ancestralidade
+  - **Solução**: Removido `--depth=1` do fetch, aproveitando `fetch-depth: 0` do checkout
+  - **Impacto**: Tags criadas após merge para `main` agora são publicadas corretamente no npm
+
+### 📊 **Integração com Codecov**
+
+- **Upload de Coverage**: Adicionado `codecov/codecov-action@v5` ao workflow CI
+  - Envia relatórios de cobertura automaticamente para Codecov
+  - Token configurado via `secrets.CODECOV_TOKEN`
+  - Integração com badge de coverage no README
+
+### 📚 **Documentação**
+
+- **Badges**: Badge de coverage já configurado no README (v0.4.3) agora recebe dados em tempo real
+- **Workflows**: Documentação inline sobre fetch depth e verificação de ancestralidade
+
+## [0.4.3] - 2025-10-06 — Otimizações de Performance e Qualidade
+
+### 🚀 **Melhorias de Performance**
+
+- **React.memo**: Adicionado memoização em componentes puros (`Branding`, `FloatingPreferencesButton`)
+- **useMemo**: Otimizado cálculo de `positionStyles` no `FloatingPreferencesButton`
+- **Lazy Loading Expandido**: `FloatingPreferencesButton` agora é carregado sob demanda
+- **Logger em Produção**: `warn()`, `info()`, `debug()` suprimidos em `NODE_ENV=production`
+  - Reduz overhead em bundle de produção
+  - `error()` permanece ativo para debugging crítico
+
+### 🐛 **Correções Críticas**
+
+- **ConsentProvider Suspense Bug**: Corrigido crash silencioso quando `consented=true`
+  - Adicionado `<React.Suspense>` ausente ao redor do `FloatingPreferencesButton` lazy
+  - Sintoma: Provider renderizava `<div />` vazio ao invés de `children`
+  - Impacto: Testes com `initialState.consented=true` agora passam
+
+### 🧪 **Testes de Acessibilidade (A11y)**
+
+- **jest-axe**: Integração completa com validação WCAG automática
+- **CookieBanner.a11y.test.tsx**: 3 cenários de acessibilidade validados
+- **PreferencesModal.a11y.test.tsx**: 3 cenários de acessibilidade validados
+- **TypeScript**: Definições `jest-axe.d.ts` para matcher `toHaveNoViolations()`
+- **Script**: Adicionado `npm run test:a11y` para testes focados
+
+### 📦 **Exports Modulares**
+
+- **`./integrations`**: Novo export separado para tree-shaking otimizado
+  - Permite `import { createGoogleAnalyticsIntegration } from 'react-lgpd-consent/integrations'`
+  - Reduz bundle para consumidores que não usam integrações
+  - Suporte ESM + CJS + TypeScript definitions
+
+### 🔧 **CI/CD**
+
+- **Node.js 20**: Atualizado de Node 18 para Node 20 LTS em todos os workflows
+- **Cache TypeScript**: Adicionado cache de builds para acelerar CI (~20% mais rápido)
+  - Cache de `.tsbuildinfo`, `node_modules/.cache`, `.eslintcache`
+  - Workflows atualizados: `ci.yml`, `codeql.yml`, `deploy-docs.yml`, `package-check.yml`
+
+### 📚 **Documentação**
+
+- **Badges**: Adicionados 3 badges ao README (Coverage, Bundle Size, Node Version)
+  - Codecov para visualização de cobertura
+  - Bundlephobia para tamanho de bundle
+  - Node.js badge para requisitos de ambiente
+
+### ✅ **Validação de Qualidade**
+
+- **222 testes passando**: 100% de sucesso sem skips
+- **94.85% cobertura**: Mantida cobertura alta
+- **0 warnings de lint**: ESLint limpo
+- **Build otimizado**: ESM 32.52 KB + lazy chunks (95B + 86B)
+
+### 📦 **Otimizações de Bundle**
+
+- **tsup.config.ts**: Configuração otimizada para tree-shaking e code-splitting
+- **ESM Bundle**: 33.26 KB → 32.52 KB (-740B, -2.2%)
+- **CJS Bundle**: 118.51 KB → 37.71 KB (CJS principal) + chunks (-68%, muito mais eficiente!)
+- **Brotli Compressed**:
+  - ESM: 17.06 KB → 16.95 KB (-110B)
+  - CJS: 68.72 KB → 18.02 KB (-74%, -50.7 KB!)
+- **Side-effects**: Configuração refinada para preservar code-splitting sem warnings
+- **Tree-shaking**: Agressivo com external de peer dependencies
+
+### 🎯 **Decisões de Design**
+
+- **ConsentGate não usa memo**: Decisão intencional - estado de preferências é dinâmico
+  - Re-renders necessários quando usuário altera consentimento
+  - Lógica leve o suficiente para não justificar memoização
+
+### 📋 **Dependências**
+
+- **Adicionadas**:
+  - `@axe-core/react@^4.10.2` (dev)
+  - `jest-axe@^10.0.0` (dev)
+  - `@types/jest-axe@^3.5.9` (dev)
+
 ## [0.4.1] - 2025-09-21 — Expansão das Integrações Nativas de Scripts
 
 ### 🚀 **Integrações Nativas Expandidas**
+
 - **Facebook Pixel**: `createFacebookPixelIntegration()` com auto-tracking e advanced matching
 - **Hotjar**: `createHotjarIntegration()` para heatmaps e session recordings
 - **Mixpanel**: `createMixpanelIntegration()` com configuração avançada de eventos
@@ -17,18 +117,21 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - **Freshchat**: `createFreshchatIntegration()` para customer support
 
 ### 🎯 **Sistema de Configuração em Lote**
+
 - **Templates de negócio**: `createECommerceIntegrations()`, `createSaaSIntegrations()`, `createCorporateIntegrations()`
 - **Categorização inteligente**: `suggestCategoryForScript()` para sugestão automática de categorias
 - **Configuração unificada**: Setup simplificado para múltiplas ferramentas com um comando
 - **Padrões de mercado**: Templates baseados em necessidades reais do mercado brasileiro
 
 ### 🔧 **Melhorias no Sistema de Scripts**
+
 - **Validação robusta**: `validateNecessaryClassification()` corrigida para evitar falsos positivos
 - **Auto-configuração**: `autoConfigureCategories()` com detecção inteligente de categorias necessárias
 - **Error handling**: Melhor tratamento de erros em carregamento de scripts
 - **Performance**: Carregamento otimizado e lazy loading de integrações
 
 ### 🔍 **Descoberta Automática de Cookies (Experimental)**
+
 - **discoverRuntimeCookies()**: Escaneamento de cookies em tempo real no navegador
 - **detectConsentCookieName()**: Detecção automática do cookie de consentimento
 - **categorizeDiscoveredCookies()**: Categorização inteligente usando padrões LGPD
@@ -36,17 +139,20 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - **SSR-safe**: Funciona corretamente em ambientes server-side rendering
 
 ### 🎨 **Design Tokens Expandidos**
+
 - **200+ pontos de customização**: Expansão dramática do sistema de design tokens
 - **Sistema responsivo**: Breakpoints, spacing responsivo, typography hierarchy
 - **Acessibilidade nativa**: Contrast ratios, focus states, motion preferences
 - **Tokens por componente**: Customização granular para cada elemento UI
 
 ### 📝 **Sistema Avançado de Textos**
+
 - **Templates pré-configurados**: Ecommerce, SaaS, Governo com contextos específicos
 - **Multilingual**: Português, inglês, espanhol com fallbacks inteligentes
 - **Função resolveTexts**: Resolução automática de textos baseada em contexto
 
 ### 🧪 **Melhorias de Testes e Qualidade**
+
 - **193 testes passando**: Cobertura substancialmente melhorada
 - **19 novos testes**: Especificamente para `cookieRegistry` (antes 45.83% → 100% branches)
 - **Test realism**: Testes adaptados ao comportamento real vs ideal
@@ -54,6 +160,7 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - **Lint compliance**: Configuração ESLint mais rigorosa e aderente
 
 ### 🔧 **Melhorias de API e Developer Experience**
+
 - **Exports organizados**: Melhor estruturação das exportações públicas
 - **TypeScript strict**: Tipagem mais rigorosa e descritiva
 - **Documentação TSDoc**: Comentários expandidos com exemplos práticos
@@ -61,12 +168,14 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - **Performance**: Otimizações em carregamento e renderização
 
 ### 📚 **Exemplos e Migração**
+
 - **MigrationDemo-v0.4.1.tsx**: Exemplo completo mostrando todas as novidades
 - **Remoção**: TestV0.3.1.tsx removido (obsoleto)
 - **Compatibilidade**: Guias de migração antes/depois
 - **Best practices**: Demonstrações de uso avançado
 
 ### 🏗️ **Build e Infraestrutura**
+
 - **Bundle otimizado**: ESM 34.36 KB, CJS 102.74 KB
 - **Tree-shaking**: Configuração `sideEffects: false` otimizada
 - **Docs geradas**: TypeDoc atualizado com novas funcionalidades
@@ -74,22 +183,25 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 
 ### ⚠️ **Breaking Changes**
 
-#### 🔧 **`setPreference` Type Change** 
+#### 🔧 **`setPreference` Type Change**
+
 - **Mudança**: `setPreference(cat: Category, value: boolean)` → `setPreference(cat: string, value: boolean)`
-- **Motivo**: Suporte a categorias customizadas além das predefinidas  
+- **Motivo**: Suporte a categorias customizadas além das predefinidas
 - **Impacto**: Código TypeScript com tipo `Category` explícito pode precisar ajustes
-- **Migração**: 
+- **Migração**:
   - ✅ **Nenhuma mudança necessária** se usando strings literais (`'analytics'`, `'marketing'`)
   - ⚠️ **Ajuste necessário** apenas se estava usando explicitamente o tipo `Category`
   - 📚 **Guia**: Use `string` para suportar categorias customizadas ou continue usando os valores padrão
 
 #### 🔧 **`ScriptIntegration.category` Type Change**
+
 - **Mudança**: `category: Category` → `category: string`
 - **Motivo**: Suporte a categorias customizadas nas integrações de script
 - **Impacto**: Integrações customizadas com tipo `Category` explícito
 - **Migração**: Mesmas diretrizes do `setPreference` acima
 
 ### 🎯 **Categorias Suportadas**
+
 - `necessary` (sempre ativo)
 - `analytics` (Google Analytics, etc.)
 - `marketing` (Facebook Pixel, Google Ads)
@@ -98,6 +210,7 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - `personalization` (Preferências, customização)
 
 ### 📈 **Estatísticas de Melhoria**
+
 - **Design Tokens**: 4 → 200+ pontos de customização (+4900%)
 - **Testes**: 174 → 193 testes (+11% cobertura)
 - **Funcionalidades**: +15 novas funções exportadas
@@ -107,6 +220,7 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 ## [0.4.0] - 2025-09-09 — Custom categories
 
 ### Added
+
 - Support for `customCategories` in `ConsentProvider.categories`.
   - Included in preferences initialization and validation.
   - Shown in the Preferences modal (with name/description).
@@ -115,6 +229,7 @@ O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.
 - Storybook story: WithCustomCategories.
 
 ### Notes
+
 - Non-breaking change; existing configurations continue to work.
 
 ## [0.3.7] - 2025-09-08 - Testes de UI e carregamento de scripts
@@ -656,3 +771,35 @@ A v0.2.1 introduz um **sistema inteligente de orientações** que guia desenvolv
 - [ ] Base legal por categoria
 - [ ] Relatórios de compliance
 - [ ] Templates por setor
+
+## [0.4.2] - 06/10/2025 — Quickstarts + SSR Guide + Validação (DEV)
+
+### ✨ Quickstarts executáveis
+
+- Next.js (App Router) e Vite com Consent Mode v2 integrado e bloqueio real de scripts (GTM/GA4 não carregam antes do consentimento).
+- Seções no QUICKSTART.md com passos copy‑paste e validação do comportamento esperado.
+
+### 🧱 Guia SSR/Next.js (App Router)
+
+- Padrões seguros para evitar hydration mismatch: wrapper client‑only com `'use client'` e `dynamic({ ssr: false })`, efeitos que acessam `window/document` apenas no cliente.
+- Ordem de provedores/estilos (Emotion/MUI) e z-index/portals documentados (overlay 1299, modais ≥ 1300).
+
+### ✅ Validação de configuração do ConsentProvider (DEV)
+
+- Validação com Zod em desenvolvimento (import dinâmico) e sanitização leve em produção.
+- Mensagens amigáveis: alerta quando `categories` não é fornecida; remove `'necessary'` de `enabledCategories`; detecta duplicidades/valores inválidos; valida `customCategories`.
+- Testes cobrindo casos inválidos e asserts de mensagens.
+
+### 📚 Categorias — definição, uso e exemplos
+
+- Fonte única de verdade: `ConsentProvider.categories`. UI, hooks e integrações leem a mesma definição.
+- Esclarecimento: apenas “necessários” é obrigatório; demais categorias são opcionais conforme o negócio.
+- Exemplos mínimo (somente necessários) e completo (analytics/marketing/functional).
+
+### 🔧 Dependências
+
+- Adicionado: `zod@^3.23.8` (usado somente em DEV via import dinâmico; não impacta o bundle de produção).
+
+### 🧩 Sem breaking changes
+
+- Alterações são compatíveis; padrões seguros preservados.

package/QUICKSTART.md

@@ -62,9 +62,263 @@ export default App
 
 ````
 
+## ⚡ Quickstarts: Next.js (App Router) e Vite
+
+Os exemplos a seguir integram GTM/GA4 com Consent Mode v2 e garantem que nenhum script de tracking rode antes do consentimento. Eles também mostram como usar `ConsentScriptLoader` e sincronizar os sinais do Consent Mode via `gtag('consent', ...)`.
+
+- Exemplos completos: `examples/next-app-router/*`, `examples/vite/*`
+
+### Next.js 14/15 — App Router (SSR-safe)
+
+1) Criar app Next e instalar deps
+
+```bash
+npm create next-app@latest my-app --ts --eslint --src-dir --app --no-tailwind --no-experimental-app
+cd my-app
+npm i react-lgpd-consent @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+2) Variáveis públicas no `.env.local`
+
+```
+NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
+NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX
+```
+
+3) Copiar os arquivos do exemplo e ajustar imports
+
+- De `examples/next-app-router/app/layout.tsx` → `app/layout.tsx`
+- De `examples/next-app-router/app/page.tsx` → `app/page.tsx`
+- De `examples/next-app-router/components/ClientConsent.tsx` → `app/components/ClientConsent.tsx`
+
+Observação: nos arquivos copiados, troque imports relativos para `import { ConsentProvider, ConsentScriptLoader } from 'react-lgpd-consent'`.
+
+4) O que esse setup faz
+
+- `ClientConsent` é um componente client-only (via `dynamic(..., { ssr: false })` no layout) que:
+  - Injeta um stub de `dataLayer/gtag` e define `consent default = denied` para todos os sinais (ad_storage, ad_user_data, ad_personalization, analytics_storage).
+  - Sincroniza as mudanças do consentimento com `gtag('consent','update', ...)` mapeando as categorias: `analytics → analytics_storage`, `marketing → ad_*`.
+  - Usa `ConsentScriptLoader` para carregar GTM/GA4 somente quando as categorias permitirem. Antes disso, nenhum script de tracking é carregado.
+
+5) Rodar
+
+```bash
+npm run dev
+```
+
+Validação rápida:
+- Acesse em aba anônima: a rede não carrega `gtm.js`/`gtag/js` até aceitar preferências.
+- Ao aceitar `analytics`, o GA4 é carregado; ao aceitar `marketing`, os sinais `ad_*` são atualizados como granted.
+
+### Vite (CSR)
+
+1) Criar app Vite e instalar deps
+
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm i react-lgpd-consent @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+2) Variáveis no `.env`
+
+```
+VITE_GA_ID=G-XXXXXXXXXX
+VITE_GTM_ID=GTM-XXXXXXX
+```
+
+3) Copiar os arquivos do exemplo e ajustar imports
+
+- De `examples/vite/index.html` → `index.html` (não adicione scripts do GA/GTM aqui)
+- De `examples/vite/src/main.tsx` → `src/main.tsx`
+- De `examples/vite/src/App.tsx` → `src/App.tsx`
+- De `examples/vite/src/consent/GtagConsent.tsx` → `src/consent/GtagConsent.tsx`
+
+Observação: nos arquivos copiados, troque imports relativos para `import { ... } from 'react-lgpd-consent'`.
+
+4) Rodar
+
+```bash
+npm run dev
+```
+
+Validação rápida:
+- Ao abrir a app (em nova sessão), nenhum script de tracking é baixado até que o usuário consinta.
+- Preferências atualizam `gtag('consent','update', ...)` corretamente por categoria.
+
 ## 🧩 Categorias customizadas (customCategories)
 Disponível a partir da v0.4.0.
 
+## 🍪 Categorias: definição, uso e exemplos
+
+Fonte única de verdade
+- Defina as categorias do seu projeto SOMENTE na prop `categories` do `ConsentProvider`.
+- A UI (Banner/Modal), os hooks (`useConsent`, `useCategories`) e as integrações (`ConsentScriptLoader`) leem a mesma definição. Não declare categorias em outros lugares.
+
+O que é obrigatório?
+- Apenas a categoria `necessary` é obrigatória (e já é sempre incluída automaticamente).
+- Todas as demais (`analytics`, `marketing`, `functional`, etc.) são opcionais e dependem do seu caso de negócio. Se você não usa analytics/ads/chat, simplesmente não habilite essas categorias.
+
+Como “esconder” categorias que não uso?
+- Basta não incluí-las em `enabledCategories` e não declará-las em `customCategories`. A UI não exibirá toggles para categorias ausentes.
+
+Exemplo A — Somente necessários (mínimo, comum para apps internos/governo sem tracking)
+```tsx
+import { ConsentProvider } from 'react-lgpd-consent'
+
+export default function App() {
+  return (
+    <ConsentProvider
+      categories={{ enabledCategories: [] }}
+      texts={{ bannerMessage: 'Usamos apenas cookies necessários para funcionamento.' }}
+    >
+      <YourApp />
+    </ConsentProvider>
+  )
+}
+```
+
+Exemplo B — Conjunto completo (site com analytics e marketing)
+```tsx
+import { ConsentProvider } from 'react-lgpd-consent'
+
+export default function App() {
+  return (
+    <ConsentProvider
+      categories={{ enabledCategories: ['analytics', 'marketing', 'functional'] }}
+    >
+      <YourApp />
+    </ConsentProvider>
+  )
+}
+```
+
+Boas práticas
+- Sempre passe `categories` explicitamente. Em DEV, a biblioteca avisa quando `categories` não foi configurado para evitar ambiguidades.
+- Não classifique scripts de analytics/ads como “necessary” — use `ConsentScriptLoader` e categorias adequadas.
+- Em dúvidas, comece com “somente necessários” e evolua quando o negócio exigir outras categorias.
+
+### 🔎 Validação de configuração (DEV)
+
+Em desenvolvimento, a biblioteca valida a configuração e mostra mensagens amigáveis no console. Nada disso impacta produção (onde só ocorre uma sanitização leve).
+
+Avisos comuns e como corrigir:
+- `Prop 'categories' não fornecida...` — defina `categories.enabledCategories` de forma explícita; exemplo mínimo: `categories={{ enabledCategories: [] }}`.
+- `'necessary' é sempre incluída automaticamente` — remova `'necessary'` de `enabledCategories` (ela já é incluída por padrão).
+- `IDs de categoria duplicados detectados` — revise `enabledCategories` e `customCategories` para garantir que não há IDs repetidos.
+- `enabledCategories contém valores inválidos` — verifique se todos os itens são strings não vazias (IDs de categoria).
+- `customCategories: ... — ... deve ser uma string não vazia` — preencha `id`, `name` e `description` das categorias customizadas.
+
+Notas:
+- Validação detalhada roda apenas em `NODE_ENV !== 'production'`.
+- Em produção, a lib não carrega o validador; somente remove `'necessary'` se vier por engano, mantendo o comportamento seguro.
+
+## 🧱 SSR/Next.js (App Router) — Padrões seguros
+
+Objetivo: evitar hydration mismatch, hooks em Server Components e vazamento de scripts.
+
+Padrões recomendados
+- Envolva o app com o `ConsentProvider` apenas no cliente.
+- Use `dynamic(() => import('./ClientConsent'), { ssr: false })` no `RootLayout` (Server Component) e mova hooks e efeitos para o componente cliente.
+- Nenhum acesso a `window`/`document` no topo de módulo; use apenas dentro de `useEffect`.
+- Inicialize Consent Mode v2 com `gtag('consent','default', denied)` antes de carregar GTM/GA4; depois, atualize sinais na mudança de preferências.
+
+Exemplo de RootLayout (Server) + Client wrapper
+
+```tsx
+// app/layout.tsx (Server Component)
+import dynamic from 'next/dynamic'
+
+const ClientConsent = dynamic(() => import('./components/ClientConsent'), { ssr: false })
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <ClientConsent>{children}</ClientConsent>
+      </body>
+    </html>
+  )
+}
+```
+
+```tsx
+// app/components/ClientConsent.tsx (Client Component)
+'use client'
+import React from 'react'
+import { ConsentProvider, ConsentScriptLoader } from 'react-lgpd-consent'
+import { COMMON_INTEGRATIONS } from 'react-lgpd-consent'
+import { useConsent } from 'react-lgpd-consent'
+
+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('consent', 'default', {
+      ad_storage: 'denied',
+      ad_user_data: 'denied',
+      ad_personalization: 'denied',
+      analytics_storage: 'denied',
+    })
+  }, [])
+  return null
+}
+
+function SyncConsentMode() {
+  const { consented, preferences } = useConsent()
+  React.useEffect(() => {
+    if (!consented) return
+    const w = window as any
+    w.gtag?.('consent', 'update', {
+      analytics_storage: preferences.analytics ? 'granted' : 'denied',
+      ad_storage: preferences.marketing ? 'granted' : 'denied',
+      ad_user_data: preferences.marketing ? 'granted' : 'denied',
+      ad_personalization: preferences.marketing ? 'granted' : 'denied',
+    })
+  }, [consented, preferences])
+  return null
+}
+
+export default function ClientConsent({ children }: { children: React.ReactNode }) {
+  const GA = process.env.NEXT_PUBLIC_GA_ID!
+  const GTM = process.env.NEXT_PUBLIC_GTM_ID!
+  return (
+    <ConsentProvider categories={{ enabledCategories: ['analytics', 'marketing', 'functional'] }} blocking>
+      <BootstrapConsentMode />
+      <SyncConsentMode />
+      <ConsentScriptLoader
+        integrations={[
+          COMMON_INTEGRATIONS.googleAnalytics({ measurementId: GA }),
+          COMMON_INTEGRATIONS.googleTagManager({ containerId: GTM }),
+        ]}
+      />
+      {children}
+    </ConsentProvider>
+  )
+}
+```
+
+Ordem de provedores e estilos (MUI/Emotion)
+- Preferência de ordem recomendada:
+  - `CacheProvider` (Emotion) ou `StyledEngineProvider` com `injectFirst`
+  - `ThemeProvider` (MUI)
+  - `CssBaseline`
+  - `ConsentProvider` (sem criar tema por padrão)
+- Motivo: garante injeção de estilos do MUI antes de CSS da app e evita desalinhamento visual; os componentes da lib herdam o tema quando presente.
+
+Z-index e Portals
+- Componentes MUI usam o `zIndex` do tema; modals/portals padrão usam `zIndex.modal = 1300`.
+- O overlay bloqueante do Provider usa `z-index: 1299`; o Modal/Banner usa camadas ≥ 1300.
+- Em caso de conflito com headers fixos, ajuste o `theme.zIndex` (ex.: `appBar: 1200`, `modal: 1300+`) ou os `designTokens` conforme a necessidade.
+
+Checklist SSR (evite hydration mismatch)
+- [ ] Hooks somente em Client Components (`'use client'` no topo).
+- [ ] Nada de `window`/`document`/`localStorage` no topo de módulo (apenas em `useEffect`).
+- [ ] `dynamic(..., { ssr: false })` para wrappers que usam hooks e efeitos do consentimento.
+- [ ] GTM/GA4 carregados apenas após consentimento (via `ConsentScriptLoader`).
+- [ ] Sem `<script>` de GTM/GA4 em `head`/`body`; todo carregamento vem do loader.
+
 ## 🎨 Dica de estilo: Backdrop sensível ao tema
 
 No modo bloqueante, o banner usa um backdrop para focar a atenção do usuário. Você pode controlar via design tokens:

package/README.en.md

@@ -15,6 +15,12 @@
     <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-Compatible-000000?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js Compatible"></a>
   </div>
 
+  <div>
+    <a href="https://codecov.io/gh/lucianoedipo/react-lgpd-consent"><img src="https://img.shields.io/codecov/c/github/lucianoedipo/react-lgpd-consent?style=for-the-badge&logo=codecov&logoColor=white" alt="Coverage"></a>
+    <a href="https://bundlephobia.com/package/react-lgpd-consent"><img src="https://img.shields.io/bundlephobia/minzip/react-lgpd-consent?style=for-the-badge&logo=webpack&logoColor=white" alt="Bundle Size"></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/react-lgpd-consent?style=for-the-badge&logo=node.js&logoColor=white" alt="Node Version"></a>
+  </div>
+
   <br />
 
   <p>

package/README.md

@@ -15,6 +15,12 @@
     <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-Compatible-000000?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js Compatible"></a>
   </div>
 
+  <div>
+    <a href="https://codecov.io/gh/lucianoedipo/react-lgpd-consent"><img src="https://img.shields.io/codecov/c/github/lucianoedipo/react-lgpd-consent?style=for-the-badge&logo=codecov&logoColor=white" alt="Coverage"></a>
+    <a href="https://bundlephobia.com/package/react-lgpd-consent"><img src="https://img.shields.io/bundlephobia/minzip/react-lgpd-consent?style=for-the-badge&logo=webpack&logoColor=white" alt="Bundle Size"></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/react-lgpd-consent?style=for-the-badge&logo=node.js&logoColor=white" alt="Node Version"></a>
+  </div>
+
   <br />
 
   <p>
@@ -46,6 +52,19 @@ npm install react-lgpd-consent @mui/material @emotion/react @emotion/styled js-c
 
 ---
 
+## ✨ Novidades v0.4.4
+
+### 🔧 CI/CD e Publicação
+- **Workflow de Publicação**: Corrigido bug que impedia publicação automática no npm quando tags eram criadas após merge para `main`
+- **Codecov Integration**: Adicionado upload automático de coverage reports para melhor visualização de cobertura de testes
+- **Badge de Coverage**: Agora atualizado em tempo real via Codecov
+
+### 📊 Qualidade e Confiabilidade
+- **Publicação Confiável**: Tags agora são publicadas corretamente quando commit está no histórico da `main`
+- **Visibilidade de Cobertura**: Integração completa com Codecov para tracking de qualidade
+
+---
+
 ## ✨ Novidades v0.4.1
 
 ### 🎨 Design Tokens Expandidos
@@ -113,6 +132,7 @@ Para mais detalhes sobre customização, hooks e funcionalidades, consulte os se
 ### 📋 Documentação Principal
 
 - **[📚 Guia de Início Rápido (`QUICKSTART.md`)](./QUICKSTART.md)**: Tutorial passo a passo com exemplos práticos, tabela completa de props, debugging e integrações.
+  - Seção recomendada: “SSR/Next.js (App Router) — Padrões seguros” com boas práticas de `'use client'`, `dynamic({ ssr: false })` e ordem dos provedores/estilos (MUI/Emotion) para evitar hydration mismatch.
   - Novo na v0.4.0: suporte a `customCategories` — veja a seção “Categorias customizadas (customCategories)” no Quickstart.
   - Novo na v0.4.1: integrações nativas para Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom e Zendesk — veja o guia [INTEGRACOES.md](./INTEGRACOES.md).
   - Dica: use `designTokens.layout.backdrop: 'auto'` para backdrop sensível ao tema no banner bloqueante.

package/dist/FloatingPreferencesButton-4AGBXNHH.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var chunkFJKRAERJ_cjs = require('./chunk-FJKRAERJ.cjs');
+require('./chunk-ORI4PLVG.cjs');
+
+
+
+Object.defineProperty(exports, "FloatingPreferencesButton", {
+  enumerable: true,
+  get: function () { return chunkFJKRAERJ_cjs.FloatingPreferencesButton; }
+});

package/dist/FloatingPreferencesButton-IY7TFD7D.js

@@ -0,0 +1,2 @@
+export { FloatingPreferencesButton } from './chunk-PJFGQMCI.js';
+import './chunk-RWT2ORFE.js';

package/dist/PreferencesModal-5KNHWW57.js

@@ -0,0 +1,2 @@
+export { PreferencesModal } from './chunk-N3QOW4SA.js';
+import './chunk-RWT2ORFE.js';

package/dist/PreferencesModal-YBCWCVUI.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var chunk25XEI2DZ_cjs = require('./chunk-25XEI2DZ.cjs');
+require('./chunk-ORI4PLVG.cjs');
+
+
+
+Object.defineProperty(exports, "PreferencesModal", {
+  enumerable: true,
+  get: function () { return chunk25XEI2DZ_cjs.PreferencesModal; }
+});