@c15t/react 3.0.0-alpha.3 → 3.0.0-alpha.5

package/dist-types/provider.d.ts

@@ -1,6 +1,7 @@
-import type { AllConsentNames, ClearOnRevocationConfig, ConsentPresentation, Callbacks, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
+import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentPresentation, ExperimentState, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
 import type { Script } from '@c15t/core/modules/script-loader';
-import type { ConsentControlOptions, ConsentRuntime } from '@c15t/core/runtime';
+import type { ConsentControlOptions } from '@c15t/core/runtime';
+import type { ConsentRuntime, ResolveStreamedInit } from '@c15t/core/runtime/provider';
 import type { ReactNode } from 'react';
 import type { DialogPreload } from './chunk-warming.js';
 import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from './module-hooks.js';
@@ -8,12 +9,23 @@ import type { UseIframeBlockerOptions } from './module-hooks/iframe-blocker.js';
 import type { ReactUIOptions } from './types/manager.js';
 import type { ReactComponentSlots } from './types/slots.js';
 /** Events emitted by the mounted provider without snapshot-derived consent aliases. */
-export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onPermissionsChanged' | 'onError' | 'onBeforeConsentRevocationReload'>;
-/** Prepared policy and records; legacy consent projections are not provider inputs. */
-export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'>;
+export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onPermissionsChanged' | 'onSurfaceShown' | 'onError' | 'onBeforeConsentRevocationReload'>;
+/**
+ * Prepared policy and records; legacy consent projections are not provider
+ * inputs. An `experiment` a server helper resolved runs instead of
+ * `options.experiment`.
+ */
+export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState;
 export interface ConsentProviderOptions extends ConsentControlOptions, Pick<ReactUIOptions, 'colorScheme' | 'disableAnimation' | 'noStyle' | 'scrollLock' | 'theme' | 'trapFocus'> {
     enabled?: boolean;
     presentation?: ConsentPresentation;
+    /**
+     * A/B experiment on prompt/preferences presentation. The assigned arm is
+     * merged over `presentation`, exposed through `useExperiment()`, and
+     * recorded with every impression and choice. Initial-only: remount the
+     * provider to change the experiment.
+     */
+    experiment?: ConsentExperiment;
     /**
      * Content Security Policy nonce applied to DOM nodes c15t injects.
      *
@@ -45,6 +57,12 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * ```
      */
     mode: ProviderTransportFactory;
+    /**
+     * Where the visitor's choice is stored. Read once, like `persistence`:
+     * the stored records and the data clearing that protects them stay at
+     * the location the provider mounted with. Outside production, a change
+     * logs a warning; remount the provider to move storage.
+     */
     storageConfig?: StorageConfig;
     user?: User | KernelUser;
     overrides?: KernelOverrides;
@@ -112,6 +130,10 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * is paused.
      */
     iframeBlocker?: UseIframeBlockerOptions | false;
+    /**
+     * Store the visitor's choice in a cookie and localStorage. On by default.
+     * Read once, when the provider mounts; see `storageConfig`.
+     */
     persistence?: boolean | UsePersistenceOptions;
     i18n?: Partial<I18nConfig>;
     /** Categories to offer alongside discovered integration categories, within policy scope. */
@@ -139,6 +161,16 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * @internal
      */
     __debugPkg?: string;
+    /**
+     * The code that applies a `prefetch` promise, from
+     * `@c15t/core/runtime/streamed-init`. Without it the provider loads that
+     * code once `prefetch` is a promise, so an app that never streams one
+     * doesn't download it. A framework root whose state is usually streamed
+     * (`ConsentRoot`) passes it, so the state applies as soon as it arrives
+     * instead of after one more request. Read once, at mount.
+     * @internal
+     */
+    __resolveStreamedInit?: ResolveStreamedInit;
 }
 /**
  * Options accepted when an external runtime supplies the kernel.
@@ -147,13 +179,19 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
  * Everything the component tree still owns — theme, slots, legal links —
  * is unchanged.
  */
-export type ExternalRuntimeProviderOptions = Omit<ConsentProviderOptions, 'mode' | 'vendors'> & {
+export type ExternalRuntimeProviderOptions = Omit<ConsentProviderOptions, 'callbacks' | 'mode' | 'vendors'> & {
     mode?: ConsentProviderOptions['mode'];
     /**
      * Not accepted here: the runtime owner declares vendors through
      * `createConsentRuntime({ vendors })`, and the kernel carries them.
      */
     vendors?: never;
+    /**
+     * Not accepted here: the runtime owner passes callbacks to
+     * `createConsentRuntime({ callbacks })`, and the runtime runs them.
+     * Passing them anyway logs a warning in development.
+     */
+    callbacks?: never;
 };
 /** The provider builds and owns its own kernel. */
 export interface OwnedRuntimeProviderProps {
@@ -170,19 +208,21 @@ export type ConsentProviderProps = OwnedRuntimeProviderProps | ExternalRuntimePr
 /**
  * v3 ConsentProvider.
  *
- * Retains the enabled kernel while disabled mode uses a separate permissive
- * kernel, so toggling enabled preserves recorded choices. Provides the active
- * kernel via context and wires the curated v2-like options surface to v3
- * modules. It does not mirror the
- * snapshot into React state; selector hooks still subscribe directly to
- * the kernel through `useSyncExternalStore`.
+ * Builds one consent runtime (`createConsentProviderRuntime`) per mounted
+ * provider and renders its kernel: the kernel goes into context, and
+ * selector hooks subscribe to it through `useSyncExternalStore`. New
+ * options reach the runtime through `update()`, which applies only what
+ * changed; `mode`, `i18n`, `experiment`, `prefetch`, `persistence`,
+ * `storageConfig` and `clearOnRevocation` are read once. While `enabled` is
+ * `false` the runtime renders a separate permissive kernel, so toggling it
+ * keeps the visitor's records.
  *
  * Pass `runtime` to render a runtime someone else created. The provider
- * then borrows its kernel and mounts none of the side-effecting modules —
- * no second `init()`, no second persistence handle, no second `window.c15t`
- * — and does not dispose it on unmount. Handing it a different runtime
- * switches the tree to that runtime's kernel; switching between a borrowed
- * runtime and a provider-built kernel still needs a remount.
+ * then borrows its kernel and starts nothing — no second `init()`, no
+ * second persistence handle, no second `window.c15t` — and does not
+ * dispose it on unmount. Handing it a different runtime switches the tree
+ * to that runtime's kernel; switching between a borrowed runtime and a
+ * provider-built one still needs a remount.
  *
  * @example
  * ```tsx

package/dist-types/server/headers.d.ts

@@ -1,5 +1,10 @@
-declare const FORWARDED_HEADERS: readonly ["x-c15t-country", "cf-ipcountry", "x-vercel-ip-country", "x-amz-cf-ipcountry", "x-country-code", "x-country", "x-c15t-region", "cf-region-code", "x-vercel-ip-country-region", "x-region-code", "accept-language", "x-c15t-gpc", "sec-gpc", "x-c15t-version", "user-agent", "x-forwarded-host", "x-forwarded-for", "purpose", "sec-purpose", "next-router-prefetch", "x-middleware-prefetch"];
-type ForwardedHeader = (typeof FORWARDED_HEADERS)[number];
+declare const FORWARDED_HEADERS: readonly ["x-c15t-country", "cf-ipcountry", "x-vercel-ip-country", "x-amz-cf-ipcountry", "x-country-code", "x-country", "x-c15t-region", "cf-region-code", "x-vercel-ip-country-region", "x-region-code", "accept-language", "x-c15t-gpc", "sec-gpc", "x-c15t-version", "user-agent", "x-forwarded-for", "purpose", "sec-purpose", "next-router-prefetch", "x-middleware-prefetch"];
+/**
+ * Forwarding headers a client can set to name a host or scheme. Passed to
+ * the backend only when the app trusts them.
+ */
+export declare const CLIENT_FORWARDING_HEADERS: readonly ['forwarded', 'x-forwarded-host', 'x-forwarded-proto'];
+type ForwardedHeader = (typeof FORWARDED_HEADERS)[number] | (typeof CLIENT_FORWARDING_HEADERS)[number];
 type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
 /**
  * Extracts relevant headers for consent management from the request headers.
@@ -12,10 +17,13 @@ type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
  * The extracted headers include:
  * - Country headers (cf-ipcountry, x-vercel-ip-country, etc.)
  * - Region headers (x-vercel-ip-country-region, x-region-code)
- * - Standard headers (accept-language, user-agent, x-forwarded-*)
+ * - Standard headers (accept-language, user-agent, x-forwarded-for)
  * - Prefetch headers (purpose, sec-purpose, next-router-prefetch, x-middleware-prefetch)
  *
  * @param headersList - The Headers object from the incoming request
+ * @param options - `trustForwardedHeaders` also copies `forwarded`,
+ * `x-forwarded-host` and `x-forwarded-proto`, which any client can send.
+ * Leave it off unless a proxy you control sets them and drops incoming ones.
  * @returns An object containing the relevant headers for consent management
  *
  * @example
@@ -28,5 +36,7 @@ type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
  *
  * @public
  */
-export declare const extractRelevantHeaders: (headersList: Headers) => RelevantHeaders;
+export declare const extractRelevantHeaders: (headersList: Headers, options?: {
+    trustForwardedHeaders?: boolean;
+}) => RelevantHeaders;
 export {};

package/dist-types/server/normalize-url.d.ts

@@ -21,16 +21,21 @@ export declare const validateBackendURL: (backendURL: string) => {
     normalizedURL: string;
 };
 /**
- * Normalizes a backend URL, resolving relative URLs using request headers.
+ * Normalizes a backend URL, resolving relative URLs against the request.
  *
  * @remarks
  * For absolute URLs, returns the URL as-is (with trailing slash trimmed).
- * For relative URLs, attempts to construct the full URL using:
- * 1. x-forwarded-proto + x-forwarded-host/host headers
- * 2. Referer header as fallback
+ * A relative URL resolves against the `host` header: over `https` for a
+ * domain name, and over `http` for `localhost`, an IP address or a
+ * single-label host. `x-forwarded-host`, `x-forwarded-proto` and `forwarded`
+ * are read only when `trustForwardedHeaders` is set, because any client can
+ * send them; the `referer` header is never used.
  *
  * @param backendURL - The backend URL (absolute or relative)
  * @param headersList - The Headers object from the incoming request
+ * @param options - `trustForwardedHeaders`: resolve against the request's
+ * forwarding headers. Set it only behind a proxy that sets them and drops
+ * incoming ones.
  * @returns The normalized absolute URL, or null if it cannot be determined
  *
  * @example
@@ -41,11 +46,13 @@ export declare const validateBackendURL: (backendURL: string) => {
  * normalizeBackendURL('https://api.example.com/', headers);
  * // Returns: 'https://api.example.com'
  *
- * // Relative URL - resolved from headers
+ * // Relative URL - resolved from the host header
  * normalizeBackendURL('/api/consent', headers);
- * // Returns: 'https://example.com/api/consent' (based on headers)
+ * // Returns: 'https://example.com/api/consent' (for `host: example.com`)
  * ```
  *
  * @public
  */
-export declare const normalizeBackendURL: (backendURL: string, headersList: Headers) => string | null;
+export declare const normalizeBackendURL: (backendURL: string, headersList: Headers, options?: {
+    trustForwardedHeaders?: boolean;
+}) => string | null;

package/dist-types/server/types.d.ts

@@ -12,9 +12,20 @@ import type { Overrides, SSRInitialData } from '@c15t/core';
 export interface FetchSSRDataOptionsBase {
     /**
      * The backend URL to fetch consent data from.
-     * Can be absolute (https://...) or relative (/api/consent).
+     * Can be absolute (https://...) or relative (/api/consent). A relative
+     * URL resolves against the request's `host` header.
      */
     backendURL: string;
+    /**
+     * Resolve a relative `backendURL` against the request's `forwarded`,
+     * `x-forwarded-host` and `x-forwarded-proto` headers instead of `host`.
+     * Any client can send those headers, so set this only behind a proxy
+     * that sets them and drops incoming ones. Also forwards those three
+     * headers to the backend, which is skipped otherwise.
+     *
+     * @default false
+     */
+    trustForwardedHeaders?: boolean;
     /**
      * Optional overrides for geo-location.
      */

package/dist-types/transports/offline.d.ts

@@ -1,18 +1,9 @@
-import type { ProviderTransportFactory } from '@c15t/core';
-import type { PolicyRule } from '@c15t/schema/types';
-/** Policy rules evaluated locally when initialization runs. */
-export interface OfflineModeOptions {
-    /**
-     * Rules to resolve locally. Omit them to use `recommendedPolicyRules()`:
-     * strict opt-in for Europe, the UK, Quebec and unknown locations, opt-out
-     * for the US states with a privacy law, and `none` everywhere else.
-     * Passing rules replaces that pack entirely.
-     */
-    policyRules?: PolicyRule[];
-}
 /**
- * Resolve local rules outside render and hydration.
- * @param options - Explicit policy rules; absence resolves the recommended pack.
- * @returns A provider transport with no network requests.
+ * Offline mode for the React provider: core's `offline()`, which resolves
+ * policy rules locally and switches copy when `overrides.language` or
+ * `useSetLanguage()` names a language the bundle or `i18n.messages` has.
+ * The language a server prefetch detected from `Accept-Language` keeps the
+ * startup copy.
  */
-export declare const offline: (options?: OfflineModeOptions) => ProviderTransportFactory;
+export { offline } from '@c15t/core';
+export type { OfflineModeOptions } from '@c15t/core';

package/dist-types/ui-config-context.d.ts

@@ -1,9 +1,15 @@
-import type { LegalLinks, ConsentPresentation } from '@c15t/core';
+import type { ConsentExperiment, ConsentPresentation, LegalLinks } from '@c15t/core';
 import type { DialogPreload } from './chunk-warming.js';
 import type { ReactComponentSlots } from './types/slots.js';
+import type { Theme } from './types/theme/index.js';
 export interface V3UIConfigValue {
     components?: ReactComponentSlots;
+    /** The host's base presentation, before any experiment arm is applied. */
     presentation?: ConsentPresentation;
+    /** The configured experiment; the assigned arm lives on the snapshot. */
+    experiment?: ConsentExperiment;
+    /** The host's base theme, before any experiment arm is applied. */
+    theme?: Theme;
     legalLinks?: LegalLinks;
     preloadDialog?: DialogPreload;
 }

package/dist-types/utils/merge-slot-props.d.ts

@@ -10,5 +10,19 @@ export declare const getSlotProps: (components: ReactComponentSlots | undefined,
 export type MergedSlotProps = Omit<ReactSlotProps, 'style'> & {
     style?: CSSPropertiesWithVars;
 };
-export declare const mergeSlotProps: (slotProps: ReactSlotProps | undefined, { baseClassName, className, noStyle, style, ...ownProps }: MergeSlotPropsInput) => MergedSlotProps;
+/**
+ * A `components` part, plus the `noStyle` flag a `theme.slots` entry puts
+ * on it through `applyThemeSlots`.
+ */
+type SlotPropsInput = ReactSlotProps & {
+    noStyle?: boolean;
+};
+/**
+ * Merge a `components` part with a component's own props.
+ *
+ * The stock `baseClassName` is dropped when the component's `noStyle` or
+ * the part's `noStyle` is set; the part's and the component's classes
+ * stay, as `resolveStyles` keeps theme slot classes under `noStyle`.
+ */
+export declare const mergeSlotProps: (slotProps: SlotPropsInput | undefined, { baseClassName, className, noStyle, style, ...ownProps }: MergeSlotPropsInput) => MergedSlotProps;
 export {};

package/dist-types/utils/theme-utils.d.ts

@@ -3,6 +3,7 @@
  * Handles token-to-CSS variable conversion and dark mode overrides.
  */
 import type { ThemeCSSVariables } from '@c15t/ui/theme';
+import { generateThemeCSS as baseGenerateThemeCSS } from '@c15t/ui/theme';
 import type { Theme } from '../types/theme/style-types.js';
 /**
  * Default design tokens for the v2 theme system.
@@ -13,6 +14,20 @@ export declare const defaultTheme: Required<Omit<Theme, 'slots'>>;
  */
 export declare const themeToVars: (theme: Theme, isDark?: boolean) => ThemeCSSVariables;
 /**
- * Generates a CSS string for the theme variables.
+ * Generates a CSS string for the theme variables, the same CSS as
+ * `generateThemeCSS` from `@c15t/ui/theme`.
+ *
+ * @param theme - Theme tokens to serialize.
+ * @param colorScheme - `'dark'` makes the dark tokens the default,
+ * `'system'` follows `prefers-color-scheme`, and `'light'` adds the stock
+ * dark palette under the dark classes. Omit it, or pass `null`, to write
+ * only the theme's own tokens.
+ * @returns Theme CSS for a `<style>` element or a stylesheet.
+ * @example
+ * ```ts
+ * import { generateThemeCSS } from '@c15t/react/utils';
+ *
+ * const css = generateThemeCSS({ dark: { primary: '#7fd1a8' } }, 'system');
+ * ```
  */
-export declare const generateThemeCSS: (theme: Theme) => string;
+export declare const generateThemeCSS: (theme: Theme, colorScheme?: Parameters<typeof baseGenerateThemeCSS>[1]) => string;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.3";
+export declare const version = "3.0.0-alpha.5";

package/docs/README.md

@@ -6,14 +6,16 @@ These docs ship inside the package so coding agents can read them offline. Open
 
 ## Using these docs
 
-These docs describe v3. Start with Inth hosted setup, identify the framework, router and deployment, then read its quickstart. Static sites can use Inth directly. Use page Markdown and package-bundled docs for targeted context. Verify scripts, rejection, reload and preferences; banner visibility alone is insufficient.
+These docs describe c15t v3. Find your app's row in Choose your setup, then follow that framework guide from start to finish; it names the files to create and the backend URL to use. Install c15t packages with the @alpha dist-tag, because npm latest is still v2. A visible banner does not prove anything: check that vendor requests wait for consent, that rejection survives a reload, and that preferences can be reopened.
 
 ## Start here
 
 - [React quickstart](./frameworks/react/quickstart.md)
-- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
-- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
-- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
+- [Choose your setup](./concepts/choose-your-setup.md): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
+- [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
+- [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
+- [Verify consent](./guides/verify-consent.md): Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.
+- [Migrate to v3](./upgrade-v3.md): Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React providers, the JavaScript runtime, custom UI built on useConsentManager, callbacks, policies, stored consent and a self-hosted backend.
 
 ## More documentation
 
@@ -21,90 +23,108 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 
 ## Frameworks
 
-- [ConsentBanner](./frameworks/react/components/consent-banner.md): Pre-built consent banner shown when consent is required.
+- [Callbacks](./frameworks/react/callbacks.md): Run code in a React app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, with the ConsentProvider callbacks option.
+- [Clear on revocation](./frameworks/react/clear-on-revocation.md): Delete the first-party cookies and Web Storage keys a consent category owns in a React app when that category is denied, with the clearOnRevocation option on ConsentProvider.
+- [Components](./frameworks/react/components.md): Every c15t component a React app imports from c15t/react, what each renders, where each one mounts, and which to start with.
+- [ConsentBanner](./frameworks/react/components/consent-banner.md): Render the c15t consent banner in a React app, choose its variant and position, and compose its parts.
 - [ConsentDialog](./frameworks/react/components/consent-dialog.md): Open the c15t preference center as a modal ConsentDialog in a React app, wire its triggers and control blocking, focus and policy gating.
 - [ConsentDialogLink](./frameworks/react/components/consent-dialog-link.md): Add a ConsentDialogLink to a React footer so visitors reopen the c15t preference center from your own text link, with asChild and rights data.
-- [ConsentDialogTrigger](./frameworks/react/components/consent-dialog-trigger.md): Floating button and toolbar that reopen the preference center after the first prompt.
+- [ConsentDialogTrigger](./frameworks/react/components/consent-dialog-trigger.md): Add the c15t ConsentDialogTrigger floating button or toolbar inside a React ConsentProvider so visitors can reopen the preference center after the first prompt.
 - [ConsentGate](./frameworks/react/components/consent-gate.md): Gate a YouTube or map iframe behind consent with ConsentGate in React, showing a placeholder that opens the preference center until the category is allowed.
-- [ConsentProvider](./frameworks/react/components/consent-manager-provider.md): Configure the v3 consent runtime and share its state with child components.
+- [ConsentProvider](./frameworks/react/components/consent-provider.md): Mount ConsentProvider in a React app and configure its backend, scripts, storage, blocking and presentation options.
 - [ConsentWidget](./frameworks/react/components/consent-widget.md): Embed the c15t preference center inline with ConsentWidget on a React privacy page, with draft toggles that record a choice only on Save.
-- [DevTools](./frameworks/react/components/dev-tools.md): A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
-- [Consent categories](./frameworks/react/concepts/consent-categories.md): Assign optional features to categories and understand how policy scope affects permission.
-- [Policy presets](./frameworks/react/concepts/policy-presets.md): Understand how policy rules affect React prompts, permissions and persistent privacy controls.
+- [DevTools](./frameworks/react/components/dev-tools.md): Inspect consent state, location, loaded scripts and consent events in a React app during development with the c15t DevTools panel.
+- [Compose your own banner](./frameworks/react/compose.md): Build a React consent banner from the ConsentBanner parts in c15t/react, with your own markup and buttons, while the policy still decides which actions appear.
+- [Content Security Policy](./frameworks/react/content-security-policy.md): Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.
+- [Customize](./frameworks/react/customize.md): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with the stylesheet, theme tokens, provider options and slots.
+- [Embeds](./frameworks/react/embeds.md): Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.
+- [IAB GPP](./frameworks/react/gpp.md): Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
 - [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
-- [Hooks](./frameworks/react/hooks/overview.md): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
-- [IAB TCF](./frameworks/react/iab/overview.md): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
-- [Block network requests](./frameworks/react/network-blocker.md): Block fetch and XHR calls to third-party domains in a React app until the visitor grants their consent category.
-- [Quickstart](./frameworks/react/quickstart.md): Connect a React application to Inth and add consent UI, persistence and a preferences link.
-- [Load scripts with consent](./frameworks/react/script-loader.md): Register vendor scripts once and let effective permissions control loading.
-- [Styling](./frameworks/react/styling/overview.md): Import the React stylesheet and theme c15t components with tokens, slots, and class names on ConsentProvider.
-- [Troubleshoot React consent](./frameworks/react/troubleshooting.md): Diagnose policy resolution, early scripts, storage and rendering problems.
+- [Hooks](./frameworks/react/hooks.md): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
+- [IAB TCF](./frameworks/react/iab.md): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
+- [Network blocker](./frameworks/react/network-blocker.md): Hold fetch and XMLHttpRequest calls in a React app until their consent category is allowed, with networkBlocker rules in the ConsentProvider options.
+- [Quickstart](./frameworks/react/quickstart.md): Add a consent banner, preferences dialog and consent-gated scripts to a React single-page app built with Vite, using Inth as the consent backend.
+- [Rendering and deployment](./frameworks/react/rendering.md): How c15t resolves consent in client-rendered React apps, React Router framework mode, Remix and other server-rendered React apps without a c15t adapter.
+- [Scripts](./frameworks/react/scripts.md): Load vendor scripts by consent category in a React app with ConsentProvider, and clear stored data or reload the page when a visitor withdraws consent.
+- [Translations](./frameworks/react/translations.md): Where c15t banner and dialog copy comes from in a React app, how the browser picks the visitor's language, and how to override copy and switch languages with the provider's i18n option and hooks.
+- [Troubleshooting](./frameworks/react/troubleshooting.md): Fix a missing banner, early vendor requests, unstyled components and theme warnings in a React app that uses c15t/react.
+- [Vendor consent](./frameworks/react/vendor-consent.md): Let visitors allow a category such as marketing in a React app and still turn off one vendor in it, with the vendors option on ConsentProvider and useVendorAllowed.
+
+## Concepts
+
+- [Choose your setup](./concepts/choose-your-setup.md): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
+- [Consent categories](./concepts/consent-categories.md): Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.
+- [Consent state reference](./concepts/consent-state.md): How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.
+- [Data fetching](./concepts/data-fetching.md): How c15t gets policy data through a cached manifest, backend /init, the browser or offline rules, and where consent choices are saved.
+- [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
+- [Policies](./concepts/policies.md): How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.
 
 ## Guides
 
-- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
-- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
-- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
-- [Share consent controls across frameworks](./guides/shared-consent-controls.md): Use the same c15t script lifecycle, external consent source, and event controls in every framework.
-- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
-- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+- [Banner experiments](./guides/banner-experiments.md): Run A/B tests on consent banner presentation with any feature-flag provider or built-in weighted assignment, and attribute every impression and choice to its arm.
+- [Troubleshooting](./guides/troubleshooting.md): Fix a missing banner, analytics that load before consent, choices lost on reload, CORS errors, hydration differences and failed static builds in c15t v3.
+- [Verify consent](./guides/verify-consent.md): Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.
 
 ## Customization
 
-- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
-- [Banner styling recipes](./customization/recipes.md): See real v3 components and reuse the exact theme configuration behind the examples.
-- [Style component slots](./customization/slots.md): Target a specific c15t component part without replacing its markup or behavior.
-- [Theme tokens and CSS](./customization/tokens.md): Style c15t with semantic tokens and use the stylesheet that matches your CSS tooling.
+- [Class names and CSS-in-JS](./customization/class-names.md): Style c15t's component parts with CSS Modules, vanilla-extract, StyleX, Emotion or plain class names, and see which approach works in each framework.
+- [Dark mode](./customization/dark-mode.md): Switch c15t's banner and dialog to dark colors with colorScheme, set your own dark tokens, follow your site's theme switch, and paint dark on the first frame in every framework.
+- [Motion and animation](./customization/motion.md): Change how fast c15t's banner and dialog animate with duration and easing tokens, turn animations off per surface with disableAnimation, and check reduced-motion behavior in each framework.
+- [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
+- [Banner designs](./customization/recipes.md): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
+- [Component parts](./customization/slots.md): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
+- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see when the dialog's CSS loads, order c15t's cascade layer against your own, and run c15t without its styles.
+- [Tailwind CSS](./customization/tailwind.md): Load c15t's styles next to Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
+- [Theme tokens](./customization/tokens.md): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
 - [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 
 ## Integrations
 
-- [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
-- [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
-- [Clear on revocation](./integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
-- [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
-- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Synchronize c15t permissions with Zaraz purposes while Cloudflare manages your tools.
-- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
-- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
-- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Front Chat](./integrations/front-chat.md): Load the Front Chat widget with functionality permission, forward CSP nonces and clear the session on revocation.
-- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
-- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
-- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
-- [Granular consent](./integrations/granular-consent.md): Let visitors grant a category and still turn one vendor off, without adopting IAB TCF.
-- [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
-- [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
-- [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
-- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
-- [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
-- [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
-- [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
-- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
-- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
-- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
-- [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker with measurement permission, forward its settings and verify loading and revocation.
-- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
-- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
-- [Pinterest Tag](./integrations/pinterest-tag.md): Configure the Pinterest Tag with c15t v3, track typed events and verify marketing permission, revocation and reload.
-- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
-- [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
-- [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
-- [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [Adobe Analytics](./integrations/adobe-analytics.md): Load an Adobe Data Collection Tags property only after measurement consent with the c15t adobeAnalytics helper, and check its extensions in DevTools.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Load Ahrefs Web Analytics only after measurement consent with the c15t ahrefsAnalytics helper, and check it in DevTools.
+- [Amplitude](./integrations/amplitude.md): Load the Amplitude Browser SDK 2 only after measurement consent with the c15t amplitude helper, which opts the SDK out on revocation and back in on a new grant.
+- [Custom integrations](./integrations/building-integrations.md): Gate a vendor that has no @c15t/integrations helper, or sync consent with an SDK your app already loads, using a c15t script configuration.
+- [Clearbit](./integrations/clearbit.md): Load the Clearbit enrichment tag only after marketing consent with the c15t clearbit helper, and check it in DevTools.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Load the Cloudflare Web Analytics beacon only after measurement consent with the c15t cloudflareWebAnalytics helper, and check it in DevTools.
+- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Sync c15t permissions to Cloudflare Zaraz purposes with the c15t cloudflareZaraz bridge, which runs on every page without loading a script, and check the tools it controls.
+- [Crisp](./integrations/crisp.md): Load the Crisp chat widget only after functionality consent with the c15t crisp helper, pass its runtime settings and check it in DevTools.
+- [Databuddy](./integrations/databuddy.md): Load the Databuddy SDK on every page with the c15t databuddy helper, switch its disabled flag and config from measurement consent, and check both in DevTools.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Load Fathom Analytics only after measurement consent with the c15t fathomAnalytics helper, set its SPA mode, and check it in DevTools.
+- [Front Chat](./integrations/front-chat.md): Load the Front Chat widget only after functionality consent with the c15t frontChat helper, forward CSP nonces, clear the session on revocation and check it in DevTools.
+- [Google Maps](./integrations/google-maps.md): Gate a Google Maps iframe embed with c15t v3 so the map loads only after the visitor allows its consent category, in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.
+- [Google Tag](./integrations/google-tag.md): Load gtag.js for Google Analytics or Google Ads with c15t Consent Mode v2 signals, and verify the consent commands in DevTools.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Load a Google Tag Manager container with c15t Consent Mode v2 signals, configure consent checks inside the container, and verify both in DevTools.
+- [Heap](./integrations/heap.md): Load the Heap config script and heap.js only after measurement consent with the c15t heap helper, and check it in DevTools.
+- [Hightouch](./integrations/hightouch.md): Load the Hightouch Events browser SDK only after measurement consent with the c15t hightouch helper, and check page events in DevTools.
+- [Hotjar](./integrations/hotjar.md): Load Hotjar only after measurement consent with the c15t hotjar helper, and check its loader and recordings in DevTools.
+- [Intercom](./integrations/intercom.md): Load the Intercom messenger only after functionality consent with the c15t intercom helper, set its region and check it in DevTools.
+- [Klaviyo](./integrations/klaviyo.md): Load Klaviyo signup forms and onsite tracking only after marketing and measurement consent with the c15t klaviyo helper, gate your own events, and check it in DevTools.
+- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Load the LinkedIn Insight Tag only after marketing consent with the c15t linkedinInsights helper, guard lintrk conversion calls, and check it in DevTools.
+- [LogRocket](./integrations/logrocket.md): Load LogRocket session replay only after measurement consent with the c15t logRocket helper, including proxied setups, and check it in DevTools.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo after measurement consent with the c15t matomoAnalytics helper, or use Matomo's own consent mode, and check each mode in DevTools.
+- [Meta Pixel](./integrations/meta-pixel.md): Load the Meta Pixel only after marketing consent with the c15t metaPixel helper, guard fbq event calls, and check it in DevTools.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Load Microsoft Clarity only after measurement consent with the c15t clarity helper, send Consent V2 storage signals and check them in DevTools.
+- [Microsoft UET](./integrations/microsoft-uet.md): Load Microsoft Advertising UET on every page with the c15t microsoftUet helper, send ad_storage consent defaults and updates, and verify both in DevTools.
+- [Mixpanel](./integrations/mixpanel-analytics.md): Load the Mixpanel SDK on every page with the c15t mixpanelAnalytics helper, which switches Mixpanel tracking on and off with measurement consent, and check it in DevTools.
+- [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker only after measurement consent with the c15t oneDollarStats helper, forward its data-attribute settings, and check it in DevTools.
+- [OpenAI Pixel](./integrations/openai-pixel.md): Load the ChatGPT Ads Measurement Pixel only after marketing consent with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in DevTools.
+- [Integrations](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, email and SMS, chat and embedded content.
+- [Pinterest Tag](./integrations/pinterest-tag.md): Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.
+- [Pirsch](./integrations/pirsch.md): Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
+- [PostHog](./integrations/posthog.md): Load PostHog before or after measurement consent with the c15t posthog helper, choose its cookieless behavior, turn off PostHog modules you do not use, and sync consent with an SDK you already initialize.
+- [Promptwatch](./integrations/promptwatch.md): Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Load the Reddit Pixel only after marketing consent with the c15t redditPixel helper, guard rdt conversion calls, and check it in DevTools.
+- [RudderStack](./integrations/rudderstack.md): Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.
+- [Segment](./integrations/segment.md): Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.
+- [Umami Analytics](./integrations/umami-analytics.md): Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Load the Vercel Web Analytics script only after measurement consent with the c15t vercelAnalytics helper, choose the debug script, and check it in DevTools.
+- [X Pixel](./integrations/x-pixel.md): Load the X Pixel only after marketing consent with the c15t xPixel helper, guard twq conversion events, and check it in DevTools.
 - [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
 
 ## Reference
 
-- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
+- [Migrate to v3](./upgrade-v3.md): Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React providers, the JavaScript runtime, custom UI built on useConsentManager, callbacks, policies, stored consent and a self-hosted backend.