@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

package/dist-types/server.d.ts

@@ -0,0 +1,164 @@
+import { createManifestTransport } from '@c15t/core/transports/manifest';
+import type { ConsentConfig } from './config';
+import type { ConsentState } from './types';
+type Awaitable<Value> = Promise<Value> | Value;
+/**
+ * Request context the server helpers read from.
+ *
+ * The default implementation calls `next/headers`, which only exists in the
+ * App Router. Pass your own when the request arrives another way, such as
+ * `getServerSideProps` in the Pages Router (see `@c15t/nextjs/pages`, which
+ * builds this adapter for you) or a test harness.
+ *
+ * @example
+ * ```ts
+ * const state = await resolveConsent({
+ * 	request: {
+ * 		cookies: () => ({ toString: () => req.headers.cookie ?? '' }),
+ * 		headers: () => new Headers({ host: req.headers.host ?? '' }),
+ * 	},
+ * });
+ * ```
+ */
+export interface NextRequestContext {
+    /**
+     * Returns the request cookies. Only `toString()` is read; it must
+     * serialize to a `Cookie` header value (`a=1; b=2`).
+     */
+    cookies: () => Awaitable<{
+        toString: () => string;
+    }>;
+    /**
+     * Returns the request headers as a Web `Headers` instance.
+     */
+    headers: () => Awaitable<Headers>;
+}
+/**
+ * How the request is read: the clock, the consent cookie, header
+ * overrides, and the adapter that exposes the request itself.
+ */
+export interface ConsentRequestOptions {
+    /** Request clock reused for record validation and hydration. */
+    now?: number;
+    /**
+     * Cookie name holding persisted consent. Defaults to `c15t`, the
+     * persistence module's storage key. Set this only if you customized
+     * `storageConfig.storageKey` client-side; it must match.
+     */
+    cookieName?: string;
+    /**
+     * If provided, override the auto-detected country from request headers.
+     * Mainly useful for tests.
+     */
+    country?: string;
+    /**
+     * If provided, override the auto-detected language.
+     */
+    language?: string;
+    /**
+     * Request context adapter. Defaults to `next/headers`, so set this
+     * wherever that module is unavailable: the Pages Router, custom
+     * servers, or tests. `@c15t/nextjs/pages` derives it from the Node
+     * request for you.
+     */
+    request?: NextRequestContext;
+}
+/**
+ * Type alias re-exported so consumers can stay within `@c15t/nextjs`.
+ */
+export type { KernelConfig } from '@c15t/core';
+export type { ConsentState } from './types';
+export type { ConsentConfig } from './config';
+export { defineConsentConfig } from './config';
+export interface ResolveConsentOptions extends ConsentRequestOptions {
+    /**
+     * Backend base URL. When set (here or through `config`), the helper
+     * calls `${backendURL}/init` server-side and folds the response into the
+     * returned state (policy, UI, translations, IAB metadata, and consents
+     * if the backend knows the user). This avoids a first-paint flicker
+     * before the client-side init lands.
+     *
+     * Relative URLs are resolved via the request headers (`x-forwarded-proto`,
+     * `host`) so the backend call works under any reverse-proxy.
+     *
+     * Without a backend URL the helper returns the cookie- and header-only
+     * state and performs no network call. Overrides `config.backendURL`.
+     */
+    backendURL?: string;
+    /**
+     * A `defineConsentConfig` result. Supplies `backendURL` and `manifestURL`
+     * defaults; the explicit fields on this options bag win.
+     */
+    config?: ConsentConfig;
+    /**
+     * Same-origin or absolute `GET /manifest` URL. When set, the helper
+     * resolves init locally from the cached manifest and does not call
+     * `/init`. Overrides `config.manifestURL`.
+     */
+    manifestURL?: string;
+    /**
+     * Inline manifest for hosts that already loaded it. Takes precedence over
+     * `manifestURL` and keeps the request path backend-free.
+     */
+    manifest?: Parameters<typeof createManifestTransport>[0]['manifest'];
+    /**
+     * Override fetch. Useful for testing or for wiring Vercel's
+     * unstable_cache / Next.js `fetch`-level caching around the call.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Forward additional request headers onto the backend call. Cookies,
+     * `x-forwarded-for`, and `user-agent` from the incoming request are
+     * forwarded automatically (see {@link DEFAULT_FORWARD_HEADERS}). Use this for
+     * authentication tokens or custom tracing headers.
+     */
+    forwardHeaders?: string[];
+    /**
+     * Called when the backend or manifest request fails. The helper still
+     * returns the request-only state so the page renders and the client
+     * retries on mount. When omitted, the failure is logged with
+     * `console.warn` outside production so it does not go unnoticed.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Request headers forwarded to the backend on every server-side `/init`.
+ *
+ * The backend geolocates from the client IP when no CDN geo header is
+ * present, and records the user agent with the consent decision, so both
+ * have to travel with a server-initiated call the way they do with a
+ * browser-initiated one. `forwardHeaders` adds to this list.
+ */
+export declare const DEFAULT_FORWARD_HEADERS: readonly ['x-forwarded-for', 'user-agent'];
+/**
+ * Resolve the visitor's consent state for the current request.
+ *
+ * 1. Reads the consent cookie, geo headers, language, and GPC from the
+ *    request.
+ * 2. With a backend URL (`backendURL` or `config.backendURL`), calls
+ *    `${backendURL}/init` server-side with the request context, or resolves
+ *    init from the cached manifest when `manifest` or `manifestURL` is set.
+ * 3. Folds the response into a `ConsentState` so first paint is correct
+ *    without waiting for a client roundtrip.
+ *
+ * Without a backend URL, step 2 is skipped and the request-only state is
+ * returned with no network call. If the backend call fails, the request-only
+ * state is returned too, so the page still renders and `ConsentRoot` retries
+ * on mount. The failure reaches `onError` when provided, and is otherwise
+ * logged outside production.
+ *
+ * Each call reads fresh headers and never caches across requests, so
+ * concurrent requests stay isolated.
+ *
+ * @param options - Backend URL or a `defineConsentConfig` result, the
+ * manifest source, fetch overrides, and how to read the request
+ * @returns The visitor's JSON-serializable state for `ConsentRoot`
+ * @example
+ * ```ts
+ * import { resolveConsent } from '@c15t/nextjs/server';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * const state = await resolveConsent({ config: consentConfig });
+ * ```
+ */
+export declare const resolveConsent: (options?: ResolveConsentOptions) => Promise<ConsentState>;

package/dist-types/static.d.ts

@@ -0,0 +1,42 @@
+import type { ConsentManifest, InitOutput, ResolveInitFromManifestInputs } from '@c15t/schema/types';
+export type { ConsentManifest } from '@c15t/schema/types';
+export interface StaticManifestModuleOptions {
+    manifestURL: string;
+    fetch?: typeof globalThis.fetch;
+    exportName?: string;
+    /** Package entry that supplies the generated ConsentManifest type. */
+    importSource?: string;
+}
+export interface StaticGeoResult {
+    country?: string | null;
+    countryCode?: string | null;
+    region?: string | null;
+    regionCode?: string | null;
+}
+export interface StaticConsentResolverOptions {
+    manifest: ConsentManifest;
+    geo?: StaticGeoResult | null;
+    geoURL?: string;
+    language?: string;
+    gpc?: boolean;
+    fetch?: typeof globalThis.fetch;
+}
+export interface StaticConsentResolution {
+    /**
+     * Synchronous policy outcome for first paint. Unknown geography never
+     * rewrites a configured matcher.
+     */
+    initial: InitOutput;
+    /**
+     * Resolves to the geo-specific result when `geo` or `geoURL` is available.
+     * Falls back to `initial` when geo cannot be resolved.
+     */
+    resolved: Promise<InitOutput>;
+}
+/** Resolve unknown geography without rewriting configured policy matchers. */
+export declare const resolveStrictestDefaultInit: (manifest: ConsentManifest, inputs?: Omit<ResolveInitFromManifestInputs, 'country' | 'region'>) => InitOutput;
+export declare const createStaticConsentResolver: (options: StaticConsentResolverOptions) => StaticConsentResolution;
+/** Fetches the manifest used by static builds. */
+export declare const loadStaticManifest: (options: Omit<StaticManifestModuleOptions, 'exportName'>) => Promise<ConsentManifest>;
+/** Generates a typed manifest module for a static build. */
+export declare const createStaticManifestModule: (options: StaticManifestModuleOptions) => Promise<string>;

package/dist-types/types.d.ts

@@ -1,38 +1,7 @@
-import type { ConsentManagerProviderProps } from '@c15t/react';
-import type { FetchSSRDataOptionsBase } from '@c15t/react/server';
-import type { PrefetchOptions } from 'c15t';
-export type InitialDataPromise = NonNullable<ConsentManagerProviderProps['options']['store']>['ssrData'];
-export interface NextCacheOptions {
-    /**
-     * Cache lifetime in seconds for the Next.js data cache.
-     * Set to false to disable Next.js caching for this call.
-     *
-     * @default 1
-     */
-    revalidateSeconds?: number | false;
-}
-export interface C15tPrefetchProps extends PrefetchOptions {
-    /**
-     * Optional script element ID.
-     *
-     * @default 'c15t-initial-data-prefetch'
-     */
-    id?: string;
-}
+import type { ConsentProviderPrefetch } from '@c15t/react/provider';
 /**
- * Options for the fetchInitialData function.
- *
- * @remarks
- * Uses the base options from @c15t/react/server - headers are
- * resolved automatically from Next.js.
+ * The visitor's resolved consent state: serializable policy, records, and
+ * request clock. Produced server-side by `resolveConsent()` and consumed by
+ * `ConsentRoot`, which hands it to the React provider.
  */
-export interface FetchInitialDataOptions extends FetchSSRDataOptionsBase {
-    /**
-     * Optional Next.js cache controls for SSR init requests.
-     */
-    nextCache?: NextCacheOptions;
-}
-export interface ConsentManagerProps {
-    children: React.ReactNode;
-    ssrData?: InitialDataPromise;
-}
+export type ConsentState = ConsentProviderPrefetch;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.2.1";
+export declare const version = "3.0.0-alpha.0";

package/docs/README.md

@@ -1,155 +1,115 @@
 # @c15t/nextjs
 
-> Next.js consent management docs for c15t, including App Router setup, consent UI, SSR behavior, script loading, and integrations.
+> Next.js v3 App Router, Pages Router, static export and hydration with Inth.
 
 These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
 
+## 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.
+
+## Start here
+
+- [Next.js quickstart](./frameworks/next/quickstart.md)
+- [App Router setup](./frameworks/next/app-router.md)
+- [Pages Router setup](./frameworks/next/pages-router.md)
+- [Static export setup](./frameworks/next/static-export.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.
+
+## 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.
+
 ## Frameworks
 
-Install and configure c15t in JavaScript, React, and Next.js applications.
-
-- [Building Headless Components](./frameworks/next/building-headless-components.md): Build policy-aware custom consent components in Next.js using the headless hooks and policy-pack tooling.
-- [Callbacks](./frameworks/next/callbacks.md): React to consent lifecycle events - initialization, consent changes, errors, and revocation reloads.
-- [ConsentBanner](./frameworks/next/components/consent-banner.md): A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
-- [ConsentDialog](./frameworks/next/components/consent-dialog.md): A modal dialog where users can toggle individual consent categories.
-- [ConsentDialogLink](./frameworks/next/components/consent-dialog-link.md): An inline trigger for opening the consent dialog from footers, legal pages, and account settings.
-- [ConsentDialogTrigger](./frameworks/next/components/consent-dialog-trigger.md): A floating, draggable button that lets users re-open the consent dialog at any time.
-- [ConsentManagerProvider](./frameworks/next/components/consent-manager-provider.md): The root provider component that initializes the consent system and makes consent state available to all child components.
-- [ConsentWidget](./frameworks/next/components/consent-widget.md): An inline consent management widget for embedding in settings or privacy pages. Shows category toggles with accordion layout.
-- [DevTools](./frameworks/next/components/dev-tools.md): A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
-- [Frame](./frameworks/next/components/frame.md): A consent-gated content wrapper - children only mount when the required consent category is granted.
-- [Client Modes](./frameworks/next/concepts/client-modes.md): Choose how c15t connects to its backend - full hosted integration, offline-only, or bring your own backend.
-- [Consent Categories](./frameworks/next/concepts/consent-categories.md): How c15t organizes tracking technologies into five consent categories.
-- [Consent Models](./frameworks/next/concepts/consent-models.md): How c15t determines consent behavior based on legal jurisdiction.
-- [Cookie Management](./frameworks/next/concepts/cookie-management.md): How c15t manages cookies through script, iframe, and network gating
-- [Glossary](./frameworks/next/concepts/glossary.md): Key terms used throughout the c15t documentation.
-- [Initialization Flow](./frameworks/next/concepts/initialization-flow.md): What happens from provider mount to first render — the full consent lifecycle.
-- [Policy Packs](./frameworks/next/concepts/policy-packs.md): How c15t resolves regional consent policies and what a policy pack controls.
-- [Headless Mode](./frameworks/next/headless.md): Build fully custom consent UI using only hooks - no pre-built components required.
-- [useColorScheme](./frameworks/next/hooks/use-color-scheme.md): Manage light/dark mode preferences for consent components.
-- [Checking Consent](./frameworks/next/hooks/use-consent-manager/checking-consent.md): Use has() for flexible consent checks with AND, OR, and NOT logic. Check if any consent exists with hasConsented().
-- [Location Info](./frameworks/next/hooks/use-consent-manager/location-info.md): Access detected jurisdiction, country, and region. Override geolocation for testing.
-- [useConsentManager](./frameworks/next/hooks/use-consent-manager/overview.md): The primary hook for accessing consent state and actions. Returns the full consent store including all state properties and action methods.
-- [Setting Consent](./frameworks/next/hooks/use-consent-manager/setting-consent.md): Save, update, and reset consent preferences with setConsent(), setSelectedConsent(), and saveConsents().
-- [useDraggable](./frameworks/next/hooks/use-draggable.md): Make an element draggable between viewport corners with snapping, persistence, and animation support.
-- [useFocusTrap](./frameworks/next/hooks/use-focus-trap.md): Trap keyboard focus within a container for accessible modal dialogs.
-- [useReducedMotion](./frameworks/next/hooks/use-reduced-motion.md): Detect the user's prefers-reduced-motion OS setting and reactively disable animations.
-- [useSSRStatus](./frameworks/next/hooks/use-ssr-status.md): Check whether server-side rendered consent data was used during initialization.
-- [useTextDirection](./frameworks/next/hooks/use-text-direction.md): Manage RTL/LTR text direction based on the active language for consent UI.
-- [useTranslations](./frameworks/next/hooks/use-translations.md): Access the current language's translations for building custom consent UI.
-- [IABConsentBanner](./frameworks/next/iab/consent-banner.md): An IAB TCF 2.3 compliant consent banner that displays partner count, purpose summaries, and legitimate interest notices.
-- [IABConsentDialog](./frameworks/next/iab/consent-dialog.md): An IAB TCF 2.3 compliant preference center with tabbed purpose and vendor management.
-- [IAB TCF 2.3](./frameworks/next/iab/overview.md): Implement IAB Transparency & Consent Framework 2.3 compliance for programmatic advertising in EU/EEA jurisdictions.
-- [useGVLData (Internal)](./frameworks/next/iab/use-gvl-data.md): Status note for the internal GVL hook used by the built-in IAB dialog.
-- [Iframe Blocking](./frameworks/next/iframe-blocking.md): Block embedded content (YouTube, social widgets, maps) until users grant consent for the appropriate category.
-- [Internationalization](./frameworks/next/internationalization.md): Translate consent UI into 30+ languages with built-in translations, custom overrides, and automatic browser language detection.
-- [Network Blocker](./frameworks/next/network-blocker.md): Block outgoing network requests to third-party domains until the user grants consent for the appropriate category.
-- [Optimization](./frameworks/next/optimization.md): Improve c15t startup performance in Next.js with same-origin rewrites, static prefetching, and dynamic-route SSR.
-- [Policy Packs](./frameworks/next/policy-packs.md): Configure regional consent policies in Next.js — hosted mode, presets, and offline fallback.
-- [Quickstart](./frameworks/next/quickstart.md): Add consent management to your Next.js app in under 5 minutes.
-- [Script Loader](./frameworks/next/script-loader.md): Gate third-party scripts behind consent in Next.js — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
-- [Server-Side Data Fetching](./frameworks/next/server-side.md): Pre-fetch consent data in Server Components with fetchInitialData for dynamic Next.js routes.
-- [Class Names](./frameworks/next/styling/classnames.md): Style consent components using className props and per-slot className targeting via the theme.
-- [Color Scheme](./frameworks/next/styling/color-scheme.md): Support light mode, dark mode, and system preference detection in consent components.
-- [CSS Variables](./frameworks/next/styling/css-variables.md): Reference for all --c15t-* CSS custom properties generated by the theme system.
-- [Styling Overview](./frameworks/next/styling/overview.md): Five approaches for theming consent components — design tokens, component slots, CSS variables, className, and noStyle mode.
-- [Component Slots](./frameworks/next/styling/slots.md): Target individual component parts with styles using the slot system - className strings or inline style objects.
-- [Tailwind CSS](./frameworks/next/styling/tailwind.md): Use Tailwind CSS utility classes to style consent components via the slot system.
-- [Design Tokens](./frameworks/next/styling/tokens.md): The six base token categories that control colors, typography, spacing, radius, shadows, and motion, plus optional dark-mode overrides.
-- [Troubleshooting](./frameworks/next/troubleshooting.md): Solutions for common issues with @c15t/nextjs — provider errors, missing banners, consent persistence, and more.
+- [Fetching reference](./frameworks/next/api-reference/data-fetching.md): Reference for Next.js consent URLs, manifest resolution, request geography and offline configuration.
+- [App Router](./frameworks/next/app-router.md): Set up App Router with Inth, cached manifests and consent-gated scripts.
+- [Client-side initialization](./frameworks/next/client-side.md): Initialize Next.js consent in the browser with one backend URL, without server prefetch or local API handlers.
+- [ConsentBanner](./frameworks/next/components/consent-banner.md): Render the pre-built ConsentBanner inside a Next.js ConsentRoot and configure its variants, per-policy buttons and compound parts.
+- [ConsentDialog](./frameworks/next/components/consent-dialog.md): Mount ConsentDialog as a Client Component inside a Next.js ConsentRoot to open the preference center from the banner, links and triggers.
+- [ConsentDialogLink](./frameworks/next/components/consent-dialog-link.md): Open the preference center from a Next.js footer with ConsentDialogLink, a Client Component that renders an unstyled button inside ConsentRoot.
+- [ConsentDialogTrigger](./frameworks/next/components/consent-dialog-trigger.md): Add the floating ConsentDialogTrigger button or toolbar to a Next.js ConsentRoot so visitors can reopen the preference center.
+- [ConsentRoot](./frameworks/next/components/consent-manager-provider.md): Pass server-resolved consent state and shared configuration to the Next.js ConsentRoot.
+- [ConsentWidget](./frameworks/next/components/consent-widget.md): Render ConsentWidget on a Next.js privacy page inside ConsentRoot as an inline preference center, server-rendered when the route resolves consent.
+- [DevTools](./frameworks/next/components/dev-tools.md): Load the c15t DevTools panel only in Next.js development builds to inspect consent state, scripts, policy and events inside ConsentRoot.
+- [Frame](./frameworks/next/components/frame.md): Consent-gate an iframe in Next.js with Frame inside ConsentRoot; with server prefetch the placeholder or embed is decided in the server HTML.
+- [Consent categories](./frameworks/next/concepts/consent-categories.md): Assign optional features to categories and understand how policy scope affects permission.
+- [Policy presets](./frameworks/next/concepts/policy-presets.md): Understand how policy rules affect Next.js prompts, permissions and persistent privacy controls.
+- [Content Security Policy](./frameworks/next/content-security-policy.md): Pass a per-request CSP nonce to ConsentRoot in Next.js and allow the consent backend in connect-src.
+- [Data fetching](./frameworks/next/data-fetching.md): Choose cached manifests for a Next.js server, backend initialization for a simpler setup, or offline mode for local development.
+- [Forward geography headers](./frameworks/next/geography-headers.md): Use c15tProxy in Next.js proxy.ts or middleware.ts so Server Components and Route Handlers receive the visitor's country and region.
+- [Headless](./frameworks/next/headless.md): Build a custom consent banner in Next.js with the c15t/next/headless hooks inside your existing ConsentRoot.
+- [Hooks](./frameworks/next/hooks/use-consent-manager/overview.md): Gate features and save consent choices in Next.js Client Components with the focused hooks exported from c15t/next.
+- [IAB TCF](./frameworks/next/iab/overview.md): Mount the IAB TCF banner and dialog inside a Next.js ConsentRoot and configure the CMP ID, policy and vendor data.
+- [Optimization](./frameworks/next/optimization.md): Reuse cached policy data and optionally reduce browser connection overhead without changing consent behavior.
+- [Pages Router](./frameworks/next/pages-router.md): Set up Pages Router with Inth, cached manifests and consent-gated scripts.
+- [Quickstart](./frameworks/next/quickstart.md): Add c15t consent management to Next.js with Inth, with setup guides for the App Router, the Pages Router and static export.
+- [Load scripts with consent](./frameworks/next/script-loader.md): Register vendor scripts in your existing Next.js ConsentRoot and handle loading and revocation.
+- [Server rendering and hydration](./frameworks/next/server-side.md): Resolve consent on the server, choose what waits for the result, and preserve the same state through hydration.
+- [Static export](./frameworks/next/static-export.md): Add c15t to output export without request helpers or a local API server.
+- [Styling](./frameworks/next/styling/overview.md): Import the Next.js stylesheet and theme c15t components with tokens, slots, and class names through ConsentRoot options.
+- [Troubleshoot Next.js consent](./frameworks/next/troubleshooting.md): Diagnose failed Next.js prefetch, verify manifest requests, and fix consent rendering or persistence problems.
+
+## 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.
+
+## 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.
+- [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 
 ## Integrations
 
-Connect analytics, advertising, maps, media, and other third-party tools behind consent.
-
-- [Adobe Analytics](./integrations/adobe-analytics.md): Adobe Analytics loaded through an Adobe Experience Platform Data Collection Tags embed URL.
-- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
-- [Amplitude](./integrations/amplitude.md): Load Amplitude Browser SDK 2 with c15t and gate product analytics behind measurement consent.
-- [Build a Custom Script Integration](./integrations/building-integrations.md): Learn when to use a raw Script, when to build a reusable manifest-backed integration, and how to debug and test custom consent-aware scripts in c15t.
-- [Clearbit](./integrations/clearbit.md): Visitor and company enrichment loaded with Clearbit's account-keyed tags.js snippet.
-- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Cookieless analytics from Cloudflare with a prebuilt helper that serializes the beacon config into the `data-cf-beacon` attribute.
-- [Crisp](./integrations/crisp.md): Load Crisp live chat with website ID, runtime, cookie, and session options.
-- [Databuddy](./integrations/databuddy.md): Databuddy is a privacy-focused analytics platform that helps you understand user behavior and track events. It supports cookieless tracking and manages consent automatically through c15t's consent state synchronization.
-- [Fathom Analytics](./integrations/fathom-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that maps Fathom's data attributes into a c15t-managed script.
-- [Google Maps](./integrations/google-maps.md): Render Google Maps only after consent with one shared Maps JavaScript API loader and independently managed map instances.
-- [GA4 + Google Ads (gtag.js)](./integrations/google-tag.md): Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
-- [Google Tag Manager](./integrations/google-tag-manager.md): Deploy and manage marketing tags centrally with automatic consent state synchronization.
-- [Heap](./integrations/heap.md): Load Heap with c15t and gate autocapture product analytics behind measurement consent.
-- [Hightouch](./integrations/hightouch.md): Load Hightouch Events with c15t and gate the browser SDK behind measurement consent.
-- [Hotjar](./integrations/hotjar.md): Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
-- [Intercom](./integrations/intercom.md): Bootstrap Intercom settings and load the messenger widget bundle.
-- [LinkedIn Insights](./integrations/linkedin-insights.md): Track conversions and build matched audiences for LinkedIn advertising campaigns.
-- [LogRocket](./integrations/logrocket.md): Session replay and monitoring loaded after measurement consent with LogRocket's browser SDK.
-- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
-- [Meta Pixel](./integrations/meta-pixel.md): Track conversions and build audiences for Facebook and Instagram advertising campaigns.
-- [Microsoft Clarity](./integrations/microsoft-clarity.md): Session replay and behavior analytics with a prebuilt helper that keeps Clarity consent synchronized with c15t measurement state.
-- [Microsoft UET](./integrations/microsoft-uet.md): Track conversions and measure performance for Microsoft Advertising and Bing Ads.
-- [Mixpanel Analytics](./integrations/mixpanel-analytics.md): Load Mixpanel with c15t and let Mixpanel's own opt-in and opt-out APIs follow measurement consent.
-- [Integrations](./integrations/overview.md): Load analytics, pixels, tag managers, and widgets through c15t so consent state controls when they run, update, and appear in your consent UI.
-- [Pirsch](./integrations/pirsch.md): Privacy-friendly, cookieless analytics loaded with Pirsch's fixed script id and identification-code attributes.
-- [Plausible Analytics](./integrations/plausible-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that preserves Plausible's queue bootstrap and loader attributes.
-- [PostHog](./integrations/posthog.md): PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
-- [Promptwatch](./integrations/promptwatch.md): Promptwatch analyzes traffic on your site for Artificial Intelligence (AI) traffic and usage insights. Data is stored in the EU without user-identifiable information.
-- [Reddit Pixel](./integrations/reddit-pixel.md): Track conversions and build retargeting audiences for Reddit advertising campaigns.
-- [RudderStack](./integrations/rudderstack.md): Load RudderStack's JavaScript SDK with c15t and gate the browser SDK behind measurement consent.
-- [Rybbit Analytics](./integrations/rybbit-analytics.md): Privacy-friendly analytics with script-tag configuration via Rybbit's data attributes.
-- [Segment](./integrations/segment.md): Load Segment Analytics.js with c15t and gate it behind measurement consent.
-- [Snapchat Pixel](./integrations/snapchat-pixel.md): Measure Snapchat ad performance and build remarketing audiences with a prebuilt pixel helper.
-- [TikTok Pixel](./integrations/tiktok-pixel.md): Measure ad performance and build audiences for TikTok advertising campaigns.
-- [Umami Analytics](./integrations/umami-analytics.md): Open-source, cookieless analytics with a prebuilt helper that maps Umami's data attributes into a c15t-managed script.
-- [Vercel Analytics](./integrations/vercel-analytics.md): Bootstrap Vercel Analytics with a declarative queue and script attributes.
-- [X Pixel (Twitter Pixel)](./integrations/x-pixel.md): Track conversions and build audiences for advertising campaigns on X (formerly Twitter).
-- [YouTube](./integrations/youtube.md): Keep YouTube iframes unmounted until consent with a privacy-enhanced, lazy-loaded React or Next.js embed.
+- [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.
+- [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.
+- [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
 
 ## Reference
 
-Concepts, legal templates, open-source policies, and contributor documentation.
-
-- [Client Modes](./shared/concepts/client-modes.md): Reference page for client modes.
-- [Consent Categories](./shared/concepts/consent-categories.md): Reference page for consent categories.
-- [Consent Models](./shared/concepts/consent-models.md): Reference page for consent models.
-- [Cookie Management](./shared/concepts/cookie-management.md): Reference page for cookie management.
-- [Glossary](./shared/concepts/glossary.md): Reference page for glossary.
-- [Initialization Flow](./shared/concepts/initialization-flow.md): Reference page for initialization flow.
-- [Policy Packs](./shared/concepts/policy-packs.md): Reference page for policy packs.
-- [Consent Banner](./shared/react/components/consent-banner.md): Reference page for consent banner.
-- [Consent Dialog](./shared/react/components/consent-dialog.md): Reference page for consent dialog.
-- [Consent Dialog Link](./shared/react/components/consent-dialog-link.md): Reference page for consent dialog link.
-- [Consent Dialog Trigger](./shared/react/components/consent-dialog-trigger.md): Reference page for consent dialog trigger.
-- [Consent Manager Provider](./shared/react/components/consent-manager-provider.md): Reference page for consent manager provider.
-- [Consent Widget](./shared/react/components/consent-widget.md): Reference page for consent widget.
-- [Dev Tools](./shared/react/components/dev-tools.md): Reference page for dev tools.
-- [Frame](./shared/react/components/frame.md): Reference page for frame.
-- [Building Headless Components](./shared/react/guides/building-headless-components.md): Reference page for building headless components.
-- [Callbacks](./shared/react/guides/callbacks.md): Reference page for callbacks.
-- [Headless](./shared/react/guides/headless.md): Reference page for headless.
-- [Iframe Blocking](./shared/react/guides/iframe-blocking.md): Reference page for iframe blocking.
-- [Internationalization](./shared/react/guides/internationalization.md): Reference page for internationalization.
-- [Network Blocker](./shared/react/guides/network-blocker.md): Reference page for network blocker.
-- [Optimization](./shared/react/guides/optimization.md): Reference page for optimization.
-- [Policy Packs](./shared/react/guides/policy-packs.md): Reference page for policy packs.
-- [Script Loader](./shared/react/guides/script-loader.md): Reference page for script loader.
-- [Use Color Scheme](./shared/react/hooks/use-color-scheme.md): Reference page for use color scheme.
-- [Checking Consent](./shared/react/hooks/use-consent-manager/checking-consent.md): Reference page for checking consent.
-- [Location Info](./shared/react/hooks/use-consent-manager/location-info.md): Reference page for location info.
-- [Overview](./shared/react/hooks/use-consent-manager/overview.md): Reference page for overview.
-- [Setting Consent](./shared/react/hooks/use-consent-manager/setting-consent.md): Reference page for setting consent.
-- [Use Draggable](./shared/react/hooks/use-draggable.md): Reference page for use draggable.
-- [Use Focus Trap](./shared/react/hooks/use-focus-trap.md): Reference page for use focus trap.
-- [Use Reduced Motion](./shared/react/hooks/use-reduced-motion.md): Reference page for use reduced motion.
-- [Use SSR Status](./shared/react/hooks/use-ssr-status.md): Reference page for use ssr status.
-- [Use Text Direction](./shared/react/hooks/use-text-direction.md): Reference page for use text direction.
-- [Use Translations](./shared/react/hooks/use-translations.md): Reference page for use translations.
-- [Consent Banner](./shared/react/iab/consent-banner.md): Reference page for consent banner.
-- [Consent Dialog](./shared/react/iab/consent-dialog.md): Reference page for consent dialog.
-- [Overview](./shared/react/iab/overview.md): Reference page for overview.
-- [Use GVL Data](./shared/react/iab/use-gvl-data.md): Reference page for use gvl data.
-- [Classnames](./shared/react/styling/classnames.md): Reference page for classnames.
-- [Color Scheme](./shared/react/styling/color-scheme.md): Reference page for color scheme.
-- [CSS Variables](./shared/react/styling/css-variables.md): Reference page for css variables.
-- [Overview](./shared/react/styling/overview.md): Reference page for overview.
-- [Slots](./shared/react/styling/slots.md): Reference page for slots.
-- [Stylesheet Entrypoint](./shared/react/styling/stylesheet-entrypoint.md): Reference page for stylesheet entrypoint.
-- [Tailwind](./shared/react/styling/tailwind.md): Reference page for tailwind.
-- [Tokens](./shared/react/styling/tokens.md): Reference page for tokens.
-- [Troubleshooting](./shared/troubleshooting.md): Reference page for troubleshooting.
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.