@react-lgpd-consent/core 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,4 +1,23 @@
 # Changelog - @react-lgpd-consent/core
 
+## 0.6.1
+
+### Patch Changes
+
+- [#105](https://github.com/lucianoedipo/react-lgpd-consent/pull/105) [`1deb3bb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/1deb3bb56853165f7ec231e73d7b1d271e51b8f1) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - chore: sincronizar pnpm-lock.yaml com versões bumpeadas
+
+## 0.6.0
+
+### Minor Changes
+
+- [#103](https://github.com/lucianoedipo/react-lgpd-consent/pull/103) [`4c9ebf2`](https://github.com/lucianoedipo/react-lgpd-consent/commit/4c9ebf231ff58168294f2fde405298b7087016ca) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - feat: adicionar diagnósticos de peer dependencies e sistema de troubleshooting
+  - ✨ Novo sistema de diagnóstico automático para peer deps
+  - 🔍 Detecta múltiplas instâncias de React (causa "Invalid hook call")
+  - 📋 Verifica versões de React (18-19) e MUI (5-7)
+  - 📖 Nova página TROUBLESHOOTING.md com soluções detalhadas
+  - 🔧 Mensagens acionáveis no console em modo desenvolvimento
+  - 🚀 Configuração de Turborepo para builds otimizados
+  - 📦 Configuração de Changesets para versionamento automatizado
+
 As notas de versão completas são mantidas no arquivo `CHANGELOG.md` da raiz do repositório.  
 Este pacote segue a numeração conjunta da biblioteca `react-lgpd-consent`.

package/dist/index.cjs

@@ -55,6 +55,15 @@ function createProjectPreferences(config, defaultValue = false) {
   });
   return preferences;
 }
