@c15t/nextjs 2.0.0-rc.1 → 2.0.0-rc.10

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/nextjs';
+
+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/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+      }}
+    >
+      <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/nextjs';
+
+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/nextjs';
+
+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/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        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/nextjs';
+
+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/nextjs';
+
+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,116 @@
+---
+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
+'use client';
+
+import { useConsentManager } from '@c15t/nextjs';
+
+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
+'use client';
+
+import { useConsentManager } from '@c15t/nextjs';
+
+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.

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/nextjs';
+
+function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        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.|