@c15t/react 2.0.0-rc.0 → 2.0.0-rc.10

package/docs/components/consent-widget.md

@@ -0,0 +1,160 @@
+---
+title: ConsentWidget
+description: An inline consent management widget for embedding in settings or privacy pages. Shows category toggles with accordion layout.
+---
+`ConsentWidget` is a standalone, inline consent management widget. Unlike `ConsentDialog` (which is a modal), the widget embeds directly in your page layout - ideal for privacy settings pages, account preferences, or any page where users should be able to manage consent without a modal overlay.
+
+## Basic Usage
+
+```tsx
+import { ConsentWidget } from '@c15t/react';
+
+export function PrivacySettingsPage() {
+  return (
+    <>
+      <h1>Privacy Settings</h1>
+      <p>Manage your cookie preferences below.</p>
+      <ConsentWidget />
+    </>
+  );
+}
+```
+
+## Configuration
+
+```tsx
+<ConsentWidget
+  hideBranding
+  legalLinks={['privacyPolicy', 'cookiePolicy']}
+  noStyle={false}
+  disableAnimation={false}
+/>
+```
+
+## Accordion Behavior
+
+Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
+
+## Styling First
+
+> ℹ️ **Info:**
+> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, and toggle before reaching for compound components. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentWidgetAccordion: 'rounded-3xl border border-black/10',
+        consentWidgetFooter: 'border-t border-black/10 px-6',
+        toggle: 'shadow-sm',
+      },
+    },
+  }}
+>
+  <ConsentWidget />
+</ConsentManagerProvider>
+```
+
+Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
+
+## Advanced: Compound Components
+
+Use compound components only when you need to rearrange the widget's existing primitives while keeping policy-aware action grouping:
+
+```tsx
+<ConsentWidget.Root>
+  <ConsentWidget.Accordion type="multiple">
+    <ConsentWidget.AccordionItems />
+  </ConsentWidget.Accordion>
+  <ConsentWidget.PolicyActions />
+</ConsentWidget.Root>
+```
+
+* `ConsentWidget.Root` — Theme context provider
+* `ConsentWidget.Accordion` — Radix-based accordion root
+* `ConsentWidget.AccordionItems` — Auto-generates toggle items from consent config
+* `ConsentWidget.AccordionItem` — Individual category item
+* `ConsentWidget.AccordionTrigger` — Clickable header for each item
+* `ConsentWidget.AccordionContent` — Collapsible content area
+* `ConsentWidget.AccordionArrow` — Expand/collapse indicator
+* `ConsentWidget.Switch` — Category toggle switch
+* `ConsentWidget.PolicyActions` — Renders grouped policy-aware actions
+* `ConsentWidget.Footer` — Footer container
+* `ConsentWidget.FooterSubGroup` — Groups related buttons
+* `ConsentWidget.AcceptAllButton` — Accepts all consent
+* `ConsentWidget.RejectButton` — Rejects all consent
+* `ConsentWidget.SaveButton` — Saves custom selections
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentWidget.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentWidget.PolicyActions />
+```
+
+`renderAction` is optional. Return the stock button compounds when you want custom mapping while preserving built-in c15t behavior and copy:
+
+```tsx
+<ConsentWidget.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentWidget.AcceptAllButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentWidget.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentWidget.SaveButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+Use `useTranslations()` only when you are replacing the button markup entirely:
+
+```tsx
+import { ConsentWidget, useTranslations } from '@c15t/react';
+
+export function CustomWidgetActions() {
+  const { common } = useTranslations();
+
+  return (
+    <ConsentWidget.PolicyActions
+      renderAction={(action, props) => (
+        <button
+          key={props.key}
+          type="button"
+          className={props.isPrimary ? 'btn-primary' : 'btn-secondary'}
+          style={props.style}
+        >
+          {action === 'accept'
+            ? common.acceptAll
+            : action === 'reject'
+              ? common.rejectAll
+              : common.save}
+        </button>
+      )}
+    />
+  );
+}
+```
+
+For a fixed footer layout, render `ConsentWidget.Footer` and `ConsentWidget.FooterSubGroup` manually instead of using `ConsentWidget.PolicyActions`.
+
+If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
+
+## Props
+
+### ConsentWidgetProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|hideBranding|boolean \|undefined|Controls whether to hide the branding in the widget footer.|-|Optional|
+|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display in the widget footer.|-|Optional|

package/docs/components/dev-tools.md

@@ -0,0 +1,63 @@
+---
+title: DevTools
+description: A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
+---
+`DevTools` is a floating panel that shows the internal state of the consent manager. Use it during development to inspect consent values, geolocation results, loaded scripts, and debug consent flows. Also exported as `C15TDevTools` if you need to avoid naming conflicts with other devtools.
+
+> ℹ️ **Info:**
+> DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
+
+## Installation
+
+DevTools lives in a separate package to keep it out of production bundles:
+
+```bash
+bun add -D @c15t/dev-tools
+```
+
+## Usage
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { DevTools } from '@c15t/dev-tools/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
+      {children}
+      {process.env.NODE_ENV === 'development' && <DevTools />}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Configuration
+
+```tsx
+<DevTools
+  position="bottom-right"  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  defaultOpen={false}       // Start with panel open
+  namespace="c15tStore"     // Store namespace to connect to
+  disabled={false}          // Disable without removing from tree
+/>
+```
+
+## Panels
+
+|Panel|What it shows|
+|--|--|
+|**Consents**|Current consent state for all categories|
+|**Location**|Detected jurisdiction, country, region, and consent model|
+|**Scripts**|Configured scripts and their load status|
+|**IAB**|IAB TCF state (when enabled) - TC string, vendor consents, purposes|
+|**Events**|Timeline of consent events and state changes|
+|**Actions**|Buttons to trigger consent actions (accept all, reject all, reset)|
+
+## Props
+
+### C15TDevToolsProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disabled|boolean \|undefined|Whether the DevTools should be disabled Useful for production builds|false|Optional|

package/docs/components/frame.md

@@ -0,0 +1,73 @@
+---
+title: Frame
+description: A consent-gated content wrapper - children only mount when the required consent category is granted.
+---
+`Frame` conditionally renders its children based on consent state. When consent for the specified category is not granted, a placeholder is shown instead. Children are not mounted at all until consent is given, preventing any network requests or script execution.
+
+## Basic Usage
+
+```tsx
+import { Frame } from '@c15t/react';
+
+function YouTubeEmbed() {
+  return (
+    <Frame category="marketing">
+      <iframe
+        src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+        width="560"
+        height="315"
+        allowFullScreen
+      />
+    </Frame>
+  );
+}
+```
+
+## Custom Placeholder
+
+Replace the default placeholder:
+
+```tsx
+<Frame
+  category="experience"
+  placeholder={
+    <div className="rounded-lg border p-8 text-center">
+      <p>This content requires experience cookies.</p>
+      <p>Please enable them in your privacy settings.</p>
+    </div>
+  }
+>
+  <InteractiveWidget />
+</Frame>
+```
+
+## Compound Components
+
+Build fully custom placeholder layouts:
+
+```tsx
+<Frame.Root category="marketing">
+  <Frame.Title category="marketing" />
+  <Frame.Button category="marketing" />
+</Frame.Root>
+```
+
+* `Frame.Root` - Container with default placeholder styling
+* `Frame.Title` - Displays a consent-request message with the category name
+* `Frame.Button` - Button that opens the consent dialog for the specified category
+
+## Automatic Category Registration
+
+When `Frame` mounts, it automatically adds its `category` to the active `consentCategories` list. This means you don't need to explicitly list the category in your provider's `consentCategories` option - if a `Frame` component uses it, it will be registered.
+
+## Props
+
+### FrameProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|Content rendered when consent is granted. Children are not mounted until consent is given, preventing unnecessary network requests.|-|✅ Required|
+|category|AllConsentNames|Consent category required to render children.|-|✅ Required|
+|placeholder|ReactNode|A custom placeholder component to display when consent is not met. If not provided, a default placeholder will be displayed.|-|Optional|
+|noStyle|boolean \|undefined|When true, removes all default styling from the component|false|Optional|
+|theme|any|Custom theme to override default styles while maintaining structure and accessibility. Merges with defaults. Ignored when \`noStyle=\{true}\`.|undefined|Optional|

package/docs/concepts/client-modes.md

@@ -0,0 +1,175 @@
+---
+title: Client Modes
+description: Choose how c15t connects to its backend - full hosted integration, offline-only, or bring your own backend.
+---
+c15t supports three client modes that determine how consent data is stored and synchronized. Choose the mode that matches your infrastructure:
+
+* **Hosted mode** - Recommended for production. Backend-backed consent with geolocation, centralized policy resolution, audit history, and offline fallback.
+* **Offline mode** - Browser-only storage with no network requests. Best for local development, demos, static deployments, or controlled fallback scenarios.
+* **Custom mode** - Bring your own backend with custom endpoint handlers
+
+> ℹ️ **Info:**
+> If you need durable consent records, server-side enforcement, or automatic jurisdiction detection, use hosted mode. Offline mode cannot provide those guarantees because consent lives only in the browser.
+
+<span id="c15t-mode" />
+
+## Hosted Mode (Recommended)
+
+The default mode. Connects to a c15t backend for full consent lifecycle management. We recommend using [inth.com](https://inth.com) for a fully managed experience, but you can [self-host](/docs/self-host) as well.
+
+> ℹ️ **Info:**
+> mode: 'hosted' is the preferred value. The legacy alias mode: 'c15t' is still supported for backward compatibility.
+
+**What happens:**
+
+1. On page load, the client calls `/init` to fetch geolocation, jurisdiction, localized translation strings
+2. When the user grants or changes consent, it is saved locally before being synced to the backend.
+3. If the backend is unreachable, it falls back to Offline mode and re-syncs with the backend when it's available
+
+**Configuration:**
+
+* `backendURL` (required) - API endpoint path
+
+**Why it is the default for production:**
+
+* The backend stays the source of truth for policy, translations, and jurisdiction logic
+* Consent decisions can be stored beyond the current browser session for audit and support workflows
+* Server-side systems can preload consent-aware behavior instead of waiting for client-only storage
+* If the backend is temporarily unavailable, c15t can fall back locally and re-sync later
+
+**Best for:** Production apps that need geolocation-based jurisdiction detection, consent record storage, and compliance audit trails.
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner } from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+      }}
+    >
+      <ConsentBanner />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Offline Mode
+
+No network requests. Consent is stored entirely in the browser using localStorage and cookies.
+
+**What happens:**
+
+1. Default jurisdiction is GDPR unless manually set via `overrides`
+2. Consent preferences persist locally only
+3. No server-side consent records or analytics
+
+> ℹ️ **Info:**
+> Important: Offline mode still stores consent locally (cookie + localStorage). It only skips backend storage and sync.
+
+### Consequences of Browser-Only Storage
+
+If consent is not stored at all (for example, storage is blocked or frequently cleared):
+
+* Users are treated as new visitors and must re-consent repeatedly
+* Preferences are lost across browser resets, private sessions, and device changes
+* You have no reliable audit evidence to prove prior consent choices
+* Support and compliance teams have no centralized visibility into consent history by default
+* Server-side systems cannot apply prior consent decisions before client initialization
+
+**Trade-offs:**
+
+* No automatic geolocation or jurisdiction detection
+* No consent audit trail
+* No centralized policy or translation updates without shipping frontend changes
+* No cross-device sync
+* No server-side visibility before client initialization
+* Works without any backend infrastructure
+
+**Best for:** Local development, Storybook/static demos, resilience fallback, or simpler sites that explicitly accept browser-only consent storage.
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner } from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'offline',
+        overrides: {
+          country: 'DE', // Override country to trigger GDPR jurisdiction
+        },
+      }}
+    >
+      <ConsentBanner />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Custom Mode
+
+Bring your own backend. You provide handler functions for each consent endpoint, and c15t calls them instead of making HTTP requests.
+
+**What happens:**
+
+1. On page load, the client calls your endpoint handler to fetch geolocation, jurisdiction, localized translation strings
+2. When the user grants or changes consent, it is saved locally before being synced to the backend.
+3. If one of your handlers fails, c15t returns a handler error and keeps local consent state, but automatic offline fallback and retry queue behavior is not provided for custom handlers by default
+
+This lets you integrate c15t with any existing API - your CRM, your own consent database, or a third-party compliance service.
+
+**Best for:** Teams with existing consent infrastructure that want c15t's frontend without its backend.
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner } from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'custom',
+        endpointHandlers: {
+          async init() {
+            const res = await fetch('/my-api/consent/init');
+            const data = await res.json();
+            return { data, response: res, error: null };
+          },
+          async setConsent(options) {
+            const res = await fetch('/my-api/consent', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(options?.body),
+            });
+            return { data: await res.json(), response: res, error: null };
+          },
+        },
+      }}
+    >
+      <ConsentBanner />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Choosing a Mode
+
+|Feature|Hosted|Offline|Custom|
+|--|--|--|--|
+|Geolocation|Automatic|Manual via overrides|Your implementation|
+|Policy source of truth|Backend-managed|Bundled into the frontend|Your implementation|
+|Consent sync|API|Local only|Your implementation|
+|Audit trail|Backend records|Not available|Your implementation|
+|Server-side consent awareness|Supported|Not available|Your implementation|
+|SSR data|Supported|Not available|Your implementation|
+|Analytics|Built-in|Not available|Your implementation|
+|Infrastructure|c15t backend|None|Your backend|
+|Setup effort|Minimal|Zero|Moderate|

package/docs/concepts/consent-categories.md

@@ -0,0 +1,97 @@
+---
+title: Consent Categories
+description: How c15t organizes tracking technologies into five consent categories.
+---
+c15t organizes tracking technologies into five consent categories that align with GDPR and ePrivacy Directive requirements. Rather than asking users to approve or deny individual cookies or scripts, each category groups related tracking purposes together so users can make meaningful, informed choices about how their data is used.
+
+> ℹ️ **Info:**
+> Why categories, not cookie lists? Many consent banners list individual cookie names like \_ga, \_gid, or \_fbp. This is counterproductive:Technical names are meaningless to users — nobody knows what \_gid does by reading its name.Information overload drives "accept all" — a wall of cookie names pushes users toward dismissing the banner as fast as possible, which is the opposite of informed consent.Purpose is what matters — privacy regulations (GDPR, ePrivacy) require clear information about the purposes of data processing, not a cookie-by-cookie inventory.Cookie lists go stale — third-party scripts change their cookie names across versions, creating a maintenance burden that provides no real transparency.c15t's category-based approach — "measurement", "marketing", "experience" — communicates purpose directly. Users understand why data is collected, not how it is stored.
+
+Configure which categories your app supports in the provider:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        consentCategories: ['necessary', 'measurement', 'marketing'],
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## The Five Categories
+
+|Category|Default|Toggleable|Description|
+|--|--|--|--|
+|`necessary`|`true`|No|Strictly necessary to operate or deliver the service|
+|`functionality`|`false`|Yes|Basic interactions and functionalities|
+|`experience`|`false`|Yes|Improve quality of user experience|
+|`measurement`|`false`|Yes|Measure traffic and analyze behavior|
+|`marketing`|`false`|Yes|Deliver personalized ads or marketing content|
+
+The `necessary` category has `disabled: true` set internally, which prevents the user from toggling it off in the consent UI. All other categories can be freely toggled by the user.
+
+Note that all categories except `necessary` have `display: false` by default. A category appears in the consent UI only if you include it in `consentCategories`. Categories not listed are hidden from the UI, but they still exist in consent state and may be affected by model-level behavior (for example, auto-grant in `opt-out` or `null` model flows).
+
+Check if a specific category has consent using the `has()` method:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function AnalyticsLoader() {
+  const { has } = useConsentManager();
+
+  if (has('measurement')) {
+    // Safe to load analytics scripts
+  }
+
+  return null;
+}
+```
+
+## Configuring Categories
+
+The `consentCategories` array controls which consent categories are presented to the user in the consent UI. Only categories you list in this array will appear as toggleable options in the consent banner or modal.
+
+The `necessary` category is always implicitly included even if you do not add it to the array. You never need to worry about accidentally omitting it -- c15t ensures it is always present and always enabled.
+
+For example, if you set:
+
+```
+consentCategories: ['necessary', 'measurement', 'marketing']
+```
+
+then only those three categories will show toggles in the consent UI. The `functionality` and `experience` categories will not appear as user-configurable toggles.
+
+In `opt-in`/`iab` flows, hidden categories usually remain `false` unless you explicitly set them. In `opt-out`/`null` flows, categories may be auto-granted even when hidden.
+
+This gives you precise control over which consent choices to present to your users. A simple blog that only runs an analytics script might only need `measurement`. A media site with ad integrations would include `marketing`. A SaaS application with personalization features might add `experience` and `functionality` as well. You choose what is relevant to your site and c15t handles the rest - storing consent state, exposing it through hooks, and ensuring the right categories are active based on the user's choices.
+
+You can dynamically update which categories are active:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function CategoryManager() {
+  const { consentCategories, setConsentCategories } = useConsentManager();
+
+  const addExperienceCategory = () => {
+    setConsentCategories([...consentCategories, 'experience']);
+  };
+
+  return (
+    <button onClick={addExperienceCategory}>
+      Enable experience features
+    </button>
+  );
+}
+```

package/docs/concepts/consent-models.md

@@ -0,0 +1,112 @@
+---
+title: Consent Models
+description: How c15t determines consent behavior based on legal jurisdiction.
+---
+c15t supports four consent models that control how consent defaults, banner visibility, and category gating behave:
+
+|Model|Philosophy|Banner|Categories default to|
+|--|--|--|--|
+|`opt-in`|Explicit consent required|Blocking banner|`false` (except `necessary`)|
+|`opt-out`|Processing allowed by default|Non-blocking notice|`true` (all granted)|
+|`iab`|IAB TCF 2.3 for programmatic ads|TCF banner|Managed by TCF framework|
+|`null`|No regulation detected|No banner|`true` (all auto-granted)|
+
+There are two ways c15t determines which model applies:
+
+1. **Policy packs** (recommended) — you explicitly set the model per region in a `PolicyConfig`. This gives you full control over which regions get which model. See [Policy Packs](/docs/frameworks/react/concepts/policy-packs).
+
+2. **Automatic jurisdiction mapping** (legacy default) — when no policy pack is configured, c15t detects the visitor's jurisdiction via geolocation and maps it to a model using the table below. This still works but gives you less control over categories, UI, and scope.
+
+> ℹ️ **Info:**
+> When using policy packs, the consent.model field in each policy directly sets the model — the automatic jurisdiction mapping is bypassed for that request.
+
+Read the current consent model from the hook:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function ConsentStatus() {
+  const { model, policy } = useConsentManager();
+
+  return (
+    <p>
+      Current consent model: {model ?? 'detecting...'}
+      {policy && ` (from policy: ${policy.id})`}
+    </p>
+  );
+}
+```
+
+## The Four Models
+
+### Opt-in
+
+The strictest consent model, used for GDPR and similar regulations that require explicit, affirmative consent before any non-essential data processing occurs. All consent categories except `necessary` default to `false`. A consent banner must be shown before any tracking scripts load.
+
+Applies to: EU (GDPR), UK (UK GDPR), Switzerland, Brazil (LGPD), Japan (APPI), South Korea (PIPA), Quebec (Law 25). Also the fallback for unknown jurisdiction codes.
+
+### Opt-out
+
+Used for CCPA-style regulations where data processing is permitted by default until the user exercises their right to opt out. All consent categories default to `true`. A blocking banner is not required — the typical pattern is a non-intrusive notice or footer link.
+
+Applies to: California (CCPA), Canada (PIPEDA), Australia.
+
+When the policy has `consent.gpc: true`, the browser's Global Privacy Control signal (`Sec-GPC: 1` or `navigator.globalPrivacyControl`) is respected — `marketing` and `measurement` are denied while other categories remain granted. The built-in California presets enable this by default. See [Policy Packs — GPC](/docs/frameworks/react/concepts/policy-packs#gpc) for details.
+
+### IAB
+
+IAB Transparency and Consent Framework (TCF) 2.3 mode for programmatic advertising compliance. Only activates when two conditions are met: the jurisdiction is `GDPR` or `UK_GDPR`, and `iab.enabled` is `true` in your configuration.
+
+When active, IAB mode generates TC strings, registers the `__tcfapi` CMP API, and works with the Global Vendor List (GVL) for machine-readable consent signals. If `iab.enabled` is not set, GDPR jurisdictions fall back to standard opt-in.
+
+### null
+
+Returned when no jurisdiction is detected (`NONE` or `null`). No banner is displayed. On first visit, all categories are auto-granted.
+
+## Jurisdiction Mapping
+
+When no policy pack is configured, c15t maps jurisdictions to models automatically:
+
+|Jurisdiction Code|Region|Consent Model|
+|--|--|--|
+|`GDPR`|European Union|opt-in|
+|`UK_GDPR`|United Kingdom|opt-in|
+|`CH`|Switzerland|opt-in|
+|`BR`|Brazil (LGPD)|opt-in|
+|`APPI`|Japan|opt-in|
+|`PIPA`|South Korea|opt-in|
+|`PIPEDA`|Canada (excl. Quebec)|opt-out|
+|`QC_LAW25`|Quebec, Canada|opt-in|
+|`CCPA`|California, USA|opt-out|
+|`AU`|Australia|opt-out|
+|`NONE`|No jurisdiction|null|
+|*(unknown)*|Any other|opt-in|
+
+**IAB override:** If `iab.enabled: true` and the jurisdiction is `GDPR` or `UK_GDPR`, the model becomes `'iab'` instead of `'opt-in'`. This override only applies to those two jurisdictions.
+
+> ℹ️ **Info:**
+> With policy packs, you set the model explicitly per policy — the automatic mapping above is only used as a fallback when no policy pack is configured, or for non-policy-pack features like auto-granting in opt-out jurisdictions.
+
+Override the detected jurisdiction for testing:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function JurisdictionTester() {
+  const { setOverrides } = useConsentManager();
+
+  return (
+    <div>
+      <button onClick={() => setOverrides({ country: 'DE' })}>
+        Test as EU visitor
+      </button>
+      <button onClick={() => setOverrides({ country: 'US', region: 'CA' })}>
+        Test as California visitor
+      </button>
+    </div>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> For full control over which model applies where — plus UI customization, category scoping, and re-prompting — see Policy Packs.