+function ensureNecessaryAlwaysOn(preferences) {
+  if (preferences.necessary === true) {
+    return { ...preferences, necessary: true };
+  }
+  return {
+    ...preferences,
+    necessary: true
+  };
+}
 function validateProjectPreferences(preferences, config) {
   const validPreferences = {
     necessary: true
@@ -322,12 +331,22 @@ function setDebugLogging(enabled, level = 2 /* INFO */) {
 }
 
 // src/utils/cookieUtils.ts
+var DEFAULT_STORAGE_NAMESPACE = "lgpd-consent";
+var DEFAULT_STORAGE_VERSION = "1";
+function buildConsentStorageKey(options) {
+  const namespaceRaw = options?.namespace?.trim() || DEFAULT_STORAGE_NAMESPACE;
+  const versionRaw = options?.version?.trim() || DEFAULT_STORAGE_VERSION;
+  const sanitizedNamespace = namespaceRaw.replace(/[^a-z0-9._-]+/gi, "-").toLowerCase();
+  const sanitizedVersion = versionRaw.replace(/[^a-z0-9._-]+/gi, "-").toLowerCase();
+  return `${sanitizedNamespace}__v${sanitizedVersion}`;
+}
 var DEFAULT_COOKIE_OPTS = {
   name: "cookieConsent",
   maxAgeDays: 365,
   sameSite: "Lax",
   secure: typeof window !== "undefined" ? window.location.protocol === "https:" : false,
-  path: "/"
+  path: "/",
+  domain: void 0
 };
 var COOKIE_SCHEMA_VERSION = "1.0";
 function readConsentCookie(name = DEFAULT_COOKIE_OPTS.name) {
@@ -381,10 +400,11 @@ function writeConsentCookie(state, config, opts, source = "banner") {
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const o = { ...DEFAULT_COOKIE_OPTS, ...opts };
+  const preferences = ensureNecessaryAlwaysOn(state.preferences);
   const cookieData = {
     version: COOKIE_SCHEMA_VERSION,
     consented: state.consented,
-    preferences: state.preferences,
+    preferences,
     consentDate: state.consentDate || now,
     lastUpdate: now,
     source,
@@ -395,7 +415,8 @@ function writeConsentCookie(state, config, opts, source = "banner") {
     expires: o.maxAgeDays,
     sameSite: o.sameSite,
     secure: o.secure,
-    path: o.path
+    path: o.path,
+    domain: o.domain
   });
   logger.info("Consent cookie saved", {
     consented: cookieData.consented,
@@ -410,12 +431,12 @@ function removeConsentCookie(opts) {
   }
   const o = { ...DEFAULT_COOKIE_OPTS, ...opts };
   logger.cookieOperation("delete", o.name);
-  Cookies__default.default.remove(o.name, { path: o.path });
+  Cookies__default.default.remove(o.name, { path: o.path, domain: o.domain });
   logger.info("Consent cookie removed");
 }
 
 // src/utils/dataLayerEvents.ts
-var LIBRARY_VERSION = "0.5.0";
+var LIBRARY_VERSION = "0.6.1";
 function ensureDataLayer() {
   if (typeof window === "undefined") return;
   if (!window.dataLayer) {
@@ -1051,6 +1072,207 @@ var GUIDANCE_PRESETS = {
   }
 };
 
+// src/utils/peerDepsCheck.ts
+function detectMultipleReactInstances() {
+  if (typeof window === "undefined") return false;
+  try {
+    const reactSymbols = Object.getOwnPropertySymbols(window).map((sym) => String(sym)).filter((name) => name.includes("react"));
+    if (reactSymbols.length > 1) {
+      return true;
+    }
+    const ReactModule = window.React;
+    if (ReactModule && Array.isArray(ReactModule)) {
+      return true;
+    }
+    const hasMultipleVersions = window.__REACT_DEVTOOLS_GLOBAL_HOOK__?.renderers?.size > 1;
+    return hasMultipleVersions || false;
+  } catch {
+    return false;
+  }
+}
+function getPackageVersion(packageName) {
+  if (typeof window === "undefined") return null;
+  try {
+    const pkg = window[packageName];
+    if (pkg?.version) return pkg.version;
+    const React6 = window.React;
+    if (packageName === "react" && React6?.version) {
+      return React6.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function isVersionInRange(version, minMajor, maxMajor) {
+  const major = parseInt(version.split(".")[0], 10);
+  return major >= minMajor && major <= maxMajor;
+}
+function checkPeerDeps(options = {}) {
+  const { skipInProduction = true, logWarnings = true } = options;
+  const result = {
+    ok: true,
+    warnings: [],
+    errors: []
+  };
+  const isProduction = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  if (skipInProduction && isProduction) {
+    return result;
+  }
+  if (typeof window === "undefined") {
+    return result;
+  }
+  if (detectMultipleReactInstances()) {
+    result.ok = false;
+    const errorMsg = `
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551 \u26A0\uFE0F  ERRO: M\xFAltiplas inst\xE2ncias de React detectadas                           \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+
+\u{1F534} Problema:
+   Seu projeto est\xE1 carregando mais de uma c\xF3pia do React, causando o erro:
+   "Invalid hook call. Hooks can only be called inside of the body of a 
+    function component."
+
+\u{1F50D} Causa prov\xE1vel:
+   \u2022 pnpm/Yarn PnP sem hoisting adequado de peer dependencies
+   \u2022 node_modules com React duplicado (npm/yarn cl\xE1ssico)
+   \u2022 Webpack/Vite com m\xFAltiplas resolu\xE7\xF5es do mesmo pacote
+
+\u2705 Solu\xE7\xF5es:
+
+   \u{1F4E6} PNPM (RECOMENDADO):
+      Adicione ao package.json raiz:
+      {
+        "pnpm": {
+          "overrides": {
+            "react": "$react",
+            "react-dom": "$react-dom"
+          }
+        }
+      }
+      Execute: pnpm install
+
+   \u{1F4E6} NPM/Yarn:
+      Adicione ao package.json raiz:
+      {
+        "overrides": {
+          "react": "^18.2.0 || ^19.0.0",
+          "react-dom": "^18.2.0 || ^19.0.0"
+        }
+      }
+      Execute: npm install (ou yarn install)
+      
+   \u{1F527} Webpack:
+      Adicione ao webpack.config.js:
+      module.exports = {
+        resolve: {
+          alias: {
+            react: path.resolve('./node_modules/react'),
+            'react-dom': path.resolve('./node_modules/react-dom'),
+          }
+        }
+      }
+
+   \u26A1 Vite:
+      Adicione ao vite.config.js:
+      export default {
+        resolve: {
+          dedupe: ['react', 'react-dom']
+        }
+      }
+
+\u{1F4DA} Documenta\xE7\xE3o:
+   https://github.com/lucianoedipo/react-lgpd-consent/blob/main/TROUBLESHOOTING.md#multiple-react-instances
+
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`;
+    result.errors.push(errorMsg);
+    if (logWarnings) {
+      console.error(errorMsg);
+    }
+  }
+  const reactVersion = getPackageVersion("react");
+  if (reactVersion) {
+    if (!isVersionInRange(reactVersion, 18, 19)) {
+      result.ok = false;
+      const errorMsg = `
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551 \u26A0\uFE0F  AVISO: Vers\xE3o do React n\xE3o suportada                                     \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+
+\u{1F4E6} Vers\xE3o detectada: React ${reactVersion}
+\u2705 Vers\xF5es suportadas: React 18.x ou 19.x
+
+\u{1F50D} O react-lgpd-consent requer React 18.2.0+ ou React 19.x
+
+\u2705 Solu\xE7\xE3o:
+   Atualize o React para uma vers\xE3o suportada:
+   
+   npm install react@^18.2.0 react-dom@^18.2.0
+   
+   ou
+   
+   npm install react@^19.0.0 react-dom@^19.0.0
+
+\u{1F4DA} Documenta\xE7\xE3o:
+   https://github.com/lucianoedipo/react-lgpd-consent/blob/main/TROUBLESHOOTING.md#react-version
+
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`;
+      result.errors.push(errorMsg);
+      if (logWarnings) {
+        console.error(errorMsg);
+      }
+    }
+  }
+  const muiVersion = window["@mui/material"]?.version;
+  if (muiVersion) {
+    if (!isVersionInRange(muiVersion, 5, 7)) {
+      result.warnings.push(
+        `MUI vers\xE3o ${muiVersion} detectada. Vers\xF5es suportadas: 5.15.0+, 6.x ou 7.x. Alguns componentes podem n\xE3o funcionar corretamente.`
+      );
+      if (logWarnings) {
+        logger.warn(
+          `
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551 \u26A0\uFE0F  AVISO: Vers\xE3o do Material-UI fora do range recomendado                   \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+
+\u{1F4E6} Vers\xE3o detectada: @mui/material ${muiVersion}
+\u2705 Vers\xF5es suportadas: 5.15.0+, 6.x, 7.x
+
+\u{1F50D} Componentes de UI (@react-lgpd-consent/mui) podem apresentar problemas.
+
+\u2705 Solu\xE7\xE3o:
+   Atualize o MUI para uma vers\xE3o suportada:
+   
+   npm install @mui/material@^7.0.0 @emotion/react @emotion/styled
+   
+   ou mantenha 5.15.0+:
+   
+   npm install @mui/material@^5.15.0 @emotion/react @emotion/styled
+
+\u{1F4DA} Documenta\xE7\xE3o:
+   https://github.com/lucianoedipo/react-lgpd-consent/blob/main/TROUBLESHOOTING.md#mui-version
+
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`
+        );
+      }
+    }
+  }
+  return result;
+}
+function runPeerDepsCheck() {
+  const result = checkPeerDeps({ logWarnings: true });
+  if (result.ok && result.warnings.length === 0) {
+    logger.debug("\u2705 Peer dependencies check: OK");
+  } else if (result.warnings.length > 0) {
+    logger.warn("\u26A0\uFE0F  Peer dependencies check: avisos detectados");
+  }
+}
+
 // src/utils/validation.ts
 var isDev = () => typeof process !== "undefined" && process.env.NODE_ENV !== "production";
 function validateConsentProviderProps(props) {
@@ -1323,10 +1545,11 @@ function useDesignTokens() {
 }
 function createFullConsentState(consented, preferences, source, projectConfig, isModalOpen = false, existingState) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  const enforcedPreferences = ensureNecessaryAlwaysOn(preferences);
   return {
     version: "1.0",
     consented,
-    preferences,
+    preferences: enforcedPreferences,
     consentDate: existingState?.consentDate || now,
     lastUpdate: now,
     source,
@@ -1390,7 +1613,11 @@ function reducer(state, action) {
       });
       return newState;
     }
-    case "SET_CATEGORY":
+    case "SET_CATEGORY": {
+      if (action.category === "necessary") {
+        logger.warn("Attempt to toggle necessary category ignored for compliance reasons.");
+        return state;
+      }
       logger.debug("Category preference changed", {
         category: action.category,
         value: action.value
@@ -1403,9 +1630,12 @@ function reducer(state, action) {
         },
         lastUpdate: (/* @__PURE__ */ new Date()).toISOString()
       };
-    case "SET_PREFERENCES":
-      logger.info("Preferences saved", { preferences: action.preferences });
-      return createFullConsentState(true, action.preferences, "modal", action.config, false, state);
+    }
+    case "SET_PREFERENCES": {
+      const sanitized = ensureNecessaryAlwaysOn(action.preferences);
+      logger.info("Preferences saved", { preferences: sanitized });
+      return createFullConsentState(true, sanitized, "modal", action.config, false, state);
+    }
     case "OPEN_MODAL":
       return { ...state, isModalOpen: true };
     case "CLOSE_MODAL":
@@ -1456,16 +1686,25 @@ function ConsentProvider({
   onConsentGiven,
   onPreferencesSaved,
   cookie: cookieOpts,
+  storage,
+  onConsentVersionChange,
   disableDeveloperGuidance,
   guidanceConfig,
   children,
   disableDiscoveryLog
 }) {
   const texts = React4__namespace.useMemo(() => ({ ...DEFAULT_TEXTS, ...textsProp ?? {} }), [textsProp]);
-  const cookie = React4__namespace.useMemo(
-    () => ({ ...DEFAULT_COOKIE_OPTS, ...cookieOpts ?? {} }),
-    [cookieOpts]
-  );
+  const cookie = React4__namespace.useMemo(() => {
+    const base = { ...DEFAULT_COOKIE_OPTS, ...cookieOpts ?? {} };
+    base.name = cookieOpts?.name ?? buildConsentStorageKey({
+      namespace: storage?.namespace,
+      version: storage?.version
+    });
+    if (!base.domain && storage?.domain) {
+      base.domain = storage.domain;
+    }
+    return base;
+  }, [cookieOpts, storage?.domain, storage?.namespace, storage?.version]);
   const finalCategoriesConfig = React4__namespace.useMemo(() => {
     const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
     if (!categories) return DEFAULT_PROJECT_CATEGORIES;
@@ -1483,6 +1722,12 @@ function ConsentProvider({
   }, [categories]);
   const didWarnAboutMissingUI = React4__namespace.useRef(false);
   useDeveloperGuidance(finalCategoriesConfig, disableDeveloperGuidance, guidanceConfig);
+  React4__namespace.useEffect(() => {
+    const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+    if (!isProd && !disableDeveloperGuidance) {
+      runPeerDepsCheck();
+    }
+  }, [disableDeveloperGuidance]);
   React4__namespace.useEffect(() => {
     const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
     if (!isProd && PreferencesModalComponent) {
@@ -1502,6 +1747,8 @@ function ConsentProvider({
     );
   }, [initialState, finalCategoriesConfig]);
   const [state, dispatch] = React4__namespace.useReducer(reducer, boot);
+  const previousCookieRef = React4__namespace.useRef(cookie);
+  const skipCookiePersistRef = React4__namespace.useRef(false);
   const [isHydrated, setIsHydrated] = React4__namespace.useState(false);
   const previousPreferencesRef = React4__namespace.useRef(state.preferences);
   React4__namespace.useEffect(() => {
@@ -1517,6 +1764,35 @@ function ConsentProvider({
     }
     setIsHydrated(true);
   }, [cookie.name, initialState, finalCategoriesConfig]);
+  React4__namespace.useEffect(() => {
+    const previousCookie = previousCookieRef.current;
+    const isSameCookie = previousCookie.name === cookie.name && previousCookie.domain === cookie.domain && previousCookie.path === cookie.path;
+    if (isSameCookie) {
+      previousCookieRef.current = cookie;
+      return;
+    }
+    skipCookiePersistRef.current = true;
+    removeConsentCookie(previousCookie);
+    const reset = () => {
+      removeConsentCookie(cookie);
+      dispatch({ type: "RESET", config: finalCategoriesConfig });
+    };
+    reset();
+    if (onConsentVersionChange) {
+      onConsentVersionChange({
+        previousKey: previousCookie.name,
+        nextKey: cookie.name,
+        resetConsent: reset
+      });
+    }
+    previousCookieRef.current = cookie;
+  }, [cookie, finalCategoriesConfig, onConsentVersionChange, dispatch]);
+  function resetSkipCookiePersistOnConsentRevoked() {
+    if (skipCookiePersistRef.current && !state.consented) {
+      skipCookiePersistRef.current = false;
+    }
+  }
+  React4__namespace.useEffect(resetSkipCookiePersistOnConsentRevoked, [state.consented]);
   React4__namespace.useEffect(() => {
     if (isHydrated) {
       pushConsentInitializedEvent(state.preferences);
@@ -1526,7 +1802,9 @@ function ConsentProvider({
     }
   }, [isHydrated]);
   React4__namespace.useEffect(() => {
-    if (state.consented) writeConsentCookie(state, finalCategoriesConfig, cookie);
+    if (!state.consented) return;
+    if (skipCookiePersistRef.current) return;
+    writeConsentCookie(state, finalCategoriesConfig, cookie);
   }, [state, cookie, finalCategoriesConfig]);
   const prevConsented = React4__namespace.useRef(state.consented);
   React4__namespace.useEffect(() => {
@@ -1554,15 +1832,22 @@ function ConsentProvider({
   const api = React4__namespace.useMemo(() => {
     const acceptAll = () => dispatch({ type: "ACCEPT_ALL", config: finalCategoriesConfig });
     const rejectAll = () => dispatch({ type: "REJECT_ALL", config: finalCategoriesConfig });
-    const setPreference = (category, value) => dispatch({ type: "SET_CATEGORY", category, value });
+    const setPreference = (category, value) => {
+      if (category === "necessary") {
+        logger.warn("setPreference: attempt to toggle necessary category ignored.");
+        return;
+      }
+      dispatch({ type: "SET_CATEGORY", category, value });
+    };
     const setPreferences = (preferences) => {
+      const sanitized = ensureNecessaryAlwaysOn(preferences);
       dispatch({
         type: "SET_PREFERENCES",
-        preferences,
+        preferences: sanitized,
         config: finalCategoriesConfig
       });
       if (onPreferencesSaved) {
-        setTimeout(() => onPreferencesSaved(preferences), 150);
+        setTimeout(() => onPreferencesSaved(sanitized), 150);
       }
     };
     const openPreferences = () => dispatch({ type: "OPEN_MODAL" });
@@ -2577,7 +2862,9 @@ exports.TEXT_TEMPLATES = TEXT_TEMPLATES;
 exports.analyzeDeveloperConfiguration = analyzeDeveloperConfiguration;
 exports.analyzeIntegrationCategories = analyzeIntegrationCategories;
 exports.autoConfigureCategories = autoConfigureCategories;
+exports.buildConsentStorageKey = buildConsentStorageKey;
 exports.categorizeDiscoveredCookies = categorizeDiscoveredCookies;
+exports.checkPeerDeps = checkPeerDeps;
 exports.createClarityIntegration = createClarityIntegration;
 exports.createCorporateIntegrations = createCorporateIntegrations;
 exports.createECommerceIntegrations = createECommerceIntegrations;
@@ -2594,6 +2881,7 @@ exports.createZendeskChatIntegration = createZendeskChatIntegration;
 exports.defaultTexts = defaultTexts;
 exports.detectConsentCookieName = detectConsentCookieName;
 exports.discoverRuntimeCookies = discoverRuntimeCookies;
+exports.ensureNecessaryAlwaysOn = ensureNecessaryAlwaysOn;
 exports.extractCategoriesFromIntegrations = extractCategoriesFromIntegrations;
 exports.getAllProjectCategories = getAllProjectCategories;
 exports.getCookiesInfoForCategory = getCookiesInfoForCategory;
@@ -2604,6 +2892,7 @@ exports.openPreferencesModal = openPreferencesModal;
 exports.pushConsentInitializedEvent = pushConsentInitializedEvent;
 exports.pushConsentUpdatedEvent = pushConsentUpdatedEvent;
 exports.resolveTexts = resolveTexts;
+exports.runPeerDepsCheck = runPeerDepsCheck;
 exports.setCookieCatalogOverrides = setCookieCatalogOverrides;
 exports.setCookieCategoryOverrides = setCookieCategoryOverrides;
 exports.setDebugLogging = setDebugLogging;