@c15t/nextjs 2.1.0 → 2.2.1

package/docs/integrations/youtube.md

@@ -0,0 +1,193 @@
+---
+title: YouTube
+description: Keep YouTube iframes unmounted until consent with a
+  privacy-enhanced, lazy-loaded React or Next.js embed.
+icon: youtube
+group: integrations
+---
+`YouTubeEmbed` is a renderable integration for React and Next.js. It uses c15t's
+`Frame` consent boundary, so the YouTube iframe is not mounted and no YouTube
+request is made until the configured consent category is allowed.
+
+The component does not load the YouTube IFrame Player API. It is intended for
+standard iframe embeds and keeps script readiness separate from iframe gating.
+
+## Integrate with c15t
+
+`YouTubeEmbed` must render inside a `ConsentManagerProvider`. Complete the
+[React quickstart](/docs/frameworks/react/quickstart) or
+[Next.js quickstart](/docs/frameworks/next/quickstart) first.
+
+**React**
+
+```tsx
+import { YouTubeEmbed } from '@c15t/react';
+
+export function ProductVideo() {
+  return (
+    <YouTubeEmbed
+      consentCategory="marketing"
+      params={{ controls: true, playsinline: true }}
+      title="Product overview"
+      videoId="dQw4w9WgXcQ"
+    />
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { YouTubeEmbed } from '@c15t/nextjs';
+
+export function ProductVideo() {
+  return (
+    <YouTubeEmbed
+      consentCategory="marketing"
+      params={{ controls: true, playsinline: true }}
+      title="Product overview"
+      videoId="dQw4w9WgXcQ"
+    />
+  );
+}
+```
+
+`marketing` is the default category. Choose a different category only when it
+matches the purpose of the embed and the policy presented to your users.
+
+## How c15t loads it
+
+* **Before consent:** c15t renders a placeholder and does not mount the iframe.
+* **After consent:** the iframe mounts with its final embed URL.
+* **On revocation:** the `Frame` boundary unmounts the iframe, stopping the
+  embedded player and future requests from that document.
+* **Loading behavior:** c15t reserves the final player size, shows a localized
+  loading state, and uses native iframe lazy loading by default.
+* **Default layout:** the placeholder and player share a responsive 16:9,
+  borderless frame with a `200px` minimum height.
+* **Privacy-enhanced mode:** URLs built from `videoId` use
+  `youtube-nocookie.com` by default.
+
+Privacy-enhanced mode changes the YouTube host but does not replace consent
+gating. Keep the iframe behind the category required by your privacy policy.
+
+## Build the embed URL
+
+Prefer `videoId` when you control the video:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  params={{
+    autoplay: false,
+    controls: true,
+    playsinline: true,
+    rel: false,
+  }}
+  start={36}
+  title="Quarterly product update"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+Boolean `params` are serialized as YouTube's `1` and `0` values. `start` is
+serialized as the player's start time in seconds. If `params.start` is also
+present, the top-level `start` prop takes precedence.
+
+Set `privacyEnhanced={false}` only when you intentionally need the regular
+`youtube.com` host.
+
+### Migrate an existing iframe URL
+
+Use `src` when you already have a complete embed URL:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?start=36"
+  title="Quarterly product update"
+/>
+```
+
+When `src` is provided, c15t uses it unchanged. TypeScript treats `src` and
+`videoId` as mutually exclusive source modes: `start`, `params`, and
+`privacyEnhanced` are available only with `videoId`.
+
+## Style the wrapper and iframe
+
+`wrapperClassName` targets the consent-gated `Frame`. `className` and the
+forwarded ref target the iframe itself.
+
+The defaults are responsive and stable without utility classes. Override them
+only when your layout needs a different aspect ratio or height:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  frameProps={{ style: { aspectRatio: '4 / 3', minHeight: 280 } }}
+  style={{ borderRadius: 4 }}
+  title="Product overview"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+`frameProps.style` is merged after the wrapper defaults. The iframe fills that
+wrapper, has no border, and inherits the wrapper radius by default.
+
+## Customize the placeholder
+
+```tsx
+import { Frame, YouTubeEmbed } from '@c15t/react';
+
+<YouTubeEmbed
+  consentCategory="marketing"
+  placeholder={
+    <Frame.Root>
+      <Frame.Title>Allow marketing consent to watch this video.</Frame.Title>
+      <Frame.Button category="marketing" />
+    </Frame.Root>
+  }
+  title="Product overview"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+Custom placeholders should explain why the content is blocked and provide a
+clear way to change consent. Always give the iframe a meaningful `title`.
+
+Use `loadingFallback` to replace the post-consent loading message and
+`errorFallback` to replace the configuration error state. If neither `videoId`
+nor `src` is supplied at runtime, the component renders that error state instead
+of mounting an iframe.
+
+Standard cross-origin iframes do not provide a reliable player-error signal.
+`YouTubeEmbed` forwards the iframe's native `onError` when a browser emits it,
+but player-level errors require the YouTube IFrame Player API and are outside
+this iframe-only component.
+
+## Verify setup
+
+1. Clear saved consent and reload the page.
+2. Confirm there is no YouTube iframe or YouTube network request before consent.
+3. Grant the configured category and confirm exactly one iframe mounts.
+4. Confirm a `videoId` embed uses `youtube-nocookie.com` unless
+   `privacyEnhanced={false}`.
+5. Revoke consent and confirm the iframe is removed.
+6. Confirm the default 16:9 frame is borderless and reserves the same space at
+   mobile and desktop widths.
+
+See YouTube's [embedded player parameters](https://developers.google.com/youtube/player_parameters)
+for the supported query parameters.
+
+## Types
+
+### YouTubeEmbedProps
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`YouTubeEmbedProps\`|
+|Source Path|\`./packages/react/src/components/integrations/youtube-embed.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "YouTubeEmbedProps" from "./packages/react/src/components/integrations/youtube-embed.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/concepts/client-modes.md

@@ -0,0 +1,103 @@
+---
+title: Client Modes
+description: Reference page for client modes.
+group: reference
+---
+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
+
+> ⚠️ **Warning:**
+> 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.
+
+## 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.
+
+## 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.
+
+## 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/shared/concepts/consent-categories.md

@@ -0,0 +1,41 @@
+---
+title: Consent Categories
+description: Reference page for consent categories.
+group: reference
+---
+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.
+
+## 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).
+
+## 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.

package/docs/shared/concepts/consent-models.md

@@ -0,0 +1,72 @@
+---
+title: Consent Models
+description: Reference page for consent models.
+group: reference
+---
+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.
+
+## 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.

package/docs/shared/concepts/cookie-management.md

@@ -0,0 +1,88 @@
+---
+title: Cookie Management
+description: Reference page for cookie management.
+group: reference
+---
+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.
+
+> ⚠️ **Warning:**
+> 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)
+
+## 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/shared/concepts/glossary.md

@@ -0,0 +1,24 @@
+---
+title: Glossary
+description: Reference page for glossary.
+group: reference
+---
+### 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/shared/concepts/initialization-flow.md

@@ -0,0 +1,105 @@
+---
+title: Initialization Flow
+description: Reference page for initialization flow.
+group: reference
+---
+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. `onConsentSet` is the broad lifecycle signal; `onConsentChanged` and `subscribeToConsentChanges()` are the change-only signals for explicit post-init saves.
+
+|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|
+|Change-only integrations|Events|`onConsentChanged` or `subscribeToConsentChanges()`|`allowedCategories`, `deniedCategories`, and previous values only when a real save changed preferences|
+|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|