@react-lgpd-consent/core 0.5.1 → 0.6.2

package/dist/index.d.cts

@@ -656,6 +656,58 @@ interface ConsentCookieOptions {
     secure: boolean;
     /** Caminho do cookie. Padrão: '/' */
     path: string;
+    /**
+     * Domínio do cookie (ex.: `.example.com` para compartilhar entre subdomínios).
+     * Se não definido, o navegador usa o domínio atual.
+     * @since 0.5.2
+     */
+    domain?: string;
+}
+/**
+ * Configuração de versionamento da chave de storage utilizada pelo consentimento.
+ * @category Types
+ * @since 0.5.2
+ * @public
+ *
+ * @remarks
+ * Combine `namespace` e `version` para gerar um nome de cookie único por aplicação
+ * e ciclo de consentimento. Ao alterar a `version`, o consentimento anterior é
+ * automaticamente considerado inválido, garantindo novo fluxo de consentimento.
+ */
+interface ConsentStorageConfig {
+    /**
+     * Namespace lógico do consentimento (ex.: nome do produto ou domínio raiz).
+     * @defaultValue `'lgpd-consent'`
+     */
+    namespace?: string;
+    /**
+     * Versão do consentimento atual. Incrementar ou alterar o valor força re-consentimento.
+     * Use valores sem espaços (ex.: `'2025.10'`, `'marketing-v2'`).
+     * @defaultValue `'1'`
+     */
+    version?: string;
+    /**
+     * Domínio compartilhado do cookie (ex.: `.example.com` para múltiplos subdomínios).
+     * Se definido, sobrescreve `cookie.domain`.
+     */
+    domain?: string;
+}
+/**
+ * Payload entregue ao callback `onConsentVersionChange`.
+ * @category Types
+ * @since 0.5.2
+ * @public
+ */
+interface ConsentVersionChangeContext {
+    /** Nome da chave anterior utilizada pelo armazenamento de consentimento (cookie). */
+    previousKey: string | null;
+    /** Nova chave aplicada após a mudança de namespace/versão. */
+    nextKey: string;
+    /**
+     * Helper para gatilhar o reset imediato do estado de consentimento.
+     * Útil para cenários onde o consumidor controla estado adicional (ex.: localStorage).
+     */
+    resetConsent: () => void;
 }
 /**
  * Tipo alias para valores de espaçamento que suportam eixos x/y.
@@ -732,7 +784,8 @@ type BackdropConfig = boolean | string | {
  *
  * @category Types
  * @since 0.1.3
- * @version 0.4.1 - Expandido substancialmente com novos tokens
+ * @remarks
+ * **Histórico**: v0.4.1 - Expandido substancialmente com novos tokens
  * @public
  *
  * @example Configuração básica
@@ -1317,6 +1370,32 @@ interface ConsentProviderProps {
      * ```
      */
     guidanceConfig?: GuidanceConfig;
+    /**
+     * Configuração da chave de armazenamento (cookie/localStorage) do consentimento.
+     * Permite definir namespace, versão e domínio compartilhado.
+     * @since 0.5.2
+     */
+    storage?: ConsentStorageConfig;
+    /**
+     * Callback disparado quando a chave de armazenamento muda (ex.: bump de versão).
+     * Recebe a chave anterior, a nova chave e um helper `resetConsent`.
+     * @since 0.5.2
+     *
+     * @example
+     * ```tsx
+     * <ConsentProvider
+     *   storage={{ namespace: 'portal.gov.br', version: '2025-Q4' }}
+     *   onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
+     *     console.info('[consent] versão alterada', { previousKey, nextKey })
+     *     analytics.clearUserStorage()
+     *     resetConsent()
+     *   }}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
+     */
+    onConsentVersionChange?: (context: ConsentVersionChangeContext) => void;
     /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
