react-lgpd-consent 0.4.0 → 0.4.3

package/QUICKSTART.md

@@ -62,9 +62,297 @@ 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:
+
+```tsx
+<ConsentProvider
+  categories={{ enabledCategories: ['analytics'] }}
+  designTokens={{
+    layout: {
+      // false: transparente | 'auto': ajusta ao tema | string: cor custom (ex.: '#00000088')
+      backdrop: 'auto',
+    },
+    colors: {
+      // Se omitido, usa o palette do tema MUI (background.paper, text.primary)
+      // background: '#1e1e1e',
+      // text: '#ffffff',
+    },
+  }}
+>
+  <App />
+</ConsentProvider>
+```
+
+Se `colors.background` ou `colors.text` não forem fornecidos, a lib usa automaticamente `theme.palette.background.paper` e `theme.palette.text.primary` do MUI, garantindo compatibilidade com dark mode.
+
+## 🧑‍🏫 Guia do Dev (console)
+
+Durante o desenvolvimento, o console exibe um guia com:
+- Avisos quando a configuração padrão é usada; sugestões para explicitar categorias
+- Lista de categorias ativas e quais exigem toggle
+- Detecção de integrações que requerem categorias, com sugestão para habilitá-las
+- Boas práticas LGPD (Brasil) e alertas de UX (categorias demais)
+- Silenciado automaticamente em produção; SSR-safe
+
 Adicione categorias específicas do seu projeto (ex.: chat de suporte, players de vídeo, AB testing):
 
 ```tsx
@@ -193,7 +481,6 @@ A biblioteca `react-lgpd-consent` não injeta um `ThemeProvider` global por cont
 
 ```tsx
 import { ConsentProvider, createDefaultConsentTheme } from 'react-lgpd-consent'
-
 ;<ConsentProvider
   theme={createDefaultConsentTheme()}
   categories={{ enabledCategories: ['analytics'] }}
