@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

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/theme-provider.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
-import type { ThemeContextValue } from './context/theme-context';
-import type { V3UIConfigValue } from './ui-config-context';
+import type { ThemeContextValue } from './context/theme-context.js';
+import type { V3UIConfigValue } from './ui-config-context.js';
 interface V3ThemeProviderProps {
     themeConfig: ThemeContextValue;
     uiConfig: V3UIConfigValue;

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

@@ -0,0 +1,36 @@
+import type { HostedModeFactory, HostedModeOptions } from '@c15t/core';
+/** Options for {@link hosted}. `backendURL` defaults to the build's. */
+export type HostedOptions = Omit<HostedModeOptions, 'backendURL'> & {
+    /**
+     * Backend URL, relative (`/api/c15t`) or absolute. Defaults to the URL
+     * `consentManifest()` from `c15t/build` read from
+     * `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`.
+     */
+    backendURL?: string;
+};
+/**
+ * Build a hosted factory, taking the backend URL from the build when the
+ * options name none.
+ *
+ * @param options - The page's options.
+ * @param buildBackendURL - The backend URL the build read, if any.
+ * @returns A hosted transport factory.
+ * @throws {Error} When neither names a backend URL.
+ * @internal
+ */
+export declare const hostedWithBuild: (options: HostedOptions, buildBackendURL: string | undefined) => HostedModeFactory;
+/**
+ * Ask the backend's `/init` for every visitor's policy.
+ *
+ * @param options - Backend URL, init headers and request overrides.
+ * @returns A transport factory for the provider's `mode`, carrying its
+ * options.
+ * @throws {Error} When no backend URL is passed and the build set none.
+ * @example
+ * ```tsx
+ * import { ConsentProvider, hosted } from 'c15t/react';
+ *
+ * <ConsentProvider options={{ mode: hosted() }}>{children}</ConsentProvider>;
+ * ```
+ */
+export declare const hosted: (options?: HostedOptions) => HostedModeFactory;

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

@@ -0,0 +1,48 @@
+import type { BrowserManifestModeFactory, BrowserManifestOptions } from '@c15t/core/transports/manifest-browser';
+/**
+ * Manifest mode for the React provider: core's browser resolver, with the
+ * policy and backend URL the build integration downloaded as defaults.
+ */
+import type { ConsentManifest } from '@c15t/schema/types';
+/** What a build integration downloaded, as `@c15t/core/generated` exports it. */
+export interface BuildOutput {
+    backendURL?: string;
+    snapshot?: ConsentManifest;
+}
+/**
+ * Fill the options the page left out from the build: the backend URL that
+ * saves go to, and the snapshot unless the page passed one, a
+ * `manifestURL`, or `source: 'runtime'`.
+ *
+ * @param options - The page's options.
+ * @param build - What the build downloaded.
+ * @returns The options `manifest()` resolves with.
+ * @internal
+ */
+export declare const withBuildDefaults: (options: BrowserManifestOptions, build: BuildOutput) => BrowserManifestOptions;
+/**
+ * Resolve the policy in the browser from the backend's consent manifest.
+ *
+ * Without options it uses what `consentManifest()` from `c15t/build`
+ * downloaded: the snapshot and the backend URL from
+ * `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`, both served as
+ * `c15t/generated`. Without a
+ * snapshot, such as in dev after a failed fetch, it fetches
+ * `${backendURL}/manifest` at runtime. Saves go to the backend either way.
+ * With `manifestURL` or `source: 'runtime'`, also pass `source: 'runtime'`
+ * to `consentManifest()`, so the build downloads no snapshot.
+ *
+ * @param options - Overrides: your own `snapshot`, `source: 'runtime'`, a
+ * `manifestURL`, a `backendURL`, or the visitor's location as `inputs`.
+ * @returns A transport factory for the provider's `mode`, carrying its
+ * options.
+ * @throws {Error} When no snapshot, manifest URL or backend URL is known.
+ * @example
+ * ```tsx
+ * import { ConsentProvider, manifest } from 'c15t/react';
+ *
+ * <ConsentProvider options={{ mode: manifest() }}>{children}</ConsentProvider>;
+ * ```
+ */
+export declare const manifest: (options?: BrowserManifestOptions) => BrowserManifestModeFactory;
+export type { BrowserManifestModeFactory, BrowserManifestOptions as ManifestModeOptions, } from '@c15t/core/transports/manifest-browser';

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/types/index.d.ts

@@ -1,3 +1,3 @@
-export * from './manager';
-export * from './slots';
-export * from './theme';
+export * from './manager.js';
+export * from './slots.js';
+export * from './theme/index.js';

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

@@ -1,5 +1,5 @@
 import type { UIOptions } from '@c15t/ui/theme';
-import type { ReactComponentSlots } from './slots';
+import type { ReactComponentSlots } from './slots.js';
 /**
  * React-specific UI configuration options.
  *

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

@@ -1 +1 @@
-export * from './style-types';
+export * from './style-types.js';

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

@@ -1,9 +1,21 @@
-import type { LegalLinks, ConsentPresentation } from '@c15t/core';
-import type { ReactComponentSlots } from './types/slots';
+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;
+    /** CSP nonce for the `<style>` elements the surfaces render. */
+    nonce?: string;
+    /** `false` when the app loads `styles.css` itself. */
+    styles?: boolean;
 }
 export declare const V3UIConfigContext: import("react").Context<V3UIConfigValue>;
 export declare const useUIConfig: () => V3UIConfigValue;