@@ -1397,8 +1476,8 @@ interface ConsentContextValue {
      * @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
+     * @remarks
+     * **Breaking Change (v0.4.1)**: Parâmetro `cat` mudou de `Category` para `string` para suportar
      * categorias customizadas. O uso com strings literais continua funcionando.
      *
      * @example
@@ -1577,7 +1656,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: ConsentTexts;
 
 /**
@@ -2174,6 +2253,7 @@ declare function useCategoryStatus(categoryId: string): {
  * }
  * ```
  *
+ *
  * @component
  * @category Context
  * @since 0.1.0
@@ -2245,6 +2325,24 @@ declare function ConsentGate(props: Readonly<{
     children: React$1.ReactNode;
 }>): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * @fileoverview
+ * Utilitários para manipulação do cookie de consentimento.
+ * A estrutura de dados do cookie é um JSON simples para atender aos requisitos da LGPD,
+ * e não implementa o padrão IAB TCF, que é mais complexo.
+ * Veja `src/types/types.ts` para a definição da estrutura `ConsentCookieData`.
+ */
+
+/**
+ * Gera o nome da chave de armazenamento (cookie/localStorage) combinando namespace e versão.
+ * @param options.namespace Namespace lógico do consentimento (ex.: domínio raiz).
+ * @param options.version Versão atual do consentimento (ex.: lote de políticas).
+ */
+declare function buildConsentStorageKey(options?: {
+    namespace?: string | null;
+    version?: string | null;
+}): string;
+
 /** @module src/utils/scriptLoader */
 /**
  * @category Utils
@@ -2265,6 +2363,9 @@ declare function ConsentGate(props: Readonly<{
  * após o consentimento do usuário. Ela garante que o script só seja inserido na página
  * se o consentimento for dado e o contexto estiver disponível.
  *
+ * **React 19 StrictMode**: A função é idempotente e mantém um registro global de scripts
+ * em carregamento para evitar duplicações durante double-invoking de efeitos em desenvolvimento.
+ *
  * @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 {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.
@@ -3225,7 +3326,8 @@ type LanguageTexts = Partial<Omit<ConsentTexts, 'i18n' | 'variants' | 'contexts'
  *
  * @category Types
  * @since 0.4.1
- * @version 0.4.1 - Nova interface com suporte avançado a i18n e contextos
+ * @remarks
+ * **Histórico**: v0.4.1 - Nova interface com suporte avançado a i18n e contextos
  *
  * @example Configuração multilíngue
  * ```typescript
@@ -3606,6 +3708,88 @@ declare const logger: ConsentLogger;
  */
 declare function setDebugLogging(enabled: boolean, level?: LogLevel): void;
 
+/**
+ * @fileoverview
+ * Sistema de diagnóstico de peer dependencies e compatibilidade de versões.
+ * Detecta problemas comuns como múltiplas instâncias de React e versões de MUI fora do range suportado.
+ *
+ * @author Luciano Édipo
+ * @since 0.5.4
+ */
+/**
+ * Resultado da verificação de peer dependencies.
+ *
+ * @category Utils
+ * @since 0.5.4
+ */
+interface PeerDepsCheckResult {
+    /** Se todas as verificações passaram sem problemas críticos */
+    ok: boolean;
+    /** Lista de avisos detectados */
+    warnings: string[];
+    /** Lista de erros críticos detectados */
+    errors: string[];
+}
+/**
+ * Verifica compatibilidade de peer dependencies (React e MUI).
+ *
+ * @category Utils
+ * @since 0.5.4
+ *
+ * @remarks
+ * Esta função executa verificações em ambiente de desenvolvimento para detectar:
+ * - Múltiplas instâncias de React (causa "Invalid hook call")
+ * - Versões de React fora do range suportado (18-19)
+ * - Versões de MUI fora do range suportado (5-7)
+ *
+ * As mensagens incluem:
+ * - Descrição clara do problema
+ * - Causa raiz provável
+ * - Passos objetivos para resolver
+ * - Links para documentação
+ *
+ * @param options - Opções de configuração
+ * @param options.skipInProduction - Se true, pula verificação em produção (padrão: true)
+ * @param options.logWarnings - Se true, loga avisos no console (padrão: true)
+ *
+ * @returns Resultado da verificação com lista de avisos e erros
+ *
+ * @example
+ * ```typescript
+ * import { checkPeerDeps } from '@react-lgpd-consent/core'
+ *
+ * // Verificar compatibilidade em desenvolvimento
+ * const result = checkPeerDeps()
+ * if (!result.ok) {
+ *   console.log('Problemas detectados:', result.errors)
+ * }
+ * ```
+ */
+declare function checkPeerDeps(options?: {
+    skipInProduction?: boolean;
+    logWarnings?: boolean;
+}): PeerDepsCheckResult;
+/**
+ * Executa verificação de peer dependencies e loga resultados automaticamente.
+ * Versão conveniente de `checkPeerDeps` que sempre loga no console.
+ *
+ * @category Utils
+ * @since 0.5.4
+ *
+ * @remarks
+ * Esta função é chamada automaticamente pelo ConsentProvider em modo development.
+ * Use `checkPeerDeps()` se precisar do resultado programaticamente sem logging.
+ *
+ * @example
+ * ```typescript
+ * import { runPeerDepsCheck } from '@react-lgpd-consent/core'
+ *
+ * // Executar verificação manual (já é automática no Provider)
+ * runPeerDepsCheck()
+ * ```
+ */
+declare function runPeerDepsCheck(): void;
+
 interface CookieCatalogOverrides {
     byCategory?: Record<string, CookieDescriptor[]>;
     byIntegration?: Record<string, CookieDescriptor[]>;
@@ -3666,6 +3850,12 @@ declare function getCookiesInfoForCategory(categoryId: Category, usedIntegration
  * ```
  */
 declare function createProjectPreferences(config?: ProjectCategoriesConfig, defaultValue?: boolean): ConsentPreferences;
+/**
+ * Garante que a categoria `necessary` permaneça ativa em qualquer estrutura de preferências.
+ * @category Utils
+ * @since 0.5.2
+ */
+declare function ensureNecessaryAlwaysOn(preferences: ConsentPreferences): ConsentPreferences;
 /**
  * Valida um objeto de preferências de consentimento, removendo categorias que não estão permitidas pela configuração do projeto.
  * @category Utils
@@ -3842,4 +4032,4 @@ declare function useDataLayerEvents(): {
     pushUpdated: typeof pushConsentUpdatedEvent;
 };
 
-export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, type ConsentEvent, type ConsentEventOrigin, ConsentGate, type ConsentInitializedEvent, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, type ConsentUpdatedEvent, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, DesignProvider, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, categorizeDiscoveredCookies, createClarityIntegration, createCorporateIntegrations, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, logger, openPreferencesModal, pushConsentInitializedEvent, pushConsentUpdatedEvent, resolveTexts, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDataLayerEvents, useDesignTokens, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };
+export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, type ConsentEvent, type ConsentEventOrigin, ConsentGate, type ConsentInitializedEvent, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentStorageConfig, type ConsentTexts, type ConsentUpdatedEvent, type ConsentVersionChangeContext, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, DesignProvider, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, type PeerDepsCheckResult, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, buildConsentStorageKey, categorizeDiscoveredCookies, checkPeerDeps, createClarityIntegration, createCorporateIntegrations, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, ensureNecessaryAlwaysOn, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, logger, openPreferencesModal, pushConsentInitializedEvent, pushConsentUpdatedEvent, resolveTexts, runPeerDepsCheck, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDataLayerEvents, useDesignTokens, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };

package/dist/index.d.ts

@@ -656,6 +656,58 @@ interface ConsentCookieOptions {
     secure: boolean;
     /** Caminho do cookie. Padrão: '/' */
     path: string;
+    /**
+     * Domínio do cookie (ex.: `.example.com` para compartilhar entre subdomínios).
+     * Se não definido, o navegador usa o domínio atual.
+     * @since 0.5.2
+     */
+    domain?: string;
+}
+/**
+ * Configuração de versionamento da chave de storage utilizada pelo consentimento.
+ * @category Types
+ * @since 0.5.2
+ * @public
+ *
+ * @remarks
+ * Combine `namespace` e `version` para gerar um nome de cookie único por aplicação
+ * e ciclo de consentimento. Ao alterar a `version`, o consentimento anterior é
+ * automaticamente considerado inválido, garantindo novo fluxo de consentimento.
+ */
+interface ConsentStorageConfig {
+    /**
+     * Namespace lógico do consentimento (ex.: nome do produto ou domínio raiz).
+     * @defaultValue `'lgpd-consent'`
+     */
+    namespace?: string;
+    /**
+     * Versão do consentimento atual. Incrementar ou alterar o valor força re-consentimento.
+     * Use valores sem espaços (ex.: `'2025.10'`, `'marketing-v2'`).
+     * @defaultValue `'1'`
+     */
+    version?: string;
+    /**
+     * Domínio compartilhado do cookie (ex.: `.example.com` para múltiplos subdomínios).
+     * Se definido, sobrescreve `cookie.domain`.
+     */
+    domain?: string;
+}
+/**
+ * Payload entregue ao callback `onConsentVersionChange`.
+ * @category Types
+ * @since 0.5.2
+ * @public
+ */
+interface ConsentVersionChangeContext {
+    /** Nome da chave anterior utilizada pelo armazenamento de consentimento (cookie). */
+    previousKey: string | null;
+    /** Nova chave aplicada após a mudança de namespace/versão. */
+    nextKey: string;
+    /**
+     * Helper para gatilhar o reset imediato do estado de consentimento.
+     * Útil para cenários onde o consumidor controla estado adicional (ex.: localStorage).
+     */
+    resetConsent: () => void;
 }
 /**
  * Tipo alias para valores de espaçamento que suportam eixos x/y.
@@ -732,7 +784,8 @@ type BackdropConfig = boolean | string | {
  *
  * @category Types
  * @since 0.1.3
- * @version 0.4.1 - Expandido substancialmente com novos tokens
+ * @remarks
+ * **Histórico**: v0.4.1 - Expandido substancialmente com novos tokens
  * @public
  *
  * @example Configuração básica
@@ -1317,6 +1370,32 @@ interface ConsentProviderProps {
      * ```
      */
     guidanceConfig?: GuidanceConfig;
+    /**
+     * Configuração da chave de armazenamento (cookie/localStorage) do consentimento.
+     * Permite definir namespace, versão e domínio compartilhado.
+     * @since 0.5.2
+     */
+    storage?: ConsentStorageConfig;
+    /**
+     * Callback disparado quando a chave de armazenamento muda (ex.: bump de versão).
+     * Recebe a chave anterior, a nova chave e um helper `resetConsent`.
+     * @since 0.5.2
+     *
+     * @example
+     * ```tsx
+     * <ConsentProvider
+     *   storage={{ namespace: 'portal.gov.br', version: '2025-Q4' }}
+     *   onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
+     *     console.info('[consent] versão alterada', { previousKey, nextKey })
+     *     analytics.clearUserStorage()
+     *     resetConsent()
+     *   }}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
+     */
+    onConsentVersionChange?: (context: ConsentVersionChangeContext) => void;
     /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
@@ -1397,8 +1476,8 @@ interface ConsentContextValue {
      * @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
+     * @remarks
+     * **Breaking Change (v0.4.1)**: Parâmetro `cat` mudou de `Category` para `string` para suportar
      * categorias customizadas. O uso com strings literais continua funcionando.
      *
      * @example
@@ -1577,7 +1656,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: ConsentTexts;
 
 /**
@@ -2174,6 +2253,7 @@ declare function useCategoryStatus(categoryId: string): {
  * }
  * ```
  *
+ *
  * @component
  * @category Context
  * @since 0.1.0
@@ -2245,6 +2325,24 @@ declare function ConsentGate(props: Readonly<{
     children: React$1.ReactNode;
 }>): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * @fileoverview
+ * Utilitários para manipulação do cookie de consentimento.
+ * A estrutura de dados do cookie é um JSON simples para atender aos requisitos da LGPD,
+ * e não implementa o padrão IAB TCF, que é mais complexo.
+ * Veja `src/types/types.ts` para a definição da estrutura `ConsentCookieData`.
+ */
+
+/**
+ * Gera o nome da chave de armazenamento (cookie/localStorage) combinando namespace e versão.
+ * @param options.namespace Namespace lógico do consentimento (ex.: domínio raiz).
+ * @param options.version Versão atual do consentimento (ex.: lote de políticas).
+ */
+declare function buildConsentStorageKey(options?: {
+    namespace?: string | null;
+    version?: string | null;
+}): string;
+
 /** @module src/utils/scriptLoader */
 /**
  * @category Utils
@@ -2265,6 +2363,9 @@ declare function ConsentGate(props: Readonly<{
  * após o consentimento do usuário. Ela garante que o script só seja inserido na página
  * se o consentimento for dado e o contexto estiver disponível.
  *
+ * **React 19 StrictMode**: A função é idempotente e mantém um registro global de scripts
+ * em carregamento para evitar duplicações durante double-invoking de efeitos em desenvolvimento.
+ *
  * @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 {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.
@@ -3225,7 +3326,8 @@ type LanguageTexts = Partial<Omit<ConsentTexts, 'i18n' | 'variants' | 'contexts'
  *
  * @category Types
  * @since 0.4.1
- * @version 0.4.1 - Nova interface com suporte avançado a i18n e contextos
+ * @remarks
+ * **Histórico**: v0.4.1 - Nova interface com suporte avançado a i18n e contextos
  *
  * @example Configuração multilíngue
  * ```typescript
@@ -3606,6 +3708,88 @@ declare const logger: ConsentLogger;
  */
 declare function setDebugLogging(enabled: boolean, level?: LogLevel): void;
 
+/**
+ * @fileoverview
+ * Sistema de diagnóstico de peer dependencies e compatibilidade de versões.
+ * Detecta problemas comuns como múltiplas instâncias de React e versões de MUI fora do range suportado.
+ *
+ * @author Luciano Édipo
+ * @since 0.5.4
+ */
+/**
+ * Resultado da verificação de peer dependencies.
+ *
+ * @category Utils
+ * @since 0.5.4
+ */
+interface PeerDepsCheckResult {
+    /** Se todas as verificações passaram sem problemas críticos */
+    ok: boolean;
+    /** Lista de avisos detectados */
+    warnings: string[];
+    /** Lista de erros críticos detectados */
+    errors: string[];
+}
+/**
+ * Verifica compatibilidade de peer dependencies (React e MUI).
+ *
+ * @category Utils
+ * @since 0.5.4
+ *
+ * @remarks
+ * Esta função executa verificações em ambiente de desenvolvimento para detectar:
+ * - Múltiplas instâncias de React (causa "Invalid hook call")
+ * - Versões de React fora do range suportado (18-19)
+ * - Versões de MUI fora do range suportado (5-7)
+ *
+ * As mensagens incluem:
+ * - Descrição clara do problema
+ * - Causa raiz provável
+ * - Passos objetivos para resolver
+ * - Links para documentação
+ *
+ * @param options - Opções de configuração
+ * @param options.skipInProduction - Se true, pula verificação em produção (padrão: true)
+ * @param options.logWarnings - Se true, loga avisos no console (padrão: true)
+ *
+ * @returns Resultado da verificação com lista de avisos e erros
+ *
+ * @example
+ * ```typescript
+ * import { checkPeerDeps } from '@react-lgpd-consent/core'
+ *
+ * // Verificar compatibilidade em desenvolvimento
+ * const result = checkPeerDeps()
+ * if (!result.ok) {
+ *   console.log('Problemas detectados:', result.errors)
+ * }
+ * ```
+ */
+declare function checkPeerDeps(options?: {
+    skipInProduction?: boolean;
+    logWarnings?: boolean;
+}): PeerDepsCheckResult;
+/**
+ * Executa verificação de peer dependencies e loga resultados automaticamente.
+ * Versão conveniente de `checkPeerDeps` que sempre loga no console.
+ *
+ * @category Utils
+ * @since 0.5.4
+ *
+ * @remarks
+ * Esta função é chamada automaticamente pelo ConsentProvider em modo development.
+ * Use `checkPeerDeps()` se precisar do resultado programaticamente sem logging.
+ *
+ * @example
+ * ```typescript
+ * import { runPeerDepsCheck } from '@react-lgpd-consent/core'
+ *
+ * // Executar verificação manual (já é automática no Provider)
+ * runPeerDepsCheck()
+ * ```
+ */
+declare function runPeerDepsCheck(): void;
+
 interface CookieCatalogOverrides {
     byCategory?: Record<string, CookieDescriptor[]>;
     byIntegration?: Record<string, CookieDescriptor[]>;
@@ -3666,6 +3850,12 @@ declare function getCookiesInfoForCategory(categoryId: Category, usedIntegration
  * ```
  */
 declare function createProjectPreferences(config?: ProjectCategoriesConfig, defaultValue?: boolean): ConsentPreferences;
+/**
+ * Garante que a categoria `necessary` permaneça ativa em qualquer estrutura de preferências.
+ * @category Utils
+ * @since 0.5.2
+ */
+declare function ensureNecessaryAlwaysOn(preferences: ConsentPreferences): ConsentPreferences;
 /**
  * Valida um objeto de preferências de consentimento, removendo categorias que não estão permitidas pela configuração do projeto.
  * @category Utils
@@ -3842,4 +4032,4 @@ declare function useDataLayerEvents(): {
     pushUpdated: typeof pushConsentUpdatedEvent;
 };
 
-export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, type ConsentEvent, type ConsentEventOrigin, ConsentGate, type ConsentInitializedEvent, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, type ConsentUpdatedEvent, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, DesignProvider, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, categorizeDiscoveredCookies, createClarityIntegration, createCorporateIntegrations, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, logger, openPreferencesModal, pushConsentInitializedEvent, pushConsentUpdatedEvent, resolveTexts, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDataLayerEvents, useDesignTokens, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };
+export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, type ConsentEvent, type ConsentEventOrigin, ConsentGate, type ConsentInitializedEvent, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentStorageConfig, type ConsentTexts, type ConsentUpdatedEvent, type ConsentVersionChangeContext, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, DesignProvider, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, type PeerDepsCheckResult, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, buildConsentStorageKey, categorizeDiscoveredCookies, checkPeerDeps, createClarityIntegration, createCorporateIntegrations, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, ensureNecessaryAlwaysOn, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, logger, openPreferencesModal, pushConsentInitializedEvent, pushConsentUpdatedEvent, resolveTexts, runPeerDepsCheck, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDataLayerEvents, useDesignTokens, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };