react-lgpd-consent 0.3.7 → 0.4.1

package/dist/index.d.cts

@@ -6,6 +6,14 @@ import { PaperProps } from '@mui/material/Paper';
 import { SnackbarProps } from '@mui/material/Snackbar';
 import { FabProps } from '@mui/material/Fab';
 
+declare global {
+    /**
+     * @internal
+     * Variável global para rastrear integrações usadas.
+     * Usado internamente para logging e análise de performance.
+     */
+    var __LGPD_USED_INTEGRATIONS__: string[] | undefined;
+}
 /**
  * @interface PreferencesModalProps
  * Propriedades para customizar o componente `PreferencesModal`.
@@ -34,6 +42,96 @@ interface PreferencesModalProps {
  */
 declare function PreferencesModal({ DialogProps, hideBranding, }: Readonly<PreferencesModalProps>): react_jsx_runtime.JSX.Element;
 
+type GuidanceSeverity = 'info' | 'warning' | 'error';
+interface GuidanceMessage {
+    severity: GuidanceSeverity;
+    message: string;
+    category?: string;
+    actionable?: boolean;
+}
+interface GuidanceConfig {
+    /** Controla se avisos devem ser exibidos */
+    showWarnings?: boolean;
+    /** Controla se sugestões devem ser exibidas */
+    showSuggestions?: boolean;
+    /** Controla se a tabela de categorias deve ser exibida */
+    showCategoriesTable?: boolean;
+    /** Controla se as boas práticas devem ser exibidas */
+    showBestPractices?: boolean;
+    /** Controla se deve exibir score de conformidade */
+    showComplianceScore?: boolean;
+    /** Filtro de severidade mínima para exibir mensagens */
+    minimumSeverity?: GuidanceSeverity;
+    /** Callback personalizado para processar mensagens */
+    messageProcessor?: (messages: GuidanceMessage[]) => void;
+}
+interface DeveloperGuidance {
+    warnings: string[];
+    suggestions: string[];
+    messages: GuidanceMessage[];
+    activeCategoriesInfo: {
+        id: string;
+        name: string;
+        description: string;
+        essential: boolean;
+        uiRequired: boolean;
+        cookies?: string[];
+    }[];
+    usingDefaults: boolean;
+    complianceScore?: number;
+}
+declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
+/**
+ * Analisa configuração e integrações implícitas para orientar o dev.
+ *
+ * Since v0.4.0: inclui customCategories.
+ * Since v0.4.1: considera categorias/integrações implícitas e enriquece cookies por categoria.
+ */
+declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
+declare function logDeveloperGuidance(guidance: DeveloperGuidance, disableGuidanceProp?: boolean, config?: GuidanceConfig): void;
+declare function useDeveloperGuidance(config?: ProjectCategoriesConfig, disableGuidanceProp?: boolean, guidanceConfig?: GuidanceConfig): DeveloperGuidance;
+/**
+ * Presets de configuração para diferentes ambientes
+ */
+declare const GUIDANCE_PRESETS: {
+    /** Configuração completa para desenvolvimento */
+    readonly development: {
+        readonly showWarnings: true;
+        readonly showSuggestions: true;
+        readonly showCategoriesTable: true;
+        readonly showBestPractices: true;
+        readonly showComplianceScore: true;
+        readonly minimumSeverity: "info";
+    };
+    /** Configuração silenciosa para produção */
+    readonly production: {
+        readonly showWarnings: false;
+        readonly showSuggestions: false;
+        readonly showCategoriesTable: false;
+        readonly showBestPractices: false;
+        readonly showComplianceScore: false;
+        readonly minimumSeverity: "error";
+    };
+    /** Apenas erros críticos */
+    readonly minimal: {
+        readonly showWarnings: true;
+        readonly showSuggestions: false;
+        readonly showCategoriesTable: false;
+        readonly showBestPractices: false;
+        readonly showComplianceScore: false;
+        readonly minimumSeverity: "error";
+    };
+    /** Focado em conformidade LGPD */
+    readonly compliance: {
+        readonly showWarnings: true;
+        readonly showSuggestions: true;
+        readonly showCategoriesTable: true;
+        readonly showBestPractices: true;
+        readonly showComplianceScore: true;
+        readonly minimumSeverity: "warning";
+    };
+};
+
 /**
  * @fileoverview
  * Definições de tipos TypeScript para o sistema de consentimento LGPD/ANPD.
@@ -81,6 +179,7 @@ type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social
  *
  * @example
  * ```typescript
+ * // Categoria padrão da biblioteca
  * const analyticsCategory: CategoryDefinition = {
  *   id: 'analytics',
  *   name: 'Cookies Analíticos',
@@ -88,6 +187,14 @@ type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social
  *   essential: false,
  *   cookies: ['_ga', '_ga_*', '_gid']
  * };
+ *
+ * // Categoria customizada específica do projeto
+ * const chatCategory: CategoryDefinition = {
+ *   id: 'chat',
+ *   name: 'Chat de Suporte',
+ *   description: 'Widget de chat para suporte ao cliente',
+ *   essential: false
+ * };
  * ```
  *
  * @public
@@ -118,6 +225,61 @@ interface CategoryDefinition {
      * @example ['_ga', '_ga_*', '_gid']
      */
     cookies?: string[];
+    /**
+     * Metadados detalhados sobre cookies típicos desta categoria.
+     * Não exaustivo; serve para orientar UI e documentação.
+     */
+    cookiesInfo?: CookieDescriptor[];
+}
+/**
+ * Descritor de cookie com metadados úteis para UI/documentação.
+ * @category Types
+ * @since 0.2.0
+ *
+ * @remarks
+ * Mantém compatibilidade com abordagens comuns no mercado.
+ * Fornece informações detalhadas sobre cookies para exibição em interfaces
+ * e documentação de compliance.
+ *
+ * @example
+ * ```typescript
+ * const cookieInfo: CookieDescriptor = {
+ *   name: '_ga',
+ *   purpose: 'analytics',
+ *   duration: '2 years',
+ *   domain: '.example.com',
+ *   provider: 'Google Analytics'
+ * };
+ * ```
+ *
+ * @public
+ */
+interface CookieDescriptor {
+    /**
+     * Identificador ou padrão do cookie.
+     * @example '_ga'
+     */
+    name: string;
+    /**
+     * Finalidade do cookie (opcional).
+     * @example 'analytics'
+     */
+    purpose?: string;
+    /**
+     * Tempo de retenção do cookie (opcional).
+     * @example '2 years'
+     */
+    duration?: string;
+    /**
+     * Domínio associado ao cookie (opcional).
+     * @example '.example.com'
+     */
+    domain?: string;
+    /**
+     * Provedor ou serviço associado ao cookie (opcional).
+     * @example 'Google Analytics'
+     */
+    provider?: string;
 }
 /**
  * Configuração de categorias ativas no projeto.
@@ -144,11 +306,18 @@ interface CategoryDefinition {
  * // Configuração com categorias customizadas
  * const config: ProjectCategoriesConfig = {
  *   enabledCategories: ['analytics'],
- *   customCategories: [{
- *     id: 'support',
- *     name: 'Suporte',
- *     description: 'Cookies para sistema de suporte ao cliente'
- *   }]
+ *   customCategories: [
+ *     {
+ *       id: 'chat',
+ *       name: 'Chat de Suporte',
+ *       description: 'Widget de chat para suporte ao cliente'
+ *     },
+ *     {
+ *       id: 'abTesting',
+ *       name: 'A/B Testing',
+ *       description: 'Experimentos de interface e funcionalidades'
+ *     }
+ *   ]
  * };
  * ```
  *
@@ -164,6 +333,7 @@ interface ProjectCategoriesConfig {
     /**
      * Categorias customizadas específicas do projeto.
      * Permite extensão além das categorias padrão da biblioteca.
+     * @example [{ id: 'chat', name: 'Chat de Suporte', description: 'Widget de chat' }]
      */
     customCategories?: CategoryDefinition[];
 }