package/dist-types/utils/deferred-module.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react';
+/**
+ * Share an on-demand module across exports and preloading. Ready client
+ * retries run synchronously; Suspense retains server rendering and hydration.
+ * A failed import is cached for rendered exports only, so a failed preload
+ * does not stop a later open from retrying.
+ *
+ * @internal
+ */
+export declare const createDeferredModule: <ModuleType>(importModule: () => Promise<ModuleType>) => {
+    component<Props extends object>(select: (module: ModuleType) => ComponentType<Props>): ComponentType<Props>;
+    preload(): Promise<void>;
+};

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

@@ -1,4 +1,4 @@
-export * from './cn';
-export * from './default-translation-config';
-export * from './merge-styles';
-export * from './theme-utils';
+export * from './cn.js';
+export * from './default-translation-config.js';
+export * from './merge-styles.js';
+export * from './theme-utils.js';

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

@@ -1,7 +1,7 @@
 import type { ConsentComponentSlotKey } from '@c15t/schema/config';
 import type { ClassValue } from '@c15t/ui/utils';
-import type { ReactComponentSlots, ReactSlotProps } from '../types/slots';
-import type { CSSPropertiesWithVars } from '../types/theme';
+import type { ReactComponentSlots, ReactSlotProps } from '../types/slots.js';
+import type { CSSPropertiesWithVars } from '../types/theme/index.js';
 type MergeSlotPropsInput = ReactSlotProps & {
     baseClassName?: ClassValue;
     noStyle?: boolean;
@@ -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/merge-styles.d.ts

@@ -1,4 +1,4 @@
-import type { ClassNameStyle, ThemeValue } from '../types/theme';
+import type { ClassNameStyle, ThemeValue } from '../types/theme/index.js';
 /**
  * Merges two styles objects, handling theme values and style properties.
  * This React version uses React-specific types but uses the core logic from @c15t/ui.

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

@@ -3,7 +3,8 @@
  * Handles token-to-CSS variable conversion and dark mode overrides.
  */
 import type { ThemeCSSVariables } from '@c15t/ui/theme';
-import type { Theme } from '../types/theme/style-types';
+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.1";
+export declare const version = "3.0.0-alpha.11";

package/docs/README.md

@@ -6,98 +6,125 @@ 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.
+- [Upgrade a React app from v2](./frameworks/react/upgrade-v3.md): Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers packages, ConsentProvider and transports, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.
 
 ## More documentation
 
-[Documentation index](https://c15t.com/docs/llms.txt) · [Full Markdown context](https://c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
+[Documentation index](https://v3.c15t.com/docs/llms.txt) · [Full Markdown context](https://v3.c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
 
 ## 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.
-- [ConsentProvider](./frameworks/react/components/consent-manager-provider.md): Configure the v3 consent runtime and share its state with child components.
+- [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-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.
-- [Frame](./frameworks/react/components/frame.md): Gate a YouTube or map iframe behind consent with Frame in React, showing a placeholder that opens the preference center until the category is allowed.
-- [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 theme tokens, provider options and slots, and load the stylesheet yourself when you need to.
+- [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/use-consent-manager/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.
-- [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.
+- [Upgrade from v2](./frameworks/react/upgrade-v3.md): Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers packages, ConsentProvider and transports, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.
+- [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): Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or offline rules, and understand 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.
+- [Consent modes](./concepts/modes.md): Reference for manifest(), hosted() and offline() in every c15t framework package, where each one resolves the visitor's policy, what it adds to first-load JavaScript, the build-time manifest fetch and its failure policy, and the backend URL variable each framework reads.
+- [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.
-- [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, failed manifest downloads, mode errors 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): See how c15t delivers its styles in each framework without a render-blocking stylesheet, when to import styles.css yourself with styles false, which file holds the dialog's rules, and how c15t's cascade layer meets your own.
+- [Tailwind CSS](./customization/tailwind.md): Use c15t's styles with 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.
-- [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.
-- [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.
-- [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.
-- [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.
-- [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 before or after consent 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 before or after consent 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.
+- [Sentry](./integrations/sentry.md): Configure Sentry's CDN or your own SDK with consent for error monitoring, Session Replay and user data.
+- [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.
+- [Vercel Speed Insights](./integrations/vercel-speed-insights.md): Load the Vercel Speed Insights collector only after measurement consent with the c15t vercelSpeedInsights helper, drop Web Vitals reports on revocation, 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.