@c15t/react 2.0.0-rc.4 → 2.0.0-rc.5

package/docs/concepts/cookie-management.md

@@ -0,0 +1,122 @@
+---
+title: Cookie Management
+description: How c15t manages cookies through script, iframe, and network gating
+lastModified: 2026-02-10
+---
+Cookie management is the most commonly misunderstood part of consent. A critical distinction: **c15t does not manage all cookies on your site.** It controls what scripts, iframes, and network requests are allowed to load - and those third-party resources are what set most cookies.
+
+Understanding this distinction is key to building a compliant consent flow: c15t gates the sources of cookies, not the cookies themselves.
+
+## What Actually Sets Cookies
+
+There are four sources of cookies on a typical website:
+
+**1. c15t itself**
+c15t stores the user's consent state in a `c15t` cookie (and mirrors it to localStorage). This cookie records which categories the user consented to, when they consented, and their subject ID. This is a strictly necessary cookie - it exists so the site remembers the user's consent choice.
+
+**2. Third-party scripts**
+When you load a tracking script (Google Analytics, Meta Pixel, etc.), that script sets its own cookies. Google Analytics creates `_ga` and `_gid` cookies. Meta creates `_fbp` and `_fbc`. These cookies are set by the script's code running in the browser - c15t prevents them by not loading the script until the user consents.
+
+**3. Embedded iframes**
+YouTube embeds, social media widgets, and other iframes can set cookies via their embedded content. c15t's iframe blocker replaces iframes with placeholders until consent is granted, preventing these cookies from being set.
+
+**4. Network requests**
+Server responses can include `Set-Cookie` headers. If your page makes requests to third-party APIs or CDNs, those responses may set cookies. c15t's network blocker can intercept `fetch` and `XMLHttpRequest` calls to prevent these requests from happening without consent.
+
+> ℹ️ **Info:**
+> Don't list these cookies in your banner. The cookie names above (\_ga, \_gid, \_fbp, \_fbc) are implementation details — they matter for developers understanding how tracking works, but they should not be exposed to end users in your consent UI. Users don't know what \_ga means, and listing it doesn't help them make an informed choice. Instead, use purpose-based consent categories like "measurement" or "marketing" that communicate why data is collected, not how it is stored.
+
+## Why Revoking Consent Requires a Page Reload
+
+When a user revokes consent for a category (e.g., turns off "measurement" after previously granting it), c15t reloads the page by default. This is not a limitation - it's the only reliable approach.
+
+**Why you can't just delete third-party cookies from JavaScript:**
+
+* **`httpOnly` cookies** - Many tracking cookies are set with the `httpOnly` flag, which prevents JavaScript from reading or deleting them. Only the server that set them can remove them.
+* **Domain restrictions** - Cookies set on `.google.com` or `.facebook.com` can only be deleted by those domains. Your JavaScript running on `yourdomain.com` has no access.
+* **Alternative storage** - Some scripts also write to `localStorage`, `sessionStorage`, `IndexedDB`, or even Web Workers. Cleaning up all possible storage locations is impractical.
+* **In-memory state** - A loaded script has already executed. Its event listeners, timers, and in-memory data persist until the page unloads. You can't "unrun" JavaScript.
+
+**The reliable solution: don't load the scripts in the first place.** A page reload creates a fresh execution context. On the fresh page, c15t reads the updated consent state and simply never loads the scripts that lost consent. No script means no cookies, no tracking, no in-memory state.
+
+**When reload does NOT happen:**
+
+* When a user is declining consent for the **first time** (no prior consent existed, so no scripts were loaded to clean up)
+* When `reloadOnConsentRevoked` is set to `false`
+* When the user is only **adding** consent (no revocations)
+
+Configure reload behavior in the provider:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+
+function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        reloadOnConsentRevoked: true, // default: true
+        callbacks: {
+          onBeforeConsentRevocationReload: ({ preferences }) => {
+            // Run cleanup before the page reloads
+            // e.g., flush pending analytics events
+            console.log('Reloading due to consent revocation:', preferences);
+          },
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> The reload and deferred sync are part of the broader initialization flow. See Initialization Flow for the full sequence.
+>
+> ℹ️ **Info:**
+> Setting reloadOnConsentRevoked: false means previously-loaded scripts will continue running after consent is revoked. Only disable this if you have a specific strategy for handling script cleanup.
+
+## The Revocation Flow
+
+When a user revokes consent, the following sequence occurs:
+
+**Simplified**
+
+1. **User revokes consent** — e.g. turns off "measurement" in the consent dialog
+2. **New consent saved** — updated preferences are written to cookies and localStorage
+3. **Pending sync stored** — the API update is deferred to localStorage (`c15t:pending-consent-sync`)
+4. **Page reloads** — a fresh execution context ensures revoked scripts never load
+5. **Fresh init** — c15t reads updated consent; scripts without consent are never loaded
+6. **Deferred API sync** — the pending consent change is sent to the backend and cleared from localStorage
+
+**Sequence Diagram**
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI as Consent UI
+    participant Store as Consent Store
+    participant Storage as Cookie + localStorage
+    participant API as c15t Backend
+    participant Browser
+
+    User->>UI: Revokes "measurement" consent
+    UI->>Store: saveConsents({ type: 'custom' })
+    Store->>Store: shouldReloadOnConsentChange() → true
+    Store->>Storage: Save new consent state
+    Store->>Storage: Store PendingConsentSync in localStorage
+    Store->>Browser: onBeforeConsentRevocationReload callback
+    Store->>Browser: window.location.reload()
+    Browser->>Browser: Fresh page load
+    Browser->>Storage: Read consent state
+    Browser->>Store: Initialize with updated consents
+    Note over Store: Scripts without consent are never loaded
+    Store->>Storage: Read PendingConsentSync
+    Store->>API: Sync consent to backend
+    Store->>Storage: Clear PendingConsentSync
+```
+
+**Key detail:** The API sync happens *after* the reload, not before. This ensures the page reloads as fast as possible. The pending sync data is stored in localStorage under the key `c15t:pending-consent-sync` and is picked up by the fresh page's initialization.

package/docs/concepts/glossary.md

@@ -0,0 +1,23 @@
+---
+title: Glossary
+description: Key terms used throughout the c15t documentation.
+---
+### Core Terms
+
+|Term|Definition|
+|--|--|
+|`subjectId`|Client-generated device/browser identifier (`sub_xxx`). Stored in the `c15t` cookie. Created on first consent save.|
+|`externalId`|Your authenticated user's ID (from Clerk, Auth0, etc.), linked via `identifyUser()`. Connects a device to a user account.|
+|`consents`|The **saved** consent state — `Record<string, boolean>` mapping categories to granted/denied. Used for gating scripts, iframes, and network requests.|
+|`selectedConsents`|**Unsaved** toggle state — what the user has toggled in the dialog but hasn't submitted yet. Becomes `consents` after save.|
+|`mode`|Client operating mode: `'hosted'` (full backend), `'offline'` (local only), or `'custom'` (bring your own handlers). Legacy alias: `'c15t'`. Set once in provider config. See [Client Modes](/docs/frameworks/react/concepts/client-modes).|
+|`model`|Consent regulatory model derived from jurisdiction: `'opt-in'`, `'opt-out'`, `'iab'`, or `null`. See [Consent Models](/docs/frameworks/react/concepts/consent-models).|
+
+### Regulatory Terms
+
+|Term|Definition|
+|--|--|
+|`jurisdiction`|A privacy regulation code (e.g., `GDPR`, `CCPA`, `PIPEDA`, `QC_LAW25`) detected from the user's geolocation. Maps to a consent model. See [Consent Models](/docs/frameworks/react/concepts/consent-models) for the full mapping table.|
+|GPC|Global Privacy Control — a browser signal (`Sec-GPC: 1`) indicating the user opts out of data sale/sharing. Honored when a policy sets `consent.gpc: true` (enabled by default in California presets).|
+|TCF|IAB Transparency and Consent Framework (v2.3) — a standard for programmatic advertising consent in GDPR jurisdictions. See [IAB TCF](/docs/frameworks/react/iab/overview).|
+|GVL|Global Vendor List — an IAB-maintained registry of ad-tech vendors and their declared purposes, used by the TCF consent flow.|

package/docs/concepts/initialization-flow.md

@@ -0,0 +1,141 @@
+---
+title: Initialization Flow
+description: What happens from provider mount to first render — the full consent lifecycle.
+---
+When the consent provider mounts, it creates a cached consent runtime, reads any stored consent from the browser, fetches the resolved policy from the backend (or uses SSR/offline data), and decides whether to show the banner. This entire sequence completes before the first meaningful consent-aware render.
+
+## Lifecycle Sequence
+
+**Simplified**
+
+1. **Provider mounts** — creates (or retrieves from cache) a consent runtime and store
+2. **Check stored consent** — reads existing consent from cookies / localStorage; if found and the policy fingerprint hasn't changed, the banner stays hidden
+3. **Fetch init data** — calls the backend `GET /init` (or uses SSR/offline data) for the resolved policy, location, and translations
+4. **Apply resolved policy** — the backend resolves the policy from your [policy pack](/docs/frameworks/react/concepts/policy-packs) based on visitor geo (region → country → fallback → default). The response includes the consent model, categories, UI mode, and a material fingerprint. If no policy pack is configured, the legacy jurisdiction-to-model mapping is used instead.
+5. **Decide banner visibility** — shows the banner only if no prior consent exists, the resolved policy requires it (`ui.mode` is `banner` or `dialog`), or the policy fingerprint changed since last consent
+6. **Gating enforced** — scripts, iframes, and network requests tagged with a consent category are blocked until that category is granted
+7. **User interacts** — choices are persisted to storage, synced to the backend (with `policySnapshotToken` if configured), and blocked scripts/iframes load immediately after consent is granted
+
+**Sequence Diagram**
+
+```mermaid
+sequenceDiagram
+    participant Provider as ConsentManagerProvider
+    participant Store as Consent Store
+    participant Storage as localStorage / Cookie
+    participant API as c15t Backend
+    participant UI as Banner / Dialog
+    participant Scripts as Script Loader
+
+    Provider->>Store: getOrCreateConsentRuntime()
+    Store->>Storage: getStoredConsent()
+    alt Stored consent exists
+        Storage-->>Store: consentInfo + consents
+        Store->>Store: activeUI = 'none'
+    else No stored consent
+        Store->>Store: isLoadingConsentInfo = true
+    end
+
+    Store->>Store: initConsentManager()
+    Store->>Storage: Check pending consent sync
+    opt Pending sync from revocation reload
+        Store->>API: Deferred setConsent() (non-blocking)
+    end
+
+    alt SSR data provided
+        Store->>Store: tryUseSSRData()
+    else No SSR data
+        Store->>API: GET /init
+        API-->>Store: policy, policyDecision, location, translations
+    end
+
+    Store->>Store: Apply resolved policy (model, categories, ui.mode)
+    Store->>Store: Check fingerprint change → re-prompt if needed
+    Store->>Store: Set activeUI, auto-grant if opt-out/none
+
+    alt User has no prior consent or policy changed
+        UI->>UI: Banner / Dialog appears (per policy ui.mode)
+        UI->>Store: saveConsents({ type })
+        Store->>Storage: Persist consent + subjectId + fingerprint
+        Store->>Scripts: updateScripts(), updateIframes(), updateNetwork()
+        Store->>API: POST /subjects + policySnapshotToken (non-blocking)
+    end
+```
+
+## How It Works
+
+**Mount** — When the provider renders, it creates (or retrieves from cache) a consent runtime and store. Any existing consent is read from localStorage/cookies immediately. If consent already exists and the policy fingerprint matches, the banner stays hidden and gating rules apply right away. See [Client Modes](/docs/frameworks/react/concepts/client-modes) for how the mode affects runtime creation.
+
+**Init** — The store fetches the resolved policy, location, and translation data. In hosted mode this calls `GET /init` on your backend; in offline mode it resolves from `offlinePolicy.policyPacks` locally. If SSR data was passed to the provider, the network fetch is skipped entirely. See [Server-Side Utilities](/docs/frameworks/react/server-side) for SSR setup.
+
+**Policy resolution** — When [policy packs](/docs/frameworks/react/concepts/policy-packs) are configured, the backend resolves the right policy for the visitor based on their geo-location (region → country → fallback → default). The resolved policy determines the consent model (`opt-in`, `opt-out`, `iab`, or `none`), which categories are in scope, and what UI to show. For `opt-out` and `none` models, all categories are auto-granted — unless the resolved policy has `consent.gpc: true` and the browser sends a Global Privacy Control signal, in which case `marketing` and `measurement` are denied. If no policy pack is configured, the legacy jurisdiction-to-model mapping is used instead. See [Consent Models](/docs/frameworks/react/concepts/consent-models) for details.
+
+**Re-prompting** — If the resolved policy's material fingerprint differs from the fingerprint stored with the user's last consent, the banner is shown again. This happens automatically when you change consent-affecting fields (model, categories, scope mode, allowed actions). Presentation-only changes do not trigger re-prompts. See [Policy Packs — Re-Prompting](/docs/frameworks/react/concepts/policy-packs#re-prompting) for details.
+
+**Save** — When the user interacts with the banner or dialog, their choices are persisted to localStorage/cookies and synced to the backend (along with the `policySnapshotToken` if snapshot signing is configured). Script, iframe, and network gating rules update immediately based on the new consent state. See the [Script Loader](/docs/frameworks/react/script-loader), [Iframe Blocking](/docs/frameworks/react/iframe-blocking), and [Network Blocker](/docs/frameworks/react/network-blocker) guides for gating details.
+
+**Revocation** — If a user revokes a previously granted category, the page reloads by default to ensure a clean execution environment. The API sync is deferred to the fresh page load. See [Cookie Management](/docs/frameworks/react/concepts/cookie-management) for revocation and persistence details.
+
+## When Does the Banner Show?
+
+The banner appears when any of these conditions are true:
+
+1. **No existing consent** — the user has never consented (or their consent was cleared), **and** the resolved policy requires a UI (`ui.mode` is `banner` or `dialog`, or the model is `opt-in` or `iab`)
+2. **Policy changed** — the material policy fingerprint differs from the fingerprint stored with the user's last consent (re-prompting)
+3. **Storage is accessible** — the browser allows localStorage (not blocked in private mode)
+
+If the resolved model is `none` or `opt-out` (and `ui.mode` is `none`), consents are auto-granted and the banner never appears. See [Consent Models](/docs/frameworks/react/concepts/consent-models) and [Policy Packs](/docs/frameworks/react/concepts/policy-packs) for details.
+
+## Debugging the Lifecycle
+
+Use the DevTools panel and callbacks to inspect each step of the initialization flow:
+
+|Step|DevTools Panel|Callback|What to check|
+|--|--|--|--|
+|Init / SSR hydration|Location|`onBannerFetched`|jurisdiction, countryCode, regionCode populated?|
+|Policy resolution|Policy|`onBannerFetched`|`policyId`, `matchedBy`, `fingerprint` in policyDecision|
+|Model resolution|Location|`onBannerFetched`|`model` value matches the resolved policy|
+|Banner visibility|Consents|—|`activeUI` in store state; does policy `ui.mode` require it?|
+|Re-prompting|Policy|—|Fingerprint mismatch between stored and resolved policy?|
+|Consent save|Consents + Events|`onConsentSet`|`preferences` object in callback payload|
+|Script loading|Scripts|`onConsentSet`|Script IDs and their load/blocked status|
+|Reload on revocation|Events|`onBeforeConsentRevocationReload`|Fires before reload; check localStorage for `c15t:pending-consent-sync`|
+|Deferred sync|Events|`onError` (if sync fails)|After reload, check Events panel for successful API call|
+
+Configure callbacks in the provider to log lifecycle events, and add DevTools for a visual inspector:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+import { DevTools } from '@c15t/dev-tools/react';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        callbacks: {
+          onBannerFetched: ({ jurisdiction, location }) => {
+            console.log('Init complete:', { jurisdiction, location });
+          },
+          onConsentSet: ({ preferences }) => {
+            console.log('Consent saved:', preferences);
+          },
+          onBeforeConsentRevocationReload: ({ preferences }) => {
+            console.log('Reloading due to revocation:', preferences);
+          },
+          onError: ({ error }) => {
+            console.error('Consent error:', error);
+          },
+        },
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {process.env.NODE_ENV !== 'production' && <DevTools />}
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```

package/docs/concepts/policy-packs.md

@@ -0,0 +1,227 @@
+---
+title: Policy Packs
+description: How c15t resolves regional consent policies and what a policy pack controls.
+---
+Different countries need different consent experiences. Policy packs let you define those rules once — c15t picks the right one automatically based on where the visitor is.
+
+A policy pack is an ordered array of policies. Each policy targets a region or country and controls the consent model, which categories are in scope, what UI is shown, and how consent is recorded.
+
+There are three ways to configure policy packs:
+
+1. **consent.io (recommended)** — use [consent.io](https://consent.io) as your hosted backend. Configure packs visually in the dashboard or via API — no code changes required. Works with any frontend, including static sites.
+2. **Self-hosted backend** — define packs in code via `policyPacks` and resolve them from real request geo data. Full control over policy logic and storage.
+3. **Offline fallback** — pass the same policy shapes to the frontend via `offlinePolicy.policyPacks`. Used as a resilience fallback when the backend is unreachable, or for quick local experimentation and demos. If you omit `offlinePolicy.policyPacks`, c15t falls back to a synthetic worldwide opt-in banner instead of no-banner mode.
+
+In both hosted and self-hosted modes, the **backend is always the source of truth**. Offline packs never override a live backend decision.
+
+## Quickstart
+
+The fastest way to get started is with the built-in presets:
+
+```ts
+import { policyPackPresets } from 'c15t';
+
+const policies = [
+  policyPackPresets.europeOptIn(),    // GDPR opt-in banner
+  policyPackPresets.californiaOptOut(), // CCPA opt-out banner
+  policyPackPresets.worldNoBanner(),          // No banner elsewhere
+];
+```
+
+|Preset|Model|UI|Matches|
+|--|--|--|--|
+|`europeOptIn()`|`opt-in`|banner|EEA + UK countries + geo fallback|
+|`europeIab()`|`iab`|banner|EEA + UK countries + geo fallback (TCF 2.3)|
+|`californiaOptOut()`|`opt-out`|none|US-CA region|
+|`quebecOptIn()`|`opt-in`|banner|CA-QC region|
+|`worldNoBanner()`|`none`|none|default fallback|
+
+Most apps only need these presets — pick the ones that match your regions, pass them to your backend config or provider, and you're done. Customize individual fields or write fully custom policies when you need more control.
+
+For banner/dialog actions, policy packs can also control grouped button arrangement:
+
+```ts
+ui: {
+  mode: 'banner',
+  banner: {
+    allowedActions: ['reject', 'accept', 'customize'],
+    layout: [['reject', 'accept'], 'customize'],
+    direction: 'row',
+    primaryAction: 'customize',
+  },
+}
+```
+
+That expresses arrangement only. Button appearance like `stroke`, `filled`, or `ghost` lives in the UI theme.
+
+## What Users See
+
+Each policy combination produces a different consent experience:
+
+|Policy Config|User Experience|
+|--|--|
+|`model: 'opt-in'`, `ui.mode: 'banner'`|Banner appears, nothing loads until the user consents|
+|`model: 'opt-out'`, `ui.mode: 'none'`|No banner, everything loads immediately — user opts out via a "Do Not Sell" link|
+|`model: 'none'`, `ui.mode: 'none'`|No banner, all categories auto-granted silently|
+|`model: 'opt-in'`, `ui.mode: 'dialog'`|Full-screen dialog, nothing loads until the user consents|
+|`model: 'iab'`, `ui.mode: 'banner'`|IAB TCF 2.3 banner with vendor-level controls|
+
+## How Policy Resolution Works
+
+When a visitor arrives, c15t walks the policy pack in priority order:
+
+1. **Match by region** — checks for a policy targeting the specific region (e.g., US-CA, CA-QC)
+2. **Match by country** — if no region match, checks for a country-level policy (e.g., US, DE)
+3. **Fallback (geo failure)** — if geo-location failed (no country detected), uses the policy marked with `match.fallback`
+4. **Fall back to default** — if nothing matches, uses the policy marked as the default
+5. **No match, no default** — resolves to no-banner mode (silent, no consent UI)
+
+Within the same matcher type, the first policy in the array wins. Pack order matters when two policies target the same country or region.
+
+The **fallback** step is distinct from **default**: `isDefault` is a catch-all for known locations that don't match any specific policy ("rest of world"), while `fallback` is a safety net for unknown locations when geo-headers are missing ("assume strictest"). The `europeOptIn()` and `europeIab()` presets include `fallback: true` by default so EU-level consent applies when geo fails.
+
+> ⚠️ **Warning:**
+> Only one default and one fallback policy are allowed. Use inspectPolicies() to surface overlapping matchers and other warnings before deployment.
+
+Inspect the resolved policy at runtime with `useConsentManager()`:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function PolicyDebug() {
+  const { locationInfo, model, policy, policyDecision } = useConsentManager();
+
+  return (
+    <pre>
+      {JSON.stringify(
+        {
+          country: locationInfo?.countryCode,
+          region: locationInfo?.regionCode,
+          model,
+          policyId: policy?.id,
+          matchedBy: policyDecision?.matchedBy,
+          fingerprint: policyDecision?.fingerprint,
+        },
+        null,
+        2
+      )}
+    </pre>
+  );
+}
+```
+
+## Common Patterns
+
+**The 80% case** — strict in Europe, light in California, silent everywhere else:
+
+```ts
+const policies = [
+  {
+    id: 'eu',
+    match: { countries: ['DE', 'FR', 'IT'] },
+    consent: { model: 'opt-in', categories: ['necessary', 'measurement', 'marketing'] },
+    ui: { mode: 'banner' },
+  },
+  {
+    id: 'ca',
+    match: { regions: [{ country: 'US', region: 'CA' }] },
+    consent: { model: 'opt-out', gpc: true },
+    ui: { mode: 'none' },
+  },
+  {
+    id: 'default',
+    match: { isDefault: true },
+    consent: { model: 'none' },
+    ui: { mode: 'none' },
+  },
+];
+```
+
+**Region overrides country** — stricter rules for California than the rest of the US:
+
+```ts
+const policies = [
+  {
+    id: 'us_ca',
+    match: { regions: [{ country: 'US', region: 'CA' }] },
+    consent: { model: 'opt-in', scopeMode: 'strict' },
+    ui: { mode: 'banner' },
+  },
+  {
+    id: 'us',
+    match: { countries: ['US'] },
+    consent: { model: 'opt-out' },
+    ui: { mode: 'banner' },
+  },
+];
+// US-CA → us_ca (region match wins)
+// US-NY → us (country match)
+```
+
+**Different wording per region** — use `i18n.messageProfile` to vary copy without changing the consent model:
+
+```ts
+const c15t = c15tInstance({
+  i18n: {
+    defaultProfile: 'default',
+    messages: {
+      default: {
+        translations: {
+          en: { cookieBanner: { title: 'Privacy choices' } },
+          es: { cookieBanner: { title: 'Tus opciones de privacidad' } },
+        },
+      },
+      eu: {
+        fallbackLanguage: 'en',
+        translations: {
+          en: { cookieBanner: { title: 'EU GDPR Consent' } },
+          fr: { cookieBanner: { title: 'Consentement RGPD' } },
+          de: { cookieBanner: { title: 'GDPR-Einwilligung' } },
+        },
+      },
+    },
+  },
+  policyPacks: [
+    {
+      id: 'eu',
+      match: { countries: ['DE', 'FR', 'IT'] },
+      i18n: { messageProfile: 'eu' },
+      consent: { model: 'opt-in' },
+      ui: { mode: 'banner' },
+    },
+  ],
+});
+```
+
+In that setup, the `eu` policy uses only the `eu` language set. So Europe can
+resolve to `en`, `fr`, or `de`, but not to `es` or any other locale defined
+only in `default`. If the browser asks for an unsupported locale, c15t falls
+back to the `eu` profile's `fallbackLanguage`.
+
+## Re-Prompting on Policy Change
+
+When you change a policy in a way that affects consent semantics — like adding a category, changing the consent model, or modifying allowed actions — c15t automatically re-prompts returning users.
+
+This works through the **material policy fingerprint**: a hash of only the consent-affecting fields (model, categories, scope, allowed actions, grouped action layout, direction, proof settings). Presentation-only changes like copy, button styling, or scroll lock do not trigger re-prompts.
+
+|Change|Re-prompts?|
+|--|--|
+|Add a consent category|Yes|
+|Change `model` from `opt-out` to `opt-in`|Yes|
+|Remove an `allowedAction`|Yes|
+|Change `uiProfile` or button styling|No|
+|Update translation copy|No|
+|Change `scrollLock`|No|
+
+## Design Guidelines
+
+* **Start from presets.** Use `policyPackPresets` to get running, then customize for your needs.
+* **Keep packs small.** A handful of regional policies is better than dozens of tiny fragments.
+* **Think risk, not geography.** Geography is just a matcher — the real question is what consent behavior each region needs.
+* **Always include a default.** Unless "no banner for unmatched traffic" is intentional.
+* **Set a fallback for geo failures.** Mark your strictest policy with `match.fallback=true` so users in unknown locations still see a consent banner. The `europeOptIn()` and `europeIab()` presets do this automatically.
+* **Keep policy IDs stable.** They appear in debugging output, snapshots, and audit records.
+* **Use `inspectPolicies()` before deploying.** It catches overlapping matchers, missing defaults, and IAB misconfigurations.
+
+> ℹ️ **Info:**
+> For provider setup, see the React policy pack guide. For backend configuration, see the self-host guide.