@@ -514,6 +684,7 @@ interface ConsentTexts {
  * Opções para configuração do cookie de consentimento.
  * @category Types
  * @since 0.1.0
+ * @public
  */
 interface ConsentCookieOptions {
     /** Nome do cookie. Padrão: 'cookieConsent' */
@@ -527,53 +698,451 @@ interface ConsentCookieOptions {
     /** Caminho do cookie. Padrão: '/' */
     path: string;
 }
+/**
+ * Tipo alias para valores de espaçamento que suportam eixos x/y.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Permite especificar espaçamento como string, número ou objeto com eixos x e y separados.
+ * Útil para configurações de padding e margin em design tokens.
+ * @example
+ * ```typescript
+ * const spacing: SpacingValue = { x: 10, y: 20 };
+ * ```
+ */
+type SpacingValue = string | number | {
+    x?: string | number;
+    y?: string | number;
+};
+/**
+ * Tipo alias para cores com variações.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Suporta cor simples ou objeto com variações light, main, dark e contrastText.
+ * Compatível com sistemas de design que precisam de paletas completas.
+ * @example
+ * ```typescript
+ * const color: ColorVariant = { main: '#1976d2', dark: '#1565c0' };
+ * ```
+ */
+type ColorVariant = string | {
+    light?: string;
+    main?: string;
+    dark?: string;
+    contrastText?: string;
+};
+/**
+ * Tipo alias para altura com auto.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Permite 'auto' ou qualquer string válida para altura CSS, com type safety.
+ * Evita valores inválidos através de interseção com Record<never, never>.
+ * @example
+ * ```typescript
+ * const height: HeightValue = 'auto';
+ * const customHeight: HeightValue = '100px';
+ * ```
+ */
+type HeightValue = 'auto' | (string & Record<never, never>);
+/**
+ * Tipo alias para configuração de backdrop.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Define configuração do backdrop como booleano simples, string de cor ou objeto detalhado
+ * com propriedades como enabled, color, blur e opacity para controle granular.
+ * @example
+ * ```typescript
+ * const backdrop: BackdropConfig = { enabled: true, color: 'rgba(0,0,0,0.5)', blur: '4px' };
+ * ```
+ */
+type BackdropConfig = boolean | string | {
+    enabled?: boolean;
+    color?: string;
+    blur?: string;
+    opacity?: number;
+};
 /**
  * Tokens de design para customização visual avançada dos componentes.
+ *
+ * Sistema robusto de design tokens que permite controle granular sobre todos os aspectos
+ * visuais da biblioteca. Suporta responsive design, estados interativos, acessibilidade
+ * e temas dark/light.
+ *
  * @category Types
  * @since 0.1.3
- * Permite um controle mais direto sobre a aparência sem a necessidade de `sx` props complexas.
+ * @version 0.4.1 - Expandido substancialmente com novos tokens
+ * @public
+ *
+ * @example Configuração básica
+ * ```tsx
+ * const tokens: DesignTokens = {
+ *   colors: {
+ *     primary: '#1976d2',
+ *     background: '#ffffff',
+ *     text: '#333333'
+ *   }
+ * }
+ * ```
+ *
+ * @example Configuração avançada com responsive e estados
+ * ```tsx
+ * const advancedTokens: DesignTokens = {
+ *   colors: {
+ *     primary: { light: '#42a5f5', main: '#1976d2', dark: '#1565c0' },
+ *     semantic: {
+ *       error: '#f44336',
+ *       warning: '#ff9800',
+ *       success: '#4caf50',
+ *       info: '#2196f3'
+ *     }
+ *   },
+ *   spacing: {
+ *     responsive: {
+ *       mobile: { padding: '12px', margin: '8px' },
+ *       tablet: { padding: '16px', margin: '12px' },
+ *       desktop: { padding: '24px', margin: '16px' }
+ *     }
+ *   }
+ * }
+ * ```
  */
 interface DesignTokens {
+    /**
+     * Sistema de cores expandido com suporte a variações e semântica
+     */
     colors?: {
-        background?: string;
-        text?: string;
-        primary?: string;
-        secondary?: string;
+        /** Cor primária da aplicação */
+        primary?: ColorVariant;
+        /** Cor secundária */
+        secondary?: ColorVariant;
+        /** Cor de fundo principal */
+        background?: string | {
+            main?: string;
+            paper?: string;
+            overlay?: string;
+            default?: string;
+        };
+        /** Cor do texto */
+        text?: string | {
+            primary?: string;
+            secondary?: string;
+            disabled?: string;
+        };
+        /** Cor da borda */
+        border?: ColorVariant;
+        /** Cores semânticas para estados */
+        semantic?: {
+            error?: string;
+            warning?: string;
+            success?: string;
+            info?: string;
+        };
+        /** Cores específicas para componentes */
+        components?: {
+            banner?: {
+                background?: string;
+                text?: string;
+                border?: string;
+                shadow?: string;
+            };
+            modal?: {
+                background?: string;
+                text?: string;
+                overlay?: string;
+                border?: string;
+            };
+            button?: {
+                primary?: {
+                    background?: string;
+                    text?: string;
+                    hover?: string;
+                };
+                secondary?: {
+                    background?: string;
+                    text?: string;
+                    hover?: string;
+                };
+                outlined?: {
+                    border?: string;
+                    text?: string;
+                    hover?: string;
+                };
+            };
+        };
     };
+    /**
+     * Sistema tipográfico completo com hierarquia e responsive
+     */
     typography?: {
-        fontFamily?: string;
+        /** Família de fontes principal */
+        fontFamily?: string | {
+            primary?: string;
+            secondary?: string;
+            monospace?: string;
+        };
+        /** Tamanhos de fonte com hierarchy */
         fontSize?: {
-            banner?: string;
-            modal?: string;
+            /** Tamanhos para banner */
+            banner?: {
+                title?: string;
+                message?: string;
+                button?: string;
+            };
+            /** Tamanhos para modal */
+            modal?: {
+                title?: string;
+                body?: string;
+                button?: string;
+                caption?: string;
+            };
+            /** Scale tipográfica */
+            scale?: {
+                xs?: string;
+                sm?: string;
+                base?: string;
+                lg?: string;
+                xl?: string;
+                '2xl'?: string;
+                '3xl'?: string;
+            };
+            /** Tamanhos específicos de cabeçalhos */
+            h1?: string;
+            h2?: string;
+            h3?: string;
+            h4?: string;
+            h5?: string;
+            h6?: string;
         };
+        /** Pesos de fonte */
         fontWeight?: {
+            light?: number;
             normal?: number;
+            medium?: number;
+            semibold?: number;
             bold?: number;
         };
+        /** Altura de linha */
+        lineHeight?: {
+            tight?: number;
+            normal?: number;
+            relaxed?: number;
+            loose?: number;
+        };
+        /** Espaçamento de letras */
+        letterSpacing?: {
+            tight?: string;
+            normal?: string;
+            wide?: string;
+        };
     };
+    /**
+     * Sistema de espaçamento e dimensões flexível
+     */
     spacing?: {
+        /** Valores diretos de espaçamento */
+        xs?: string | number;
+        sm?: string | number;
+        md?: string | number;
+        lg?: string | number;
+        xl?: string | number;
+        /** Escala de espaçamento base */
+        scale?: {
+            xs?: string | number;
+            sm?: string | number;
+            md?: string | number;
+            lg?: string | number;
+            xl?: string | number;
+            '2xl'?: string | number;
+            '3xl'?: string | number;
+        };
+        /** Padding específico por componente */
         padding?: {
-            banner?: string | number;
-            modal?: string | number;
+            banner?: SpacingValue;
+            modal?: SpacingValue;
+            button?: SpacingValue;
+        };
+        /** Margem específica por componente */
+        margin?: {
+            banner?: SpacingValue;
+            modal?: SpacingValue;
+            button?: SpacingValue;
         };
+        /** Bordas arredondadas */
         borderRadius?: {
             banner?: string | number;
             modal?: string | number;
+            button?: string | number;
+            /** Scale de border radius */
+            scale?: {
+                none?: string | number;
+                sm?: string | number;
+                md?: string | number;
+                lg?: string | number;
+                xl?: string | number;
+                full?: string | number;
+            };
+        };
+        /** Configurações responsive */
+        responsive?: {
+            mobile?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
+            tablet?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
+            desktop?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
         };
     };
+    /**
+     * Configurações de layout e posicionamento
+     */
     layout?: {
-        position?: 'bottom' | 'top' | 'floating';
+        /** Posição do banner */
+        position?: 'bottom' | 'top' | 'floating' | 'center';
+        /** Larguras por breakpoint */
         width?: {
             mobile?: string;
+            tablet?: string;
+            desktop?: string;
+            max?: string;
+        };
+        /** Alturas específicas */
+        height?: {
+            banner?: HeightValue;
+            modal?: HeightValue;
+            button?: HeightValue;
+        };
+        /** Configuração do backdrop */
+        backdrop?: BackdropConfig;
+        /** Z-index para layering */
+        zIndex?: {
+            banner?: number;
+            modal?: number;
+            backdrop?: number;
+            floatingButton?: number;
+        };
+        /** Breakpoints customizados */
+        breakpoints?: {
+            mobile?: string;
+            tablet?: string;
             desktop?: string;
+            wide?: string;
+        };
+        /** Border radius para componentes */
+        borderRadius?: string | number | {
+            banner?: string | number;
+            modal?: string | number;
+            button?: string | number;
+            scale?: {
+                none?: string | number;
+                sm?: string | number;
+                md?: string | number;
+                lg?: string | number;
+                xl?: string | number;
+                full?: string | number;
+            };
+        };
+    };
+    /**
+     * Efeitos visuais e interações
+     */
+    effects?: {
+        /** Sombras */
+        shadow?: {
+            banner?: string;
+            modal?: string;
+            button?: string;
+            /** Scale de sombras */
+            scale?: {
+                none?: string;
+                sm?: string;
+                md?: string;
+                lg?: string;
+                xl?: string;
+            };
+        };
+        /** Transições e animações */
+        transitions?: {
+            duration?: {
+                fast?: string;
+                normal?: string;
+                slow?: string;
+            };
+            easing?: {
+                linear?: string;
+                easeIn?: string;
+                easeOut?: string;
+                easeInOut?: string;
+            };
+            /** Transições específicas */
+            banner?: {
+                enter?: string;
+                exit?: string;
+            };
+            modal?: {
+                enter?: string;
+                exit?: string;
+            };
+        };
+        /** Blur e filtros */
+        filters?: {
+            backdrop?: string;
+            disabled?: string;
+        };
+    };
+    /**
+     * Configurações de acessibilidade
+     */
+    accessibility?: {
+        /** Contraste mínimo */
+        contrast?: {
+            normal?: number;
+            enhanced?: number;
+        };
+        /** Configurações para motion */
+        motion?: {
+            respectPreferences?: boolean;
+            reducedMotion?: {
+                duration?: string;
+                easing?: string;
+            };
+        };
+        /** Focus indicators */
+        focus?: {
+            color?: string;
+            width?: string;
+            style?: 'solid' | 'dashed' | 'dotted';
+            offset?: string;
         };
-        backdrop?: boolean | string;
+    };
+    /**
+     * Temas e variações
+     */
+    themes?: {
+        /** Configurações específicas para tema claro */
+        light?: Partial<Omit<DesignTokens, 'themes'>>;
+        /** Configurações específicas para tema escuro */
+        dark?: Partial<Omit<DesignTokens, 'themes'>>;
+        /** Auto-detecção baseada no sistema */
+        auto?: boolean;
     };
 }
 /**
  * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
  * @category Types
  * @since 0.1.0
+ * @public
  *
  * @example Uso básico (configuração mínima):
  * ```tsx
@@ -647,7 +1216,7 @@ interface ConsentProviderProps {
      * texts={{
      *   controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
      *   dataTypes: 'Coletamos: endereço IP, preferências de navegação',
-     *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos dados'
+     *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos seus dados'
      * }}
      * ```
      */
@@ -782,6 +1351,31 @@ interface ConsentProviderProps {
      * Por padrão, os avisos já são desabilitados em builds de produção.
      */
     disableDeveloperGuidance?: boolean;
+    /**
+     * Desabilita o log automático de descoberta de cookies em modo desenvolvimento.
+     * Mesmo com `disableDeveloperGuidance` ativado, por padrão a descoberta é logada uma vez para ajudar o mapeamento.
+     * Use esta prop para suprimir também esse log experimental.
+     * @since 0.4.1
+     */
+    disableDiscoveryLog?: boolean;
+    /**
+     * Configuração avançada para o sistema de developer guidance.
+     * Permite controle granular sobre quais tipos de guias são exibidos e como.
+     * @since 0.4.1
+     * @example
+     * ```tsx
+     * // Usar preset de desenvolvimento
+     * guidanceConfig={GUIDANCE_PRESETS.development}
+     *
+     * // Configuração personalizada
+     * guidanceConfig={{
+     *   showWarnings: true,
+     *   showComplianceScore: true,
+     *   minimumSeverity: 'warning'
+     * }}
+     * ```
+     */
+    guidanceConfig?: GuidanceConfig;
     /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
@@ -789,6 +1383,7 @@ interface ConsentProviderProps {
  * Props esperadas por um componente customizado de CookieBanner.
  * @category Types
  * @since 0.3.1
+ * @public
  * Fornece acesso ao estado de consentimento e ações necessárias para o banner.
  */
 interface CustomCookieBannerProps {
@@ -808,6 +1403,7 @@ interface CustomCookieBannerProps {
  * Props esperadas por um componente customizado de PreferencesModal.
  * @category Types
  * @since 0.3.1
+ * @public
  *
  * Fornece acesso às preferências atuais do usuário, funções para atualizar e salvar preferências,
  * fechar o modal e textos customizados da interface.
@@ -829,6 +1425,7 @@ interface CustomPreferencesModalProps {
  * Props esperadas por um componente customizado de FloatingPreferencesButton.
  * @category Types
  * @since 0.3.1
+ * @public
  * Fornece acesso às ações de abertura do modal e ao estado de consentimento.
  */
 interface CustomFloatingPreferencesButtonProps {
@@ -839,6 +1436,7 @@ interface CustomFloatingPreferencesButtonProps {
  * Valor do contexto de consentimento, incluindo estado e métodos de manipulação.
  * @category Types
  * @since 0.1.0
+ * @public
  */
 interface ConsentContextValue {
     /** Indica se o usuário consentiu. */
@@ -851,8 +1449,28 @@ interface ConsentContextValue {
     acceptAll: () => void;
     /** Rejeita todas as categorias de consentimento. */
     rejectAll: () => void;
-    /** Define a preferência para uma categoria específica. */
-    setPreference: (cat: Category, value: boolean) => void;
+    /**
+     * Define a preferência para uma categoria específica.
+     * Suporta tanto categorias predefinidas quanto customizadas.
+     *
+     * @param cat - ID da categoria (predefinida ou customizada)
+     * @param value - Valor do consentimento para a categoria
+     *
+     * @breakingChange
+     * **v0.4.1**: Parâmetro `cat` mudou de `Category` para `string` para suportar
+     * categorias customizadas. O uso com strings literais continua funcionando.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Continua funcionando (categorias predefinidas)
+     * setPreference('analytics', true)
+     * setPreference('marketing', false)
+     *
+     * // ✅ Novo: categorias customizadas
+     * setPreference('custom-tracking', true)
+     * ```
+     */
+    setPreference: (cat: string, value: boolean) => void;
     /** Define múltiplas preferências de uma vez e salva. */
     setPreferences: (preferences: ConsentPreferences) => void;
     /** Abre o modal de preferências. */
@@ -910,7 +1528,7 @@ interface ConsentContextValue {
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, theme, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, theme, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: ConsentTexts;
 
 /**
@@ -1353,185 +1971,63 @@ declare function useConsentTexts(): ConsentTexts;
  */
 declare function useConsentHydration(): boolean;
 /**
- * Hook que retorna uma função para abrir o modal de preferências de forma programática.
- * @hook
+ * @function
  * @category Hooks
- * @since 0.3.1+
- * @remarks
- * Este hook oferece uma maneira ReactJS-idiomática de abrir o modal de preferências
- * em qualquer lugar da aplicação. Diferente do botão flutuante padrão, permite
- * controle total sobre quando e como o modal é acionado.
- *
- * ### Casos de Uso Principais
- * - **Links no footer/header**: "Configurações de Cookies", "Preferências"
- * - **Botões customizados**: Design próprio para abrir preferências
- * - **Fluxos condicionais**: Abrir modal baseado em ações do usuário
- * - **Integração com menus**: Adicionar item de menu para configurações
- *
- * ### Vantagens sobre função global
- * - **Type-safe**: TypeScript com tipagem completa
- * - **React-friendly**: Integra com ciclo de vida dos componentes
- * - **Automático**: Sem necessidade de verificar se ConsentProvider existe
- * - **Testável**: Fácil de mockar em testes unitários
- *
- * ### Performance
- * - Função estável: não causa re-renders quando usada como dependency
- * - Memoizada internamente para otimização
- * - Sem overhead: apenas proxy para ação interna do contexto
- *
- * @returns Uma função estável que abre o modal de preferências quando chamada
- *
- * @throws {Error} Se usado fora do ConsentProvider - verifique se está dentro de `<ConsentProvider>`
- *
- * @example Hook básico no footer
- * ```tsx
- * function MeuFooter() {
- *   const abrirModal = useOpenPreferencesModal();
- *
- *   return (
- *     <footer>
- *       <a href="#" onClick={abrirModal}>
- *         Configurações de Cookies
- *       </a>
- *     </footer>
- *   );
- * }
- * ```
+ * @since 0.3.1
+ * Hook para abrir o modal de preferências programaticamente.
  *
- * @example Botão customizado com ícone
- * ```tsx
- * import { Settings } from '@mui/icons-material';
+ * @returns Função para abrir o modal de preferências.
  *
- * function CustomPreferencesButton() {
- *   const openModal = useOpenPreferencesModal();
+ * @remarks
+ * Este hook retorna uma função que pode ser usada para abrir o modal de preferências
+ * de qualquer lugar dentro do contexto do ConsentProvider. É útil para criar botões
+ * customizados ou trigger o modal baseado em eventos específicos.
  *
- *   return (
- *     <button
- *       onClick={openModal}
- *       className="preferences-btn"
- *       aria-label="Configurar cookies"
- *     >
- *       <Settings /> Cookies
- *     </button>
- *   );
- * }
- * ```
+ * @throws {Error} Se usado fora do ConsentProvider
  *
- * @example Menu dropdown com opções
+ * @example
  * ```tsx
- * function UserMenu() {
+ * function CustomButton() {
  *   const openPreferences = useOpenPreferencesModal();
- *   const [menuOpen, setMenuOpen] = useState(false);
  *
  *   return (
- *     <div className="user-menu">
- *       <button onClick={() => setMenuOpen(!menuOpen)}>
- *         Menu ▼
- *       </button>
- *       {menuOpen && (
- *         <ul>
- *           <li><a href="/profile">Meu Perfil</a></li>
- *           <li><a href="/settings">Configurações</a></li>
- *           <li>
- *             <button onClick={openPreferences}>
- *               Preferências de Cookies
- *             </button>
- *           </li>
- *         </ul>
- *       )}
- *     </div>
+ *     <button onClick={openPreferences}>
+ *       Configurar Cookies
+ *     </button>
  *   );
  * }
  * ```
+ */
+declare function useOpenPreferencesModal(): () => void;
+/**
+ * @function
+ * @category Utils
+ * @since 0.3.1
+ * Função global para abrir o modal de preferências de fora do contexto React.
  *
- * @example Integração com router para mudança de página
- * ```tsx
- * function CookieSettingsPage() {
- *   const openModal = useOpenPreferencesModal();
- *   const navigate = useNavigate(); // React Router
- *
- *   React.useEffect(() => {
- *     // Abre modal automaticamente na página de configurações
- *     openModal();
- *   }, [openModal]);
- *
- *   const handleModalClose = () => {
- *     // Volta para página anterior quando modal fechar
- *     navigate(-1);
- *   };
- *
- *   return <div>Configurações de cookies carregando...</div>;
- * }
- * ```
+ * @remarks
+ * Esta função permite abrir o modal de preferências de código JavaScript puro,
+ * sem precisar estar dentro do contexto React. É útil para integração com
+ * código legado ou bibliotecas de terceiros.
  *
- * @example Hook condicional com verificação de consentimento
- * ```tsx
- * function SmartCookieButton() {
- *   const { consented } = useConsent();
- *   const openPreferences = useOpenPreferencesModal();
+ * A função é automaticamente registrada pelo ConsentProvider e limpa quando
+ * o provider é desmontado.
  *
- *   // Se usuário já deu consentimento, mostra "Alterar"
- *   // Se não deu consentimento, mostra "Configurar"
- *   const buttonText = consented ? 'Alterar Preferências' : 'Configurar Cookies';
- *   const buttonIcon = consented ? '⚙️' : '🍪';
+ * @example
+ * ```javascript
+ * // Em código JavaScript puro
+ * window.openPreferencesModal?.();
  *
- *   return (
- *     <button
- *       onClick={openPreferences}
- *       className={consented ? 'modify-btn' : 'setup-btn'}
- *     >
- *       {buttonIcon} {buttonText}
- *     </button>
- *   );
- * }
+ * // Ou importando diretamente
+ * import { openPreferencesModal } from 'react-lgpd-consent';
+ * openPreferencesModal();
  * ```
  */
-declare function useOpenPreferencesModal(): () => void;
 declare function openPreferencesModal(): void;
 
 /**
- * @interface DeveloperGuidance
- * Define a estrutura do objeto de orientação para desenvolvedores, contendo avisos, sugestões e informações sobre categorias ativas.
- */
-interface DeveloperGuidance {
-    /** Um array de strings, cada uma representando um aviso sobre a configuração. */
-    warnings: string[];
-    /** Um array de strings, cada uma representando uma sugestão para melhorar a conformidade ou UX. */
-    suggestions: string[];
-    /** Um array de objetos, cada um descrevendo uma categoria de cookie ativa e suas propriedades relevantes para a UI. */
-    activeCategoriesInfo: {
-        id: string;
-        name: string;
-        description: string;
-        essential: boolean;
-        uiRequired: boolean;
-    }[];
-    /** Indica se a configuração padrão da biblioteca está sendo utilizada (quando nenhuma configuração explícita é fornecida). */
-    usingDefaults: boolean;
-}
-/**
- * @constant
- * @category Utils
- * @since 0.2.2
- * Configuração padrão de categorias de cookies utilizada quando o desenvolvedor não especifica nenhuma configuração.
- * Inclui apenas a categoria 'analytics' além da 'necessary' (que é sempre incluída).
- */
-declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
-/**
- * @function
- * @category Utils
- * @since 0.2.2
- * Analisa a configuração de categorias do projeto e gera um objeto de orientação para o desenvolvedor.
- * Este objeto contém avisos, sugestões e informações detalhadas sobre as categorias ativas.
- *
- * @param {ProjectCategoriesConfig} [config] A configuração de categorias fornecida pelo desenvolvedor. Se não for fornecida, a configuração padrão será utilizada.
- * @returns {DeveloperGuidance} Um objeto `DeveloperGuidance` com a análise da configuração.
- */
-declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
-
-/**
- * @interface CategoriesContextValue
- * O valor fornecido pelo `CategoriesContext`, contendo informações sobre as categorias de cookies ativas no projeto.
+ * @interface CategoriesContextValue
+ * O valor fornecido pelo `CategoriesContext`, contendo informações sobre as categorias de cookies ativas no projeto.
  */
 interface CategoriesContextValue {
     /** A configuração final das categorias, incluindo padrões aplicados. */
@@ -1592,6 +2088,15 @@ declare function ConsentGate(props: Readonly<{
     children: React$1.ReactNode;
 }>): react_jsx_runtime.JSX.Element | null;
 
+/** @module src/utils/scriptLoader */
+/**
+ * @category Utils
+ * @since 0.1.0
+ * Utilitários para carregamento dinâmico e seguro de scripts externos no DOM.
+ *
+ * Fornece funções para carregar scripts de terceiros de forma condicional ao consentimento LGPD,
+ * garantindo compatibilidade SSR e verificações de permissões por categoria.
+ */
 /**
  * @function
  * @category Utils
@@ -1605,7 +2110,7 @@ declare function ConsentGate(props: Readonly<{
  *
  * @param {string} id Um identificador único para o elemento `<script>` a ser criado.
  * @param {string} src A URL do script externo a ser carregado.
- * @param {import('../types/types').Category | null} [category=null] A categoria de consentimento exigida para o script. Se o consentimento para esta categoria não for dado, o script não será carregado.
+ * @param {string | null} [category=null] A categoria de consentimento exigida para o script. Suporta tanto categorias predefinidas quanto customizadas. Se o consentimento para esta categoria não for dado, o script não será carregado.
  * @param {Record<string, string>} [attrs={}] Atributos adicionais a serem aplicados ao elemento `<script>` (ex: `{ async: 'true' }`).
  * @returns {Promise<void>} Uma Promise que resolve quando o script é carregado com sucesso, ou rejeita se o consentimento não for dado ou ocorrer um erro de carregamento.
  * @example
@@ -1616,11 +2121,64 @@ declare function ConsentGate(props: Readonly<{
  *   .catch(error => console.error('Erro ao carregar script:', error))
  * ```
  */
+declare function loadScript(id: string, src: string, category?: string | null, attrs?: Record<string, string>): Promise<void>;
+
+/**
+ * Utilitários para descoberta e categorização de cookies em tempo de execução (experimental).
+ *
+ * Fornece funções para detectar cookies presentes no navegador, identificar o cookie de consentimento
+ * e atribuir cookies descobertos a categorias LGPD usando heurísticas baseadas em padrões conhecidos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ * @remarks Funcionalidades experimentais para auxiliar no mapeamento de cookies em conformidade com LGPD.
+ *          Recomenda-se uso em desenvolvimento para inspeção manual e merge com catálogo existente.
+ */
+
+/**
+ * Descobre cookies em tempo de execução no navegador (experimental).
+ *
+ * - Lê `document.cookie` com segurança (SSR-safe)
+ * - Retorna lista de cookies detectados (apenas nomes)
+ * - Salva em `globalThis.__LGPD_DISCOVERED_COOKIES__` para inspeção/manual merge
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function discoverRuntimeCookies(): CookieDescriptor[];
+/**
+ * Tenta detectar o nome do cookie de consentimento pela estrutura JSON armazenada.
+ * Retorna o nome se for encontrado, caso contrário `null`.
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function detectConsentCookieName(): string | null;
+/**
+ * Heurística simples para atribuir cookies descobertos a categorias LGPD (experimental).
+ *
+ * - Usa padrões conhecidos por categoria
+ * - Ignora `cookieConsent` (já tratado como necessary)
+ * - Pode opcionalmente registrar overrides de catálogo por categoria
+ *
+ * @param discovered Lista de cookies descobertos (opcional: usa global se ausente)
+ * @param registerOverrides Se `true`, registra em `setCookieCatalogOverrides`
+ * @returns Mapa categoria -> descritores atribuídos
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function categorizeDiscoveredCookies(discovered?: CookieDescriptor[], registerOverrides?: boolean): Record<Category, CookieDescriptor[]>;
 
-declare function loadScript(id: string, src: string, category?: Category | null, attrs?: Record<string, string>): Promise<void>;
+/** @module src/utils/theme */
+/**
+ * @category Utils
+ * @since 0.1.0
+ * Utilitários para criação e gerenciamento de temas Material-UI para componentes de consentimento LGPD.
+ *
+ * Fornece um tema padrão consistente e acessível, com opções de personalização.
+ */
 
 /**
- * @constant
+ * @function
  * @category Utils
  * @since 0.1.0
  * Tema padrão utilizado pelos componentes de consentimento da biblioteca.
@@ -1628,6 +2186,16 @@ declare function loadScript(id: string, src: string, category?: Category | null,
  * Inclui configurações de cores, tipografia e estilos para componentes Material-UI,
  * garantindo aparência consistente e acessível conforme guidelines LGPD.
  *
+ * @returns {Theme} Instância do tema Material-UI configurado.
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultConsentTheme } from 'react-lgpd-consent'
+ *
+ * const theme = createDefaultConsentTheme()
+ * // Use com ThemeProvider
+ * ```
+ *
  * @remarks
  * Pode ser sobrescrito via ThemeProvider externo se necessário.
  */
@@ -1638,99 +2206,225 @@ declare function createDefaultConsentTheme(): Theme;
  * @deprecated Use `createDefaultConsentTheme()` em vez de importar um tema criado no escopo do módulo.
  * Importar um tema já instanciado pode causar side-effects em SSR e conflitos de contexto.
  * Esta função retorna uma nova instância do tema quando chamada.
+ *
+ * @returns {Theme} Instância do tema Material-UI configurado.
+ *
+ * @example
+ * ```typescript
+ * import { defaultConsentTheme } from 'react-lgpd-consent'
+ *
+ * const theme = defaultConsentTheme()
+ * // Deprecated, use createDefaultConsentTheme instead
+ * ```
  */
 declare const defaultConsentTheme: () => Theme;
 
 /**
- * @interface ScriptIntegration
- * Estrutura de uma integração de script de terceiros a ser carregada condicionalmente conforme o consentimento.
+ * @fileoverview
+ * Integrações nativas de scripts (GA, GTM, Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom, Zendesk, UserWay)
+ * com categorias LGPD padrão, cookies típicos e pontos de extensão para URLs.
+ *
+ * Princípios:
+ * - Cada integração define uma categoria padrão (mais aderente ao uso no mercado)
+ * - Cada cookie típico aparece em uma única categoria por padrão
+ * - URLs possuem valores default atualizados e podem ser sobrescritos via `scriptUrl`
+ * - SSR-safe: toda execução que toca `window` é protegida
+ */
+/**
+ * Integração de script de terceiros condicionada a consentimento.
+ *
+ * @category Utils
+ * @since 0.2.0
  *
  * @remarks
- * - `category` é um `Category` tipado (ex.: 'analytics', 'marketing').
- * - `init` roda após o script ser inserido no DOM e carregado.
- * - `attrs` é repassado como atributos HTML da tag `<script>`.
+ * **Breaking Change em v0.4.1**: O campo `category` mudou de `Category` para `string`
+ * para suportar categorias customizadas. Código existente usando strings literais
+ * continua funcionando sem alterações.
+ *
+ * @example
+ * ```typescript
+ * const integration: ScriptIntegration = {
+ *   id: 'my-script',
+ *   category: 'analytics',
+ *   src: 'https://example.com/script.js',
+ *   cookies: ['_example'],
+ *   init: () => console.log('Script initialized')
+ * }
+ * ```
  */
-
 interface ScriptIntegration {
-    /** Um ID único para esta integração de script. */
+    /** Identificador único da integração */
     id: string;
-    /** Categoria de consentimento necessária para carregar o script. */
-    category: Category;
-    /** A URL do script a ser carregado. */
+    /**
+     * Categoria LGPD à qual o script pertence.
+     * Suporta tanto categorias predefinidas quanto customizadas.
+     */
+    category: string;
+    /** Nome legível da integração (opcional) */
+    name?: string;
+    /** URL do script a ser carregado */
     src: string;
-    /** Uma função opcional a ser executada após o script ser carregado e inicializado no DOM. */
+    /** Se o script deve ser carregado de forma assíncrona */
+    async?: boolean;
+    /** Se o script deve ser deferido */
+    defer?: boolean;
+    /** Configuração específica da integração */
+    config?: Record<string, unknown>;
+    /** Função de inicialização executada após carregamento do script */
     init?: () => void;
-    /** Um objeto de atributos HTML a serem adicionados à tag `<script>` (ex: `{ async: 'true' }`). */
+    /** Atributos HTML adicionais para a tag script */
     attrs?: Record<string, string>;
+    /** Lista de cookies que o script pode definir */
+    cookies?: string[];
+    /** Informações detalhadas dos cookies (nome, finalidade, duração, fornecedor) */
+    cookiesInfo?: Array<{
+        name: string;
+        purpose: string;
+        duration: string;
+        provider: string;
+    }>;
 }
 /**
- * @interface GoogleAnalyticsConfig
- * Configuração específica para a integração com o Google Analytics 4 (GA4).
+ * Configuração para integração do Google Analytics (GA4).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: GoogleAnalyticsConfig = {
+ *   measurementId: 'G-XXXXXXXXXX',
+ *   config: { anonymize_ip: true }
+ * }
+ * ```
  */
 interface GoogleAnalyticsConfig {
-    /** O ID de medição do GA4 (ex: 'G-XXXXXXXXXX'). */
+    /** ID de medição do GA4 (formato: G-XXXXXXXXXX) */
     measurementId: string;
-    /** Objeto opcional repassado para `gtag('config')`. */
+    /** Configurações adicionais para o gtag */
     config?: Record<string, unknown>;
+    /** URL do script GA4. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
 }
 /**
- * @interface GoogleTagManagerConfig
- * Configuração específica para a integração com o Google Tag Manager (GTM).
+ * Configuração para integração do Google Tag Manager (GTM).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: GoogleTagManagerConfig = {
+ *   containerId: 'GTM-XXXXXXX',
+ *   dataLayerName: 'customDataLayer'
+ * }
+ * ```
  */
 interface GoogleTagManagerConfig {
-    /** O ID do contêiner do GTM (ex: 'GTM-XXXXXXX'). */
+    /** ID do container GTM (formato: GTM-XXXXXXX) */
     containerId: string;
-    /** O nome da camada de dados (dataLayer) a ser usada. Padrão: 'dataLayer'. */
+    /** Nome customizado para o dataLayer. Padrão: 'dataLayer' */
     dataLayerName?: string;
+    /** URL do script GTM. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
 }
 /**
- * @interface UserWayConfig
- * Configuração específica para a integração com o widget de acessibilidade UserWay.
+ * Configuração para integração do UserWay (Acessibilidade).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: UserWayConfig = {
+ *   accountId: 'XXXXXXXXXX'
+ * }
+ * ```
  */
 interface UserWayConfig {
-    /** O ID da conta UserWay. */
+    /** ID da conta UserWay */
     accountId: string;
+    /** URL do script UserWay. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
 }
 /**
- * @function
+ * Cria integração do Google Analytics (GA4).
+ * Configura o gtag e inicializa o tracking com o measurement ID fornecido.
+ *
  * @category Utils
+ * @param config - Configuração do Google Analytics
+ * @returns Integração configurada para o GA4
  * @since 0.2.0
- * Cria uma integração para Google Analytics 4 (GA4).
  *
- * @param {GoogleAnalyticsConfig} config Configuração com `measurementId` e `config` opcional.
- * @returns {ScriptIntegration} Integração tipada com `category: 'analytics'`.
+ * @example
+ * ```typescript
+ * const ga = createGoogleAnalyticsIntegration({
+ *   measurementId: 'G-XXXXXXXXXX',
+ *   config: { anonymize_ip: true }
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _ga, _ga_*, _gid
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
  */
 declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
 /**
- * @function
+ * Cria integração do Google Tag Manager (GTM).
+ * Configura o dataLayer e inicializa o container GTM.
+ *
  * @category Utils
+ * @param config - Configuração do Google Tag Manager
+ * @returns Integração configurada para o GTM
  * @since 0.2.0
- * Cria uma integração para Google Tag Manager (GTM).
  *
- * @param {GoogleTagManagerConfig} config Configuração com `containerId` e `dataLayerName` opcional.
- * @returns {ScriptIntegration} Integração tipada com `category: 'analytics'`.
+ * @example
+ * ```typescript
+ * const gtm = createGoogleTagManagerIntegration({
+ *   containerId: 'GTM-XXXXXXX',
+ *   dataLayerName: 'myDataLayer'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _gcl_au
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
  */
 declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
 /**
- * @function
+ * Cria integração do UserWay (Acessibilidade).
+ * Configura o widget de acessibilidade UserWay.
+ *
  * @category Utils
+ * @param config - Configuração do UserWay
+ * @returns Integração configurada para o UserWay
  * @since 0.2.0
- * Cria uma integração para o widget de acessibilidade UserWay.
  *
- * @param {UserWayConfig} config Configuração com `accountId`.
- * @returns {ScriptIntegration} Integração tipada com `category: 'functional'`.
+ * @example
+ * ```typescript
+ * const userway = createUserWayIntegration({
+ *   accountId: 'XXXXXXXXXX'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _userway_*
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
  */
 declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
 /**
- * @constant
+ * Funções fábricas para integrações comuns.
+ * Fornece acesso direto às funções de criação de integrações pré-configuradas.
+ *
  * @category Utils
  * @since 0.2.0
- * Objeto contendo as factory functions para as integrações pré-configuradas mais comuns.
  *
  * @example
- * ```tsx
- * import { COMMON_INTEGRATIONS } from 'react-lgpd-consent';
- * const gaIntegration = COMMON_INTEGRATIONS.googleAnalytics({ measurementId: 'G-XYZ' });
+ * ```typescript
+ * const ga = COMMON_INTEGRATIONS.googleAnalytics({ measurementId: 'G-XXXXXXXXXX' })
  * ```
  */
 declare const COMMON_INTEGRATIONS: {
@@ -1738,6 +2432,485 @@ declare const COMMON_INTEGRATIONS: {
     googleTagManager: typeof createGoogleTagManagerIntegration;
     userway: typeof createUserWayIntegration;
 };
+/**
+ * Configuração para integração do Facebook Pixel.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: FacebookPixelConfig = {
+ *   pixelId: '1234567890123456',
+ *   autoTrack: true,
+ *   advancedMatching: { email: 'user@example.com' }
+ * }
+ * ```
+ */
+interface FacebookPixelConfig {
+    /** ID do pixel do Facebook */
+    pixelId: string;
+    /** Se deve rastrear PageView automaticamente. Padrão: true */
+    autoTrack?: boolean;
+    /** Configuração de correspondência avançada */
+    advancedMatching?: Record<string, unknown>;
+    /** URL do script do Pixel. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Hotjar.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: HotjarConfig = {
+ *   siteId: '1234567',
+ *   version: 6,
+ *   debug: false
+ * }
+ * ```
+ */
+interface HotjarConfig {
+    /** ID do site no Hotjar */
+    siteId: string;
+    /** Versão do script Hotjar. Padrão: 6 */
+    version?: number;
+    /** Ativar modo debug. Padrão: false */
+    debug?: boolean;
+    /** URL do script Hotjar. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Mixpanel.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: MixpanelConfig = {
+ *   token: 'your-project-token',
+ *   config: { debug: true },
+ *   api_host: 'https://api.mixpanel.com'
+ * }
+ * ```
+ */
+interface MixpanelConfig {
+    /** Token do projeto Mixpanel */
+    token: string;
+    /** Configurações adicionais do Mixpanel */
+    config?: Record<string, unknown>;
+    /** Host customizado da API Mixpanel */
+    api_host?: string;
+    /** URL do script Mixpanel. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Microsoft Clarity.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ClarityConfig = {
+ *   projectId: 'abcdefghij',
+ *   upload: true
+ * }
+ * ```
+ */
+interface ClarityConfig {
+    /** ID do projeto no Microsoft Clarity */
+    projectId: string;
+    /** Configuração de upload de dados. Padrão: indefinido */
+    upload?: boolean;
+    /** URL do script Clarity. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Intercom.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: IntercomConfig = {
+ *   app_id: 'your-app-id'
+ * }
+ * ```
+ */
+interface IntercomConfig {
+    /** ID da aplicação Intercom */
+    app_id: string;
+    /** URL do script Intercom. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Zendesk Chat.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ZendeskConfig = {
+ *   key: 'your-zendesk-key'
+ * }
+ * ```
+ */
+interface ZendeskConfig {
+    /** Chave de identificação do Zendesk */
+    key: string;
+    /** URL do script Zendesk. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Cria integração do Facebook Pixel.
+ * Configura o fbq e inicializa o pixel com tracking automático opcional.
+ *
+ * @category Utils
+ * @param config - Configuração do Facebook Pixel
+ * @returns Integração configurada para o Facebook Pixel
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const pixel = createFacebookPixelIntegration({
+ *   pixelId: '1234567890123456',
+ *   autoTrack: true
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _fbp, fr
+ * - Categoria padrão: 'marketing'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createFacebookPixelIntegration(config: FacebookPixelConfig): ScriptIntegration;
+/**
+ * Cria integração do Hotjar.
+ * Configura as configurações do Hotjar e inicializa o tracking de heatmaps e gravações.
+ *
+ * @category Utils
+ * @param config - Configuração do Hotjar
+ * @returns Integração configurada para o Hotjar
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const hotjar = createHotjarIntegration({
+ *   siteId: '1234567',
+ *   debug: true
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _hjSession_*, _hjSessionUser_*, _hjFirstSeen, _hjIncludedInSessionSample, _hjAbsoluteSessionInProgress
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createHotjarIntegration(config: HotjarConfig): ScriptIntegration;
+/**
+ * Cria integração do Mixpanel.
+ * Configura e inicializa o Mixpanel para analytics de eventos.
+ *
+ * @category Utils
+ * @param config - Configuração do Mixpanel
+ * @returns Integração configurada para o Mixpanel
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const mixpanel = createMixpanelIntegration({
+ *   token: 'your-project-token',
+ *   config: { debug: true }
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: mp_*
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na inicialização
+ */
+declare function createMixpanelIntegration(config: MixpanelConfig): ScriptIntegration;
+/**
+ * Cria integração do Microsoft Clarity.
+ * Configura o Microsoft Clarity para heatmaps e analytics de comportamento.
+ *
+ * @category Utils
+ * @param config - Configuração do Microsoft Clarity
+ * @returns Integração configurada para o Clarity
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const clarity = createClarityIntegration({
+ *   projectId: 'abcdefghij',
+ *   upload: false
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _clck, _clsk, CLID, ANONCHK, MR, MUID, SM
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Configuração de upload opcional
+ */
+declare function createClarityIntegration(config: ClarityConfig): ScriptIntegration;
+/**
+ * Cria integração do Intercom.
+ * Configura o widget de chat e suporte do Intercom.
+ *
+ * @category Utils
+ * @param config - Configuração do Intercom
+ * @returns Integração configurada para o Intercom
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const intercom = createIntercomIntegration({
+ *   app_id: 'your-app-id'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: intercom-id-*, intercom-session-*
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na inicialização
+ */
+declare function createIntercomIntegration(config: IntercomConfig): ScriptIntegration;
+/**
+ * Cria integração do Zendesk Chat.
+ * Configura o widget de chat e suporte do Zendesk.
+ *
+ * @category Utils
+ * @param config - Configuração do Zendesk Chat
+ * @returns Integração configurada para o Zendesk Chat
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const zendesk = createZendeskChatIntegration({
+ *   key: 'your-zendesk-key'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: __zlcmid, _zendesk_shared_session
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na identificação
+ */
+declare function createZendeskChatIntegration(config: ZendeskConfig): ScriptIntegration;
+/**
+ * Configuração para conjunto de integrações de e-commerce.
+ * Define configurações opcionais para múltiplas integrações otimizadas para e-commerce.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ECommerceConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   facebookPixel: { pixelId: '1234567890123456' }
+ * }
+ * ```
+ */
+interface ECommerceConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Facebook Pixel */
+    facebookPixel?: FacebookPixelConfig;
+    /** Configuração do Hotjar */
+    hotjar?: HotjarConfig;
+    /** Configuração do UserWay */
+    userway?: UserWayConfig;
+}
+/**
+ * Configuração para conjunto de integrações de SaaS.
+ * Define configurações opcionais para múltiplas integrações otimizadas para SaaS.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: SaaSConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   mixpanel: { token: 'your-token' },
+ *   intercom: { app_id: 'your-app-id' }
+ * }
+ * ```
+ */
+interface SaaSConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Mixpanel */
+    mixpanel?: MixpanelConfig;
+    /** Configuração do Intercom */
+    intercom?: IntercomConfig;
+    /** Configuração do Hotjar */
+    hotjar?: HotjarConfig;
+}
+/**
+ * Configuração para conjunto de integrações corporativas.
+ * Define configurações opcionais para múltiplas integrações otimizadas para ambientes corporativos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: CorporateConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   clarity: { projectId: 'abcdefghij' },
+ *   userway: { accountId: 'XXXXXXXXXX' }
+ * }
+ * ```
+ */
+interface CorporateConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Microsoft Clarity */
+    clarity?: ClarityConfig;
+    /** Configuração do Zendesk Chat */
+    zendesk?: ZendeskConfig;
+    /** Configuração do UserWay */
+    userway?: UserWayConfig;
+}
+/**
+ * Cria conjunto de integrações otimizado para e-commerce.
+ * Combina analytics de conversão, remarketing e acessibilidade.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações de e-commerce
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createECommerceIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   facebookPixel: { pixelId: '1234567890123456' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, marketing, functional
+ */
+declare function createECommerceIntegrations(cfg: ECommerceConfig): ScriptIntegration[];
+/**
+ * Cria conjunto de integrações otimizado para SaaS.
+ * Combina analytics de produto, suporte ao cliente e comportamento do usuário.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações de SaaS
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createSaaSIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   mixpanel: { token: 'your-project-token' },
+ *   intercom: { app_id: 'your-app-id' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, functional
+ */
+declare function createSaaSIntegrations(cfg: SaaSConfig): ScriptIntegration[];
+/**
+ * Cria conjunto de integrações otimizado para ambientes corporativos.
+ * Combina analytics empresariais, compliance e suporte corporativo.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações corporativas
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createCorporateIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   clarity: { projectId: 'abcdefghij' },
+ *   userway: { accountId: 'XXXXXXXXXX' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, functional
+ */
+declare function createCorporateIntegrations(cfg: CorporateConfig): ScriptIntegration[];
+/**
+ * Templates pré-configurados de integrações por tipo de negócio.
+ * Define integrações essenciais e opcionais para cada contexto.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const template = INTEGRATION_TEMPLATES.ecommerce
+ * console.log(template.essential) // ['google-analytics', 'facebook-pixel']
+ * console.log(template.categories) // ['analytics', 'marketing', 'functional']
+ * ```
+ *
+ * @remarks
+ * Cada template define:
+ * - essential: integrações obrigatórias/recomendadas
+ * - optional: integrações complementares
+ * - categories: categorias LGPD utilizadas
+ */
+declare const INTEGRATION_TEMPLATES: {
+    ecommerce: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+    saas: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+    corporate: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+};
+/**
+ * Sugere categorias LGPD apropriadas para um script baseado no nome/tipo.
+ * Utiliza heurísticas para classificar scripts desconhecidos.
+ *
+ * @category Utils
+ * @param name - Nome ou identificador do script
+ * @returns Array de categorias sugeridas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * suggestCategoryForScript('facebook-pixel') // ['marketing']
+ * suggestCategoryForScript('hotjar') // ['analytics']
+ * suggestCategoryForScript('intercom-chat') // ['functional']
+ * suggestCategoryForScript('unknown-script') // ['analytics']
+ * ```
+ *
+ * @remarks
+ * Heurísticas aplicadas:
+ * - Scripts de ads/marketing → 'marketing'
+ * - Scripts de analytics/tracking → 'analytics'
+ * - Scripts de chat/suporte → 'functional'
+ * - Padrão para desconhecidos → 'analytics'
+ */
+declare function suggestCategoryForScript(name: string): string[];
 
 /**
  * Componente que carrega scripts automaticamente baseado no consentimento.
@@ -1801,6 +2974,378 @@ declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly
  */
 declare function useConsentScriptLoader(): (integration: ScriptIntegration) => Promise<boolean>;
 
+/**
+ * @file autoConfigureCategories.ts
+ * @description Sistema inteligente de auto-habilitação de categorias baseado nas integrações utilizadas
+ * @since 0.4.1
+ */
+
+/**
+ * @interface CategoryAutoConfigResult
+ * Resultado da análise e auto-configuração de categorias
+ */
+interface CategoryAutoConfigResult {
+    /** Configuração original fornecida pelo desenvolvedor */
+    originalConfig: ProjectCategoriesConfig;
+    /** Configuração ajustada automaticamente pela biblioteca */
+    adjustedConfig: ProjectCategoriesConfig;
+    /** Categorias que foram automaticamente habilitadas */
+    autoEnabledCategories: string[];
+    /** Categorias requeridas pelas integrações mas não habilitadas */
+    missingCategories: string[];
+    /** Se algum ajuste foi necessário */
+    wasAdjusted: boolean;
+    /** Integrações que requerem cada categoria */
+    categoryIntegrations: Record<string, string[]>;
+}
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Analisa as integrações fornecidas e determina quais categorias são necessárias.
+ *
+ * @param integrations Array de integrações de script
+ * @returns Record mapeando categoria para nomes das integrações que a utilizam
+ */
+declare function analyzeIntegrationCategories(integrations: ScriptIntegration[]): Record<string, string[]>;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Configura automaticamente as categorias necessárias baseado nas integrações utilizadas.
+ *
+ * Esta função implementa o comportamento inteligente da biblioteca:
+ * 1. Detecta categorias requeridas pelas integrações
+ * 2. Auto-habilita categorias em falta (modo padrão)
+ * 3. Ou apenas avisa sobre categorias em falta (modo warning-only)
+ * 4. Loga no console em modo DEV
+ *
+ * @param originalConfig Configuração original do ConsentProvider
+ * @param integrations Array de integrações que serão utilizadas
+ * @param options Opções de comportamento
+ * @returns Resultado da análise e configuração automática
+ */
+declare function autoConfigureCategories(originalConfig: ProjectCategoriesConfig | undefined, integrations: ScriptIntegration[], options?: {
+    /** Se true, apenas avisa mas não modifica a config (padrão: false - auto-habilita) */
+    warningOnly?: boolean;
+    /** Se true, desabilita logs no console (padrão: false) */
+    silent?: boolean;
+}): CategoryAutoConfigResult;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Valida se todas as integrações têm suas categorias habilitadas.
+ * Útil para validação em tempo de execução.
+ *
+ * @param integrations Array de integrações
+ * @param enabledCategories Array de categorias habilitadas
+ * @returns true se todas as categorias necessárias estão habilitadas
+ */
+declare function validateIntegrationCategories(integrations: ScriptIntegration[], enabledCategories: string[]): boolean;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Extrai categorias únicas de um array de integrações
+ *
+ * @param integrations Array de integrações
+ * @returns Array de categorias únicas
+ */
+declare function extractCategoriesFromIntegrations(integrations: ScriptIntegration[]): string[];
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Valida se integrações estão sendo incorretamente classificadas como "necessary".
+ *
+ * Esta função protege contra violações de GDPR/LGPD identificando scripts que
+ * NUNCA devem ser considerados estritamente necessários.
+ *
+ * @param integrations Array de integrações para validar
+ * @param enabledCategories Categorias habilitadas na configuração
+ * @returns Lista de avisos sobre classificações incorretas
+ *
+ * @example
+ * ```typescript
+ * const warnings = validateNecessaryClassification([
+ *   createGoogleAnalyticsIntegration({...}), // ❌ NUNCA é necessary
+ *   createCustomIntegration({...})           // ✅ Pode ser necessary se apropriado
+ * ], ['necessary', 'analytics'])
+ *
+ * if (warnings.length > 0) {
+ *   console.warn('Scripts incorretamente classificados como necessary:', warnings)
+ * }
+ * ```
+ */
+declare function validateNecessaryClassification(integrations: ScriptIntegration[], enabledCategories: Category[]): string[];
+
+/**
+ * @fileoverview
+ * Sistema de textos expandido com suporte avançado a internacionalização,
+ * contextos específicos e variações de tom.
+ *
+ * @author Luciano Édipo
+ * @since 0.4.1
+ */
+
+/**
+ * Tipo auxiliar para variações de texto.
+ *
+ * Define um subconjunto opcional dos textos principais do banner e modal,
+ * permitindo variações de t    es: {
+      bannerMessage: 'Utilizamos cookies para mejorar su experiencia y mostrar contenido personalizado.', (formal, casual, etc.) sem sobrescrever todos os textos.
+ *
+ * @category Types
+ * @since 0.4.1
+ */
+type TextVariant = Partial<Pick<ConsentTexts, 'bannerMessage' | 'acceptAll' | 'declineAll' | 'modalTitle'>>;
+/**
+ * Tipo auxiliar para textos de idioma.
+ *
+ * Define um subconjunto dos textos principais, excluindo propriedades específicas de internacionalização
+ * e contextos, para uso em configurações multilíngues.
+ *
+ * @category Types
+ * @since 0.4.1
+ */
+type LanguageTexts = Partial<Omit<ConsentTexts, 'i18n' | 'variants' | 'contexts'>>;
+/**
+ * Sistema de textos avançado com suporte a internacionalização e contextos específicos.
+ *
+ * Interface expandida que permite personalização granular de todas as mensagens da biblioteca.
+ * Suporta múltiplos idiomas, contextos específicos (e-commerce, SaaS, governo), variações
+ * de tom, e compliance completo com LGPD/ANPD.
+ *
+ * @category Types
+ * @since 0.4.1
+ * @version 0.4.1 - Nova interface com suporte avançado a i18n e contextos
+ *
+ * @example Configuração multilíngue
+ * ```typescript
+ * const multiLangTexts: AdvancedConsentTexts = {
+ *   // Herda de ConsentTexts básico
+ *   bannerMessage: 'Utilizamos cookies para melhorar sua experiência.',
+ *   acceptAll: 'Aceitar todos',
+ *   declineAll: 'Recusar',
+ *   preferences: 'Preferências',
+ *   modalTitle: 'Preferências de Cookies',
+ *   modalIntro: 'Personalize suas preferências de cookies.',
+ *   save: 'Salvar',
+ *   necessaryAlwaysOn: 'Cookies necessários (sempre ativos)',
+ *
+ *   // Textos expandidos
+ *   variants: {
+ *     formal: {
+ *       bannerMessage: 'Este sítio utiliza cookies para otimizar a experiência de navegação.',
+ *       acceptAll: 'Concordar com todos os cookies'
+ *     },
+ *     casual: {
+ *       bannerMessage: '🍪 Olá! Usamos cookies para tornar tudo mais gostoso aqui.',
+ *       acceptAll: 'Aceitar tudo'
+ *     }
+ *   },
+ *
+ *   // Internacionalização
+ *   i18n: {
+ *     en: {
+ *       bannerMessage: 'We use cookies to enhance your experience.',
+ *       acceptAll: 'Accept All',
+ *       declineAll: 'Decline'
+ *     },
+ *     es: {
+ *       bannerMessage: 'Utilizamos cookies para mejorar su experiencia.',
+ *       acceptAll: 'Aceptar Todo',
+ *       declineAll: 'Rechazar'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface AdvancedConsentTexts extends ConsentTexts {
+    /** Texto para confirmar ação */
+    confirm?: string;
+    /** Texto para cancelar ação */
+    cancel?: string;
+    /** Texto de carregamento */
+    loading?: string;
+    /** Textos específicos para cada categoria de cookie */
+    categories?: {
+        necessary?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        analytics?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        marketing?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        functional?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        performance?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+    };
+    /** Mensagens de feedback ao usuário */
+    feedback?: {
+        /** Preferências salvas com sucesso */
+        saveSuccess?: string;
+        /** Erro ao salvar preferências */
+        saveError?: string;
+        /** Consentimento atualizado */
+        consentUpdated?: string;
+        /** Cookies rejeitados */
+        cookiesRejected?: string;
+        /** Configurações resetadas */
+        settingsReset?: string;
+    };
+    /** Labels ARIA e textos para leitores de tela */
+    accessibility?: {
+        /** Label do banner para leitores de tela */
+        bannerLabel?: string;
+        /** Label do modal para leitores de tela */
+        modalLabel?: string;
+        /** Instrução de navegação por teclado */
+        keyboardNavigation?: string;
+        /** Estado do toggle de categoria */
+        toggleState?: {
+            enabled?: string;
+            disabled?: string;
+        };
+        /** Região live para anúncios dinâmicos */
+        liveRegion?: string;
+    };
+    /** Textos otimizados para diferentes contextos */
+    contexts?: {
+        /** Contexto e-commerce */
+        ecommerce?: {
+            cartAbandonment?: string;
+            personalizedOffers?: string;
+            paymentSecurity?: string;
+            productRecommendations?: string;
+        };
+        /** Contexto SaaS */
+        saas?: {
+            userAnalytics?: string;
+            performanceMonitoring?: string;
+            featureUsage?: string;
+            customerSupport?: string;
+        };
+        /** Contexto governamental */
+        government?: {
+            citizenServices?: string;
+            dataProtection?: string;
+            transparency?: string;
+            accessibility?: string;
+        };
+        /** Contexto educacional */
+        education?: {
+            studentProgress?: string;
+            learningAnalytics?: string;
+            accessibility?: string;
+            parentalConsent?: string;
+        };
+    };
+    /** Diferentes variações de tom para a mesma mensagem */
+    variants?: {
+        /** Tom formal/profissional */
+        formal?: TextVariant;
+        /** Tom casual/amigável */
+        casual?: TextVariant;
+        /** Tom conciso/direto */
+        concise?: TextVariant;
+        /** Tom detalhado/explicativo */
+        detailed?: TextVariant;
+    };
+    /** Suporte a múltiplos idiomas */
+    i18n?: {
+        /** Textos em inglês */
+        en?: LanguageTexts;
+        /** Textos em espanhol */
+        es?: LanguageTexts;
+        /** Textos em francês */
+        fr?: LanguageTexts;
+        /** Textos em alemão */
+        de?: LanguageTexts;
+        /** Textos em italiano */
+        it?: LanguageTexts;
+    };
+    /** Informações técnicas sobre cookies */
+    technical?: {
+        /** Explicação sobre cookies de sessão */
+        sessionCookies?: string;
+        /** Explicação sobre cookies persistentes */
+        persistentCookies?: string;
+        /** Explicação sobre cookies de terceiros */
+        thirdPartyCookies?: string;
+        /** Como desabilitar cookies no navegador */
+        browserSettings?: string;
+        /** Impacto de desabilitar cookies */
+        disablingImpact?: string;
+    };
+    /** Cabeçalhos para tabela de detalhes de cookies */
+    cookieDetails?: {
+        tableHeaders?: {
+            name?: string;
+            purpose?: string;
+            duration?: string;
+            provider?: string;
+            type?: string;
+        };
+        /** Texto quando não há cookies para mostrar */
+        noCookies?: string;
+        /** Botão para expandir/colapsar detalhes */
+        toggleDetails?: {
+            expand?: string;
+            collapse?: string;
+        };
+    };
+}
+/**
+ * Textos padrão expandidos para diferentes contextos e idiomas.
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare const EXPANDED_DEFAULT_TEXTS: Partial<AdvancedConsentTexts>;
+/**
+ * Utilitário para resolver textos baseado em idioma, contexto e variação.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @param texts - Textos avançados configurados
+ * @param options - Opções de resolução
+ * @returns Textos resolvidos para o contexto
+ */
+declare function resolveTexts(texts: AdvancedConsentTexts, options?: {
+    language?: 'pt' | 'en' | 'es' | 'fr' | 'de' | 'it';
+    context?: 'ecommerce' | 'saas' | 'government' | 'education';
+    variant?: 'formal' | 'casual' | 'concise' | 'detailed';
+}): ConsentTexts;
+/**
+ * Templates pré-configurados para diferentes contextos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare const TEXT_TEMPLATES: {
+    readonly ecommerce: AdvancedConsentTexts;
+    readonly saas: AdvancedConsentTexts;
+    readonly government: AdvancedConsentTexts;
+};
+
 /**
  * @enum LogLevel
  * @category Utils
@@ -1840,6 +3385,17 @@ declare enum LogLevel {
  */
 declare function setDebugLogging(enabled: boolean, level?: LogLevel): void;
 
+interface CookieCatalogOverrides {
+    byCategory?: Record<string, CookieDescriptor[]>;
+    byIntegration?: Record<string, CookieDescriptor[]>;
+}
+interface CookieCategoryOverrides {
+    [cookieNameOrPattern: string]: Category;
+}
+declare function setCookieCatalogOverrides(overrides: CookieCatalogOverrides): void;
+declare function setCookieCategoryOverrides(map: CookieCategoryOverrides): void;
+declare function getCookiesInfoForCategory(categoryId: Category, usedIntegrations: string[]): CookieDescriptor[];
+
 /**
  * Propriedades para customizar o comportamento e aparência do componente CookieBanner.
  *
@@ -1902,6 +3458,11 @@ interface CookieBannerProps {
      * @example "/privacy-policy" | "https://example.com/cookies"
      */
     policyLinkUrl?: string;
+    /**
+     * URL para os termos de uso do site (opcional). Quando fornecida, será considerada uma rota "segura"
+     * para não aplicar bloqueio total (overlay) mesmo em modo bloqueante.
+     */
+    termsLinkUrl?: string;
     /**
      * Força exibição do banner em modo de debug, independente do consentimento.
      *
@@ -2063,7 +3624,7 @@ interface CookieBannerProps {
  * @public
  * @since 0.1.0
  */
-declare function CookieBanner({ policyLinkUrl, debug, blocking, hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
+declare function CookieBanner({ policyLinkUrl, termsLinkUrl, debug, blocking, hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Props para o componente FloatingPreferencesButton.
@@ -2104,6 +3665,16 @@ interface FloatingPreferencesButtonProps {
  */
 declare function FloatingPreferencesButton({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
 
+/** @module src/utils/categoryUtils */
+/**
+ * @category Utils
+ * @since 0.2.0
+ * Utilitários para gerenciamento de categorias de consentimento LGPD.
+ *
+ * Fornece funções para criar, validar e recuperar definições de categorias de cookies,
+ * garantindo conformidade com a LGPD e suporte a categorias customizadas.
+ */
+
 /**
  * Cria um objeto de preferências de consentimento inicial baseado na configuração de categorias do projeto.
  * @category Utils
@@ -2113,8 +3684,10 @@ declare function FloatingPreferencesButton({ position, offset, icon, tooltip, Fa
  * @returns Um objeto `ConsentPreferences` com as categorias e seus valores iniciais.
  * @remarks
  * Esta função é crucial para inicializar o estado de consentimento. Ela garante que apenas as categorias
- * definidas no `ConsentProvider` sejam incluídas no objeto de preferências, alinhando-se ao princípio
- * de minimização de dados da LGPD.
+ * definidas no `ConsentProvider` sejam incluídas no objeto de preferências (tanto categorias padrão
+ * em `enabledCategories` quanto `customCategories`), alinhando-se ao princípio de minimização de dados da LGPD.
+ *
+ * Since v0.4.0: inclui categorias de `config.customCategories` na inicialização.
  * @example
  * ```ts
  * // Gera preferências com 'analytics' e 'marketing' desabilitados por padrão
@@ -2123,6 +3696,15 @@ declare function FloatingPreferencesButton({ position, offset, icon, tooltip, Fa
  * })
  * // Result: { necessary: true, analytics: false, marketing: false }
  *
+ * // Inclui categorias customizadas
+ * const initialWithCustom = createProjectPreferences({
+ *   enabledCategories: ['analytics'],
+ *   customCategories: [
+ *     { id: 'abTesting', name: 'AB Testing', description: 'Experimentos de interface' },
+ *   ],
+ * })
+ * // Result: { necessary: true, analytics: false, abTesting: false }
+ *
  * // Gera preferências com todas as categorias habilitadas
  * const allAcceptedPrefs = createProjectPreferences(
  *   { enabledCategories: ['analytics', 'marketing'] },
@@ -2143,6 +3725,8 @@ declare function createProjectPreferences(config?: ProjectCategoriesConfig, defa
  * Garante a integridade dos dados ao carregar o estado de um cookie. Se a configuração do projeto mudou
  * (ex: uma categoria foi removida), esta função limpa as preferências obsoletas do estado,
  * evitando inconsistências.
+ *
+ * Since v0.4.0: reconhece `config.customCategories` como válidas ao validar.
  * @example
  * ```ts
  * const savedPrefs = { necessary: true, analytics: true, oldCategory: false }
@@ -2161,7 +3745,10 @@ declare function validateProjectPreferences(preferences: ConsentPreferences, con
  * @returns Um array de objetos `CategoryDefinition`.
  * @remarks
  * Útil para construir UIs de preferência customizadas, pois fornece os nomes e descrições
- * de todas as categorias que devem ser exibidas ao usuário.
+ * de todas as categorias que devem ser exibidas ao usuário, incluindo quaisquer `customCategories`
+ * definidas no `ConsentProvider`.
+ *
+ * Since v0.4.0: inclui categorias definidas em `config.customCategories`.
  * @example
  * ```ts
  * const config = { enabledCategories: ['analytics'] }
@@ -2175,4 +3762,4 @@ declare function validateProjectPreferences(preferences: ConsentPreferences, con
  */
 declare function getAllProjectCategories(config?: ProjectCategoriesConfig): CategoryDefinition[];
 
-export { COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryDefinition, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, CookieBanner, type CookieBannerProps, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, type DesignTokens, type DeveloperGuidance, FloatingPreferencesButton, type FloatingPreferencesButtonProps, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, LogLevel, PreferencesModal, type PreferencesModalProps, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createDefaultConsentTheme, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createProjectPreferences, createUserWayIntegration, defaultConsentTheme, defaultTexts, getAllProjectCategories, loadScript, openPreferencesModal, setDebugLogging, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useOpenPreferencesModal, validateProjectPreferences };
+export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, CookieBanner, type CookieBannerProps, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, FloatingPreferencesButton, type FloatingPreferencesButtonProps, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, PreferencesModal, type PreferencesModalProps, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, categorizeDiscoveredCookies, createClarityIntegration, createCorporateIntegrations, createDefaultConsentTheme, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultConsentTheme, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, openPreferencesModal, resolveTexts, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };