@c15t/react 3.0.0-alpha.2 → 3.0.0-alpha.4

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,17 @@
-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;
 }
 export declare const V3UIConfigContext: import("react").Context<V3UIConfigValue>;
 export declare const useUIConfig: () => V3UIConfigValue;

package/dist-types/ui-save.d.ts

@@ -1,5 +1,25 @@
 import type { ConsentKernel, SaveResult } from '@c15t/core';
 /** Explicit navigation supersedes a pending UI action, even to the same dialog. */
 export declare const invalidateConsentUIAction: (kernel: ConsentKernel) => void;
-/** Keep an open preferences dialog available until its own save succeeds. */
+/**
+ * Close the preferences dialog as soon as its choice is recorded locally.
+ *
+ * The kernel commits the receipt and updates permissions synchronously, so
+ * the dialog closes in the task that handled the click. Storage is written
+ * one task later, still ahead of the request, and the request runs after:
+ * its outcome never reopens the dialog, and a failed request stays queued
+ * for replay by the kernel. A save that recorded nothing (an unchanged
+ * selection) closes when it resolves successfully, unless explicit
+ * navigation or a newer action came first.
+ */
 export declare const saveConsentUI: (kernel: ConsentKernel, save: () => Promise<SaveResult>, canClose: () => boolean) => Promise<SaveResult>;
+/**
+ * Close an IAB surface in the task that handled the click.
+ *
+ * An IAB choice commits once its TC string is encoded, which can wait on the
+ * TCF library chunk but never on the backend. The surface closes first and
+ * comes back only when that local step recorded nothing (the vendor list
+ * failed to load, or the policy changed underneath), so the visitor can try
+ * again. A failed backend request never reopens it.
+ */
+export declare const saveIABConsentUI: (kernel: ConsentKernel, save: () => Promise<void> | void) => Promise<void>;

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

@@ -1,7 +1,9 @@
 import type { ComponentType } from 'react';
 /**
- * Share an on-demand module across exports and intent preloading. Ready client
+ * 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
  */

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.2";
+export declare const version = "3.0.0-alpha.4";

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,85 +23,107 @@ 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.
 - [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.
+- [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.
-- [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.
-- [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.
-- [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 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, 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.

package/docs/concepts/choose-your-setup.md

@@ -0,0 +1,87 @@
+---
+title: Choose your setup
+description: Pick the c15t setup for your framework, rendering mode and hosting,
+  and decide who runs the consent backend.
+group: concepts
+---
+
+## Find your app in this table
+
+Most apps need one row. Follow its guide from start to finish; each guide links
+to the alternatives it rules out.
+
+| Your app                                                                               | Setup                                                                                  | Guide                                                                                                                             |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js App Router with a Next.js server                                               | Server resolves consent from a cached manifest and streams it to the page              | [App Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                            |
+| Next.js App Router, banner must be in the first HTML                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
+| Next.js with static, ISR or `'use cache'` pages                                        | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
+| Next.js Pages Router                                                                   | Resolve consent in `getServerSideProps`                                                | [Pages Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                          |
+| Next.js with `output: 'export'`                                                        | Browser resolves consent                                                               | [Static export](https://c15t.com/docs/frameworks/next/static-export)                                                              |
+| TanStack Start with a server                                                           | Root loader resolves consent on the server                                             | [TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart)                                                      |
+| TanStack Start on a serverless host, banner may follow the page                        | Root loader streams consent                                                            | [TanStack Start rendering](https://c15t.com/docs/frameworks/tanstack-start/rendering#stream-the-page-while-consent-resolves)      |
+| TanStack Start in SPA mode or prerendered                                              | Browser resolves consent                                                               | [TanStack Start rendering](https://c15t.com/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts) |
+| React with Vite, or another single-page app                                            | Browser resolves consent                                                               | [React](../frameworks/react/quickstart.md)                                                                                        |
+| React Router framework mode, Remix, or another server-rendered React app               | Browser resolves consent after hydration                                               | [React rendering](../frameworks/react/rendering.md#react-router-remix-and-other-server-rendered-apps)                             |
+| Nuxt with a Nuxt server                                                                | Nuxt module resolves consent on the server from a cached manifest                      | [Nuxt](https://c15t.com/docs/frameworks/nuxt/quickstart)                                                                          |
+| Nuxt with prerendered or cached routes                                                 | Nuxt server for most pages, the browser on prerendered and cached routes               | [Nuxt prerendered and cached routes](https://c15t.com/docs/frameworks/nuxt/rendering#prerendered-and-cached-routes)               |
+| Nuxt with `nuxt generate` on static hosting                                            | Nuxt module, browser resolves consent from the manifest or `/init`                     | [Nuxt static hosting](https://c15t.com/docs/frameworks/nuxt/rendering#deploy-to-static-hosting)                                   |
+| Nuxt with `ssr: false`                                                                 | Nuxt module, browser resolves consent from the manifest                                | [Nuxt single-page app](https://c15t.com/docs/frameworks/nuxt/rendering#build-a-single-page-app-with-ssr-false)                    |
+| Vue with Vite                                                                          | Vue plugin, browser resolves consent                                                   | [Vue](https://c15t.com/docs/frameworks/vue/quickstart)                                                                            |
+| Vue rendered on the server without Nuxt                                                | Vue plugin; the banner mounts after hydration. Use Nuxt for the banner in server HTML. | [Vue rendering](https://c15t.com/docs/frameworks/vue/rendering#server-rendering-without-nuxt)                                     |
+| Astro with static output                                                               | Browser resolves consent through the hosted backend                                    | [Astro static output](https://c15t.com/docs/frameworks/astro/rendering#static-output-with-hosted)                                 |
+| Astro with server output and an adapter                                                | Middleware resolves consent from a cached manifest                                     | [Astro server output](https://c15t.com/docs/frameworks/astro/rendering#server-output-with-manifest)                               |
+| Svelte with Vite                                                                       | Svelte provider, browser resolves consent                                              | [Svelte](https://c15t.com/docs/frameworks/svelte/quickstart)                                                                      |
+| SvelteKit with a server                                                                | Root layout load resolves consent on the server                                        | [SvelteKit](https://c15t.com/docs/frameworks/sveltekit/quickstart)                                                                |
+| SvelteKit with `adapter-static`, prerendered pages or SPA mode                         | Browser resolves consent                                                               | [SvelteKit rendering](https://c15t.com/docs/frameworks/sveltekit/rendering#build-a-static-site)                                   |
+| Plain HTML, a CMS, a page builder, or a static site generator such as Hugo or Eleventy | One script tag, stock banner included                                                  | [HTML](https://c15t.com/docs/frameworks/html/quickstart)                                                                          |
+| JavaScript with a bundler and no UI framework                                          | `@c15t/browser` module, stock banner included                                          | [JavaScript](https://c15t.com/docs/frameworks/javascript/quickstart)                                                              |
+| Your own UI, or a framework without an adapter such as Solid                           | Headless runtime                                                                       | [JavaScript headless](https://c15t.com/docs/frameworks/javascript/headless)                                                       |
+
+Solid has no c15t adapter. Use the [headless runtime](https://c15t.com/docs/frameworks/javascript/headless#use-c15t-with-solid)
+and subscribe to it from your components.
+
+## Decide who runs the consent backend
+
+The backend supplies policies and stores consent records. Every setup above
+works with each option; only the URL changes.
+
+| Option                                                               | Use it when                                                                                                                                                    |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Inth](https://inth.com)                                             | You want hosted policies and consent records. The guides use this.                                                                                             |
+| [Self-hosted c15t backend](https://c15t.com/docs/self-host/overview) | You need to run the service and its database yourself.                                                                                                         |
+| Offline mode                                                         | Local development and tests. Policies live in your code and choices stay in the browser, with no consent records. Not recommended for production environments. |
+
+To use Inth, create a project, set its policy rules, add your site's origin to
+its trusted origins, and copy the backend URL. The guides use the placeholder
+`https://your-project.inth.app`; replace it with your project's backend URL,
+including any path prefix.
+
+## Server rendering or browser rendering
+
+Where consent resolves decides what the visitor's first HTML contains.
+
+| Rendering                                    | What the visitor gets                                                                                                                                                                   |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The server resolves consent for each request | The server reads the visitor's cookie and location headers, so the browser starts with the answer. Gated scripts can run right after hydration, and the banner can be part of the HTML. |
+| The browser resolves consent                 | The HTML is the same for everyone. After the page loads, the browser requests the policy, then shows the banner or runs gated scripts.                                                  |
+
+A static or prerendered page cannot contain one visitor's consent, because the
+same HTML goes to everyone. Static sites still use Inth; the browser talks to it
+directly. A same-origin `/api/c15t` route only works where a server runs it.
+
+Pages that are cached and shared between visitors, such as Next.js ISR or
+`'use cache'` routes, need browser resolution for the same reason. Cache the
+public policy manifest, never a response that contains a visitor's consent.
+
+## How the server gets the policy
+
+Server setups fetch policy one of two ways:
+
+* **Manifest**, used by the Next.js, Nuxt and Astro server guides.
+  Your server downloads the project's public policy file, caches it, and
+  resolves each visitor locally. Consent saves still go to the backend.
+* **`/init`**. Each visit asks the backend to resolve the visitor. Simpler, but
+  every page load makes a request to the backend.
+
+[Data fetching](./data-fetching.md) compares them in detail,
+including proxies and custom transports.

package/docs/{frameworks/react/concepts → concepts}/consent-categories.md

@@ -1,8 +1,8 @@
 ---
 title: Consent categories
-description: Assign optional features to categories and understand how policy
-  scope affects permission.
-group: frameworks
+description: Assign scripts, embeds and features to c15t consent categories, and
+  understand which categories the preference dialog shows.
+group: concepts
 ---
 
 ## Choose categories by purpose
@@ -27,8 +27,23 @@ Compound script and network conditions contribute every category they reference.
 Discovered categories are added to `consentCategories`, when supplied. The dialog
 always includes Necessary and offers the optional categories in that combined
 set that are also in the resolved policy scope. Choice completion uses the same
-set. If neither configuration nor integrations supply categories, the dialog
-uses the full policy scope.
+set.
+
+If neither configuration nor integrations supply categories, the result depends
+on the policy's `scopeMode`:
+
+* Under a permissive policy, the dialog lists only Necessary. The banner still
+  appears when the policy prompts for a choice. Accept All, Reject All and Save
+  each record that the visitor saw it, send a consent receipt for Necessary
+  alone in hosted and manifest modes, and keep the banner dismissed after
+  reload. The acknowledgement expires with the policy's choice validity and
+  after a policy change, like a choice would. A stored choice that is still
+  valid under the current policy also counts as an acknowledgement.
+* Under a strict policy, or an IAB TCF policy, the dialog uses the full policy
+  scope. TCF consent is given per purpose and recorded in the TC string.
+
+A category declared after that acknowledgement, such as a newly registered
+script or a discovered iframe, needs a choice, so the banner asks again.
 
 Categories discovered later are added immediately and retained until the provider
 or runtime is recreated. Adding a category can require a new choice; removing a
@@ -53,10 +68,17 @@ Analytics.
 Hidden optional categories do not need a choice to dismiss the banner. Their
 permissions still follow the backend policy, so hidden opt-in categories remain
 denied without a valid grant. React providers enable DOM iframe blocking and
-discovery by default; set `iframeBlocker: false` to disable it, or
+discovery by default. The blocker loads when the first iframe with
+`data-category` or `data-vendor` is on the page, so pages without one never
+download it; until it runs, such an iframe that arrives with a `src` consent
+does not allow is paused. Write gated iframes with `data-src`, not `src`. The
+browser requests a `src` as soon as the iframe is in the document, before the
+blocker can pause it, whether the iframe comes from the server HTML or a
+client render. Set
+`iframeBlocker: false` to disable it, or
 `iframeBlocker: { disableAutomaticBlocking: true }` to scan manually with
 `useIframeBlocker({ disableAutomaticBlocking: true }).processAllIframes()`.
 
 Use effective permissions to gate work and explicit choices to inspect what the
-visitor confirmed. Read [consent state](../../../guides/consent-state.md) for that
-distinction and [migration](../../../upgrade-v3.md) for v3 policy configuration.
+visitor confirmed. Read [how consent works](./how-consent-works.md#a-permission-is-not-a-recorded-choice) for that
+distinction and [migration](../upgrade-v3.md) for v3 policy configuration.