@@ -275,6 +562,280 @@ function App() {
 }
 ```
 
+### 🍪 Modal Personalizado com Detalhes dos Cookies
+
+Para casos mais avançados onde você precisa exibir informações detalhadas sobre cada cookie (nome, finalidade, duração, provedor), use `getCookiesInfoForCategory` junto com `useCategories`:
+
+```tsx
+import React from 'react'
+import {
+  ConsentProvider,
+  useCategories,
+  getCookiesInfoForCategory,
+  type CustomPreferencesModalProps,
+  type CookieDescriptor,
+} from 'react-lgpd-consent'
+
+const ModalComDetalhesCookies: React.FC<CustomPreferencesModalProps> = ({
+  preferences,
+  setPreferences,
+  closePreferences,
+  isModalOpen,
+  texts,
+}) => {
+  const { allCategories } = useCategories()
+
+  if (!isModalOpen) return null
+
+  // Simula integrações usadas no projeto (normalmente você teria isso em contexto)
+  const integracoesUsadas = ['google-analytics', 'google-tag-manager', 'mixpanel']
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: '100vw',
+        height: '100vh',
+        backgroundColor: 'rgba(0, 0, 0, 0.7)',
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+        zIndex: 2000,
+      }}
+    >
+      <div
+        style={{
+          backgroundColor: 'white',
+          borderRadius: '12px',
+          padding: '2rem',
+          maxWidth: '800px',
+          maxHeight: '80vh',
+          overflow: 'auto',
+          boxShadow: '0 10px 25px rgba(0, 0, 0, 0.25)',
+        }}
+      >
+        <h2 style={{ marginBottom: '1rem', color: '#333' }}>{texts.modalTitle}</h2>
+        <p style={{ marginBottom: '2rem', color: '#666' }}>{texts.modalIntro}</p>
+
+        {/* Lista de categorias com detalhes dos cookies */}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem' }}>
+          {allCategories.map((categoria) => {
+            const cookiesDetalhados: CookieDescriptor[] = getCookiesInfoForCategory(
+              categoria.id as any,
+              integracoesUsadas,
+            )
+
+            return (
+              <div
+                key={categoria.id}
+                style={{
+                  border: '1px solid #e0e0e0',
+                  borderRadius: '8px',
+                  padding: '1.5rem',
+                  backgroundColor: '#fafafa',
+                }}
+              >
+                <div style={{ display: 'flex', alignItems: 'center', marginBottom: '1rem' }}>
+                  <input
+                    type="checkbox"
+                    id={`categoria-${categoria.id}`}
+                    checked={preferences[categoria.id] || false}
+                    onChange={(e) =>
+                      setPreferences({
+                        ...preferences,
+                        [categoria.id]: e.target.checked,
+                      })
+                    }
+                    disabled={categoria.essential}
+                    style={{ marginRight: '0.75rem', transform: 'scale(1.2)' }}
+                  />
+                  <label
+                    htmlFor={`categoria-${categoria.id}`}
+                    style={{ fontSize: '1.1rem', fontWeight: 'bold', color: '#333' }}
+                  >
+                    {categoria.name}
+                    {categoria.essential && (
+                      <span style={{ fontSize: '0.8rem', color: '#888', marginLeft: '0.5rem' }}>
+                        (sempre ativo)
+                      </span>
+                    )}
+                  </label>
+                </div>
+
+                <p style={{ marginBottom: '1rem', color: '#666', fontSize: '0.95rem' }}>
+                  {categoria.description}
+                </p>
+
+                {/* Lista de cookies desta categoria */}
+                {cookiesDetalhados.length > 0 && (
+                  <details style={{ marginTop: '1rem' }}>
+                    <summary
+                      style={{
+                        cursor: 'pointer',
+                        fontWeight: '500',
+                        color: '#4f46e5',
+                        marginBottom: '0.5rem',
+                      }}
+                    >
+                      Ver cookies desta categoria ({cookiesDetalhados.length})
+                    </summary>
+                    <div style={{ marginTop: '0.75rem', paddingLeft: '1rem' }}>
+                      {cookiesDetalhados.map((cookie, index) => (
+                        <div
+                          key={`${cookie.name}-${index}`}
+                          style={{
+                            backgroundColor: 'white',
+                            border: '1px solid #e5e5e5',
+                            borderRadius: '6px',
+                            padding: '1rem',
+                            marginBottom: '0.75rem',
+                          }}
+                        >
+                          <h4
+                            style={{ margin: '0 0 0.5rem 0', color: '#333', fontSize: '0.95rem' }}
+                          >
+                            <code
+                              style={{
+                                backgroundColor: '#f3f4f6',
+                                padding: '2px 6px',
+                                borderRadius: '4px',
+                                fontFamily: 'monospace',
+                              }}
+                            >
+                              {cookie.name}
+                            </code>
+                          </h4>
+                          {cookie.purpose && (
+                            <p style={{ margin: '0.25rem 0', fontSize: '0.9rem', color: '#555' }}>
+                              <strong>Finalidade:</strong> {cookie.purpose}
+                            </p>
+                          )}
+                          {cookie.duration && (
+                            <p style={{ margin: '0.25rem 0', fontSize: '0.9rem', color: '#555' }}>
+                              <strong>Duração:</strong> {cookie.duration}
+                            </p>
+                          )}
+                          {cookie.provider && (
+                            <p style={{ margin: '0.25rem 0', fontSize: '0.9rem', color: '#555' }}>
+                              <strong>Provedor:</strong> {cookie.provider}
+                            </p>
+                          )}
+                        </div>
+                      ))}
+                    </div>
+                  </details>
+                )}
+
+                {/* Fallback para categorias sem cookies catalogados */}
+                {cookiesDetalhados.length === 0 &&
+                  categoria.cookies &&
+                  categoria.cookies.length > 0 && (
+                    <div style={{ marginTop: '1rem', fontSize: '0.9rem', color: '#666' }}>
+                      <strong>Padrões de cookies:</strong>{' '}
+                      {categoria.cookies.map((pattern, i) => (
+                        <code
+                          key={i}
+                          style={{
+                            backgroundColor: '#f3f4f6',
+                            padding: '2px 4px',
+                            borderRadius: '3px',
+                            marginRight: '0.5rem',
+                            fontFamily: 'monospace',
+                            fontSize: '0.8rem',
+                          }}
+                        >
+                          {pattern}
+                        </code>
+                      ))}
+                    </div>
+                  )}
+              </div>
+            )
+          })}
+        </div>
+
+        {/* Botões de ação */}
+        <div
+          style={{
+            display: 'flex',
+            gap: '1rem',
+            justifyContent: 'flex-end',
+            marginTop: '2rem',
+            paddingTop: '1rem',
+            borderTop: '1px solid #e0e0e0',
+          }}
+        >
+          <button
+            onClick={closePreferences}
+            style={{
+              padding: '0.75rem 1.5rem',
+              backgroundColor: '#6b7280',
+              color: 'white',
+              border: 'none',
+              borderRadius: '6px',
+              cursor: 'pointer',
+              fontSize: '0.95rem',
+            }}
+          >
+            Cancelar
+          </button>
+          <button
+            onClick={closePreferences}
+            style={{
+              padding: '0.75rem 1.5rem',
+              backgroundColor: '#4f46e5',
+              color: 'white',
+              border: 'none',
+              borderRadius: '6px',
+              cursor: 'pointer',
+              fontSize: '0.95rem',
+            }}
+          >
+            {texts.save}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function AppComModalAvancado() {
+  return (
+    <ConsentProvider
+      categories={{
+        enabledCategories: ['analytics', 'marketing', 'functional'],
+      }}
+      PreferencesModalComponent={ModalComDetalhesCookies}
+      // Especifique as integrações para obter informações detalhadas dos cookies
+      scriptIntegrations={[
+        { id: 'google-analytics', config: { measurementId: 'GA_MEASUREMENT_ID' } },
+        { id: 'google-tag-manager', config: { containerId: 'GTM-XXXXXXX' } },
+        { id: 'mixpanel', config: { token: 'MIXPANEL_TOKEN' } },
+      ]}
+    >
+      <main>Minha App com Modal Avançado</main>
+    </ConsentProvider>
+  )
+}
+```
+
+#### 🔧 APIs Utilizadas no Exemplo Avançado
+
+- **`useCategories()`**: Hook que retorna informações sobre todas as categorias ativas
+- **`getCookiesInfoForCategory(categoryId, integrations)`**: Função que retorna detalhes completos dos cookies
+- **`CookieDescriptor`**: Interface TypeScript com `name`, `purpose`, `duration`, `provider`
+
+#### 💡 Principais Funcionalidades
+
+1. **Informações Detalhadas**: Cada cookie mostra nome, finalidade, duração e provedor
+2. **Organização por Categoria**: Cookies agrupados logicamente
+3. **Interface Expansível**: Detalhes dos cookies ficam em `<details>` expansível
+4. **Fallback Inteligente**: Mostra padrões básicos quando detalhes não estão disponíveis
+5. **Acessibilidade**: Labels apropriados e navegação por teclado
+6. **Design Responsivo**: Layout que se adapta a diferentes tamanhos de tela
+
 ## 🎮 Controle Programático
 
 ### Hook useOpenPreferencesModal (React)

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>
@@ -64,6 +70,10 @@ export default function App() {
 -
 - **[QUICKSTART.en.md](./QUICKSTART.en.md)** (recommended)
   - New in v0.4.0: `customCategories` support — see the “Custom categories (customCategories)” section in the Quickstart.
+  - New in v0.4.1: native integrations for Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom, and Zendesk — see [INTEGRACOES.md](./INTEGRACOES.md).
+  - Tip: set `designTokens.layout.backdrop: 'auto'` for a theme-aware blocking banner backdrop.
+  - Auto-config of categories: the library detects required categories from integrations and surfaces toggles even if you forgot to enable them (initial value is always rejected). We still recommend explicitly listing them in `categories.enabledCategories` for clarity.
+  - Non-blocked Policy/Terms pages: if `policyLinkUrl` and/or `termsLinkUrl` point to the current page, the blocking overlay is not applied — ensuring readability of these pages.
 - **[Docs / API](./API.md)**
 - **[LGPD Compliance](./CONFORMIDADE.md)**
 - **[Integrations](./INTEGRACOES.md)**
@@ -73,6 +83,21 @@ export default function App() {
 - **[⚙️ TypeDoc - API Reference](https://lucianoedipo.github.io/react-lgpd-consent/docs/)**: Automatically generated complete API documentation.
 - **[🏠 Documentation Portal](https://lucianoedipo.github.io/react-lgpd-consent/)**: Home page that navigates between all docs sites.
 
+### 🧑‍🏫 Developer Guidance (dev-only)
+
+In development, the library prints a guidance panel in the console to help you configure correctly:
+- Warns when using default categories; suggests making them explicit
+- Lists active categories and which ones require a UI toggle
+- Detects integrations that require categories and suggests enabling them
+- Flags excessive number of categories (UX)
+- Highlights Brazilian LGPD best practices: opt-out by default, clear policy, consent logging, retention
+- Silenced in production; SSR-safe
+
+### ⚠️ Breaking Changes v0.4.1
+- **Custom categories support**: `setPreference` and `ScriptIntegration.category` now use `string` instead of `Category`
+- **Minimal impact**: Code using literal strings continues working without changes
+- **Migration guide**: See [CHANGELOG.md](./CHANGELOG.md) for complete details
+
 ---
 
 ## 🤝 Contributing

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,32 @@ npm install react-lgpd-consent @mui/material @emotion/react @emotion/styled js-c
 
 ---
 
+## ✨ Novidades v0.4.1
+
+### 🎨 Design Tokens Expandidos
+- **200+ pontos de customização** (cores, tipografia, espaçamento, layout)
+- **Sistema responsivo** com breakpoints e variações
+- **Acessibilidade nativa** com contrast ratios e focus states
+- **Temas light/dark/auto** com transições suaves
+
+### 📝 Sistema Avançado de Textos
+- **Templates pré-configurados** para ecommerce, SaaS e governo
+- **Internacionalização completa** (pt, en, es)
+- **Variações de tom** (formal, casual, técnico)
+- **Resolução automática** baseada em contexto
+
+### 🔍 Descoberta de Cookies (Experimental)
+- **Detecção automática** de cookies em runtime
+- **Categorização inteligente** usando padrões LGPD
+- **Integração nativa** com sistema de override
+
+### ⚠️ Breaking Changes
+- **Suporte a categorias customizadas**: `setPreference` e `ScriptIntegration.category` agora usam `string` ao invés de `Category`  
+- **Impacto mínimo**: Código usando strings literais continua funcionando sem alterações
+- **Consulte**: [CHANGELOG.md](./CHANGELOG.md) para guia de migração completo
+
+---
+
 ## 📖 Uso Básico
 
 Envolva sua aplicação com o `ConsentProvider` (exemplo mínimo):
@@ -87,7 +119,12 @@ 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.
+  - Auto-config de categorias: a biblioteca detecta categorias requeridas pelas integrações e exibe os toggles mesmo se você esquecer de habilitar (valor inicial sempre rejeitado). Recomendamos explicitar em `categories.enabledCategories` para clareza.
+  - Páginas de Política/Termos não bloqueadas: se `policyLinkUrl` e/ou `termsLinkUrl` apontarem para a página atual, o overlay bloqueante não é aplicado — garantindo legibilidade destas páginas.
 - **[Guia da API (`API.md`)](./API.md)**: Referência completa de todos os componentes, hooks e tipos.
 - **[Guia de Conformidade (`CONFORMIDADE.md`)](./CONFORMIDADE.md)**: Detalhes sobre as funcionalidades de conformidade com a LGPD.
 - **[Guia de Integrações (`INTEGRACOES.md`)](./INTEGRACOES.md)**: Como usar as integrações nativas e criar as suas.