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

package/dist-types/vendors/tag-managers/google-tag-manager.d.ts

@@ -1,96 +1,2 @@
-import type { Script } from '@c15t/core';
-declare global {
-    interface Window {
-        dataLayer: unknown[];
-        gtag: (...args: unknown[]) => void;
-    }
-}
-/**
- * Google Tag Manager vendor manifest.
- *
- * Defines GTM as a declarative integration:
- * - Initializes dataLayer and gtag function before the container loads
- * - Maps c15t consent categories to Google Consent Mode v2 types
- * - Signals consent state via `gtag('consent', 'default'|'update', ...)`
- */
-export declare const googleTagManagerManifest: {
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
-    readonly alwaysLoad: true;
-    readonly bootstrap: [{
-        readonly ifUndefined: true;
-        readonly name: 'dataLayer';
-        readonly type: 'setGlobal';
-        readonly value: readonly [];
-    }, {
-        readonly ifUndefined: true;
-        readonly name: 'gtag';
-        readonly queue: 'dataLayer';
-        readonly type: 'defineQueueFunction';
-    }];
-    readonly category: 'necessary';
-    readonly consentMapping: Record<string, string[]>;
-    readonly consentSignal: 'gtag';
-    readonly install: [{
-        readonly queue: 'dataLayer';
-        readonly type: 'pushToQueue';
-        readonly value: {
-            readonly event: 'gtm.js';
-            readonly 'gtm.start': {
-                readonly kind: "c15t.runtime-value";
-                readonly value: 'timestamp';
-            };
-        };
-    }, {
-        readonly async: true;
-        readonly src: 'https://www.googletagmanager.com/gtm.js?id={{id}}';
-        readonly type: 'loadScript';
-    }];
-    readonly onConsentChange: [{
-        readonly args: ["event", "{{updateEventName}}"];
-        readonly global: 'gtag';
-        readonly type: 'callGlobal';
-    }];
-    readonly vendor: 'google-tag-manager';
-};
-export interface GoogleTagManagerOptions {
-    /** Container queue name. Defaults to dataLayer. */
-    dataLayer?: string;
-    /**
-     * Your Google Tag Manager container ID. Begins with 'GTM-'.
-     * @example `GTM-1234XXX`
-     */
-    id: string;
-    /**
-     * Custom event name fired after consent updates.
-     * Can be used as a trigger in GTM to load scripts once consent is updated.
-     *
-     * @default 'consent-update'
-     */
-    updateEventName?: string;
-    /**
-     * Custom mapping from c15t consent categories to Google Consent Mode v2 types.
-     * Overrides the default mapping when provided.
-     *
-     * @default
-     * ```ts
-     * {
-     *   necessary: ['security_storage'],
-     *   functionality: ['functionality_storage'],
-     *   measurement: ['analytics_storage'],
-     *   marketing: ['ad_storage', 'ad_user_data', 'ad_personalization'],
-     *   experience: ['personalization_storage'],
-     * }
-     * ```
-     */
-    consentMapping?: Record<string, string[]>;
-}
-/**
- * Creates a Google Tag Manager script.
- * GTM can be used for managing the consent of other scripts via Google Tag Manager consent mode.
- * We recommend using c15t's script loader instead so your script logic is centralised.
- *
- * @param options - The options for the Google Tag Manager script.
- * @returns The Google Tag Manager script.
- */
-export declare const googleTagManager: ({ id, dataLayer, updateEventName, consentMapping, }: GoogleTagManagerOptions) => Script;
+/** @deprecated Use @c15t/integrations/vendors/tag-managers/google-tag-manager. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/tag-managers/google-tag-manager';

package/dist-types/vercel-analytics.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use @c15t/integrations/vercel-analytics. Compatibility ends in v4. */
+export * from '@c15t/integrations/vercel-analytics';

package/dist-types/x-pixel.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use @c15t/integrations/x-pixel. Compatibility ends in v4. */
+export * from '@c15t/integrations/x-pixel';

package/docs/README.md

@@ -1,19 +1,21 @@
 # @c15t/scripts
 
-> Consent-aware vendor integrations and Consent Mode loading contracts.
+> Deprecated v3 compatibility package for @c15t/integrations. Migrate before v4.
 
 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.
+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
 
 - [Connect your integrations](./integrations/overview.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,75 +23,139 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 
 ## Frameworks
 
-- [JavaScript script loading](./frameworks/javascript/script-loader.md): Attach a script loader to the consent kernel and dispose it with the application.
-- [Load scripts with consent](./frameworks/next/script-loader.md): Register vendor scripts in your existing Next.js ConsentRoot and handle loading and revocation.
-- [Load scripts with consent](./frameworks/react/script-loader.md): Register vendor scripts once and let effective permissions control loading.
+### Next.js
+
+- [Embeds](./frameworks/next/embeds.md): Keep YouTube videos, maps and other iframes out of a Next.js page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.
+- [Network blocker](./frameworks/next/network-blocker.md): Hold fetch and XMLHttpRequest calls in a Next.js app until their consent category is allowed, with networkBlocker rules on ConsentRoot.
+- [Scripts](./frameworks/next/scripts.md): Register vendor scripts in a Next.js ConsentRoot, check how each vendor loads, let visitors turn off one vendor and clear stored data after revocation.
+
+### TanStack Start
+
+- [Embeds](./frameworks/tanstack-start/embeds.md): Keep YouTube videos, maps and other iframes out of a TanStack Start page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.
+- [Network blocker](./frameworks/tanstack-start/network-blocker.md): Hold fetch and XMLHttpRequest calls in a TanStack Start app until their consent category is allowed, with networkBlocker rules on ConsentRoot.
+- [Scripts](./frameworks/tanstack-start/scripts.md): Load vendor scripts by consent category in a TanStack Start app with ConsentRoot, and clear stored data or reload the page when a visitor withdraws consent.
+
+### React
+
+- [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.
+- [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.
+- [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.
+
+### Nuxt
+
+- [Embeds](./frameworks/nuxt/embeds.md): Keep YouTube videos, maps and other iframes out of a Nuxt page until their consent category is allowed, with ConsentGate or the iframe blocker.
+- [Network blocker](./frameworks/nuxt/network-blocker.md): Hold fetch and XMLHttpRequest calls in a Nuxt app until their consent category is allowed, with rules in the c15t module options.
+- [Scripts](./frameworks/nuxt/scripts.md): Load vendor scripts by consent category in a Nuxt app with the c15t Nuxt module, and what happens when a visitor withdraws consent.
+
+### Vue
+
+- [Embeds](./frameworks/vue/embeds.md): Keep YouTube videos, maps and other iframes out of a Vue page until their consent category is allowed, with ConsentGate or the iframe blocker.
+- [Network blocker](./frameworks/vue/network-blocker.md): Hold fetch and XMLHttpRequest calls in a Vue app until their consent category is allowed, with rules passed to the c15t Vue plugin.
+- [Scripts](./frameworks/vue/scripts.md): Load vendor scripts by consent category in a Vue app with the c15t Vue plugin, and what happens when a visitor withdraws consent.
+
+### Astro
+
+- [Embeds](./frameworks/astro/embeds.md): Gate YouTube videos, maps, social posts and other iframes on an Astro site so they load only after the visitor allows their consent category, with a custom element or the c15t iframe blocker.
+- [Network blocker](./frameworks/astro/network-blocker.md): Block fetch and XMLHttpRequest calls to tracking hosts on an Astro site until the visitor allows their consent category, with c15t's network blocker rules and an onRequestBlocked handler.
+- [Scripts](./frameworks/astro/scripts.md): Load vendor scripts and gated inline scripts on an Astro site only after the visitor allows their consent category, and stop them when consent is withdrawn.
+
+### Svelte
+
+- [Embeds](./frameworks/svelte/embeds.md): Keep YouTube videos, maps and other iframes out of a Svelte page until their consent category is allowed, with ConsentGate or the iframe blocker.
+- [Network blocker](./frameworks/svelte/network-blocker.md): Hold fetch and XMLHttpRequest calls to tracking domains in a Svelte app until their consent category is allowed, with the provider's networkBlocker option.
+- [Scripts](./frameworks/svelte/scripts.md): Load vendor scripts, iframes and network requests in a Svelte app only after the visitor allows their consent category, and stop them when consent is withdrawn.
+
+### SvelteKit
+
+- [Embeds](./frameworks/sveltekit/embeds.md): Keep YouTube videos, maps and other iframes out of SvelteKit server HTML and the browser until their consent category is allowed.
+- [Network blocker](./frameworks/sveltekit/network-blocker.md): Hold browser fetch and XMLHttpRequest calls to tracking domains in a SvelteKit app until their consent category is allowed, with the networkBlocker option.
+- [Scripts](./frameworks/sveltekit/scripts.md): Load vendor scripts, iframes and network requests in a SvelteKit app only after the visitor allows their consent category, and stop them when consent is withdrawn.
+
+### HTML script tag
+
+- [Embeds](./frameworks/html/embeds.md): Hold YouTube videos, maps and other iframes on a plain HTML page until their consent category is allowed with data-src and data-category, show a placeholder, and configure the c15t iframe blocker.
+- [Network blocker](./frameworks/html/network-blocker.md): Hold fetch and XMLHttpRequest calls from a plain HTML page until their consent category is allowed, with network blocker rules queued on the c15t script tag.
+- [Scripts](./frameworks/html/scripts.md): Hold vendor scripts on a plain HTML page until the visitor allows their category, load scripts with callbacks, handle withdrawal and clear vendor cookies with the c15t script tag and no build step.
+
+### JavaScript
+
+- [Scripts](./frameworks/javascript/scripts.md): Register vendor scripts with @c15t/browser, createConsentRuntime or a consent kernel in JavaScript, and control what happens when a visitor withdraws permission.
+
+## Concepts
+
+- [Choose your setup](./concepts/choose-your-setup.md): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
+- [Consent categories](./concepts/consent-categories.md): Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.
+- [Consent state reference](./concepts/consent-state.md): How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.
+- [Data fetching](./concepts/data-fetching.md): How c15t gets policy data through a cached manifest, backend /init, the browser or offline rules, and where consent choices are saved.
+- [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
+- [Policies](./concepts/policies.md): How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.
 
 ## Guides
 
-- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
-- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
-- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
-- [Share consent controls across frameworks](./guides/shared-consent-controls.md): Use the same c15t script lifecycle, external consent source, and event controls in every framework.
-- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
-- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+- [Banner experiments](./guides/banner-experiments.md): Run A/B tests on consent banner presentation with any feature-flag provider or built-in weighted assignment, and attribute every impression and choice to its arm.
+- [Troubleshooting](./guides/troubleshooting.md): Fix a missing banner, analytics that load before consent, choices lost on reload, CORS errors, hydration differences and failed static builds in c15t v3.
+- [Verify consent](./guides/verify-consent.md): Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.
 
 ## Customization
 
-- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
-- [Banner styling recipes](./customization/recipes.md): See real v3 components and reuse the exact theme configuration behind the examples.
-- [Style component slots](./customization/slots.md): Target a specific c15t component part without replacing its markup or behavior.
-- [Theme tokens and CSS](./customization/tokens.md): Style c15t with semantic tokens and use the stylesheet that matches your CSS tooling.
+- [Class names and CSS-in-JS](./customization/class-names.md): Style c15t's component parts with CSS Modules, vanilla-extract, StyleX, Emotion or plain class names, and see which approach works in each framework.
+- [Dark mode](./customization/dark-mode.md): Switch c15t's banner and dialog to dark colors with colorScheme, set your own dark tokens, follow your site's theme switch, and paint dark on the first frame in every framework.
+- [Motion and animation](./customization/motion.md): Change how fast c15t's banner and dialog animate with duration and easing tokens, turn animations off per surface with disableAnimation, and check reduced-motion behavior in each framework.
+- [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
+- [Banner designs](./customization/recipes.md): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
+- [Component parts](./customization/slots.md): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
+- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see when the dialog's CSS loads, order c15t's cascade layer against your own, and run c15t without its styles.
+- [Tailwind CSS](./customization/tailwind.md): Load c15t's styles next to Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
+- [Theme tokens](./customization/tokens.md): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
 - [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 
 ## Integrations
 
-- [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
-- [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
-- [Clear on revocation](./integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
-- [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
-- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Synchronize c15t permissions with Zaraz purposes while Cloudflare manages your tools.
-- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
-- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
-- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Front Chat](./integrations/front-chat.md): Load the Front Chat widget with functionality permission, forward CSP nonces and clear the session on revocation.
-- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
-- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
-- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
-- [Granular consent](./integrations/granular-consent.md): Let visitors grant a category and still turn one vendor off, without adopting IAB TCF.
-- [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
-- [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
-- [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
-- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
-- [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
-- [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
-- [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
-- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
-- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
-- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
-- [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker with measurement permission, forward its settings and verify loading and revocation.
-- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
-- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
-- [Pinterest Tag](./integrations/pinterest-tag.md): Configure the Pinterest Tag with c15t v3, track typed events and verify marketing permission, revocation and reload.
-- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
-- [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
-- [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
-- [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
-- [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
-- [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
-- [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [Adobe Analytics](./integrations/adobe-analytics.md): Load an Adobe Data Collection Tags property only after measurement consent with the c15t adobeAnalytics helper, and check its extensions in DevTools.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Load Ahrefs Web Analytics only after measurement consent with the c15t ahrefsAnalytics helper, and check it in DevTools.
+- [Amplitude](./integrations/amplitude.md): Load the Amplitude Browser SDK 2 only after measurement consent with the c15t amplitude helper, which opts the SDK out on revocation and back in on a new grant.
+- [Custom integrations](./integrations/building-integrations.md): Gate a vendor that has no @c15t/integrations helper, or sync consent with an SDK your app already loads, using a c15t script configuration.
+- [Clearbit](./integrations/clearbit.md): Load the Clearbit enrichment tag only after marketing consent with the c15t clearbit helper, and check it in DevTools.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Load the Cloudflare Web Analytics beacon only after measurement consent with the c15t cloudflareWebAnalytics helper, and check it in DevTools.
+- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Sync c15t permissions to Cloudflare Zaraz purposes with the c15t cloudflareZaraz bridge, which runs on every page without loading a script, and check the tools it controls.
+- [Crisp](./integrations/crisp.md): Load the Crisp chat widget only after functionality consent with the c15t crisp helper, pass its runtime settings and check it in DevTools.
+- [Databuddy](./integrations/databuddy.md): Load the Databuddy SDK on every page with the c15t databuddy helper, switch its disabled flag and config from measurement consent, and check both in DevTools.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Load Fathom Analytics only after measurement consent with the c15t fathomAnalytics helper, set its SPA mode, and check it in DevTools.
+- [Front Chat](./integrations/front-chat.md): Load the Front Chat widget only after functionality consent with the c15t frontChat helper, forward CSP nonces, clear the session on revocation and check it in DevTools.
+- [Google Maps](./integrations/google-maps.md): Gate a Google Maps iframe embed with c15t v3 so the map loads only after the visitor allows its consent category, in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.
+- [Google Tag](./integrations/google-tag.md): Load gtag.js for Google Analytics or Google Ads with c15t Consent Mode v2 signals, and verify the consent commands in DevTools.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Load a Google Tag Manager container with c15t Consent Mode v2 signals, configure consent checks inside the container, and verify both in DevTools.
+- [Heap](./integrations/heap.md): Load the Heap config script and heap.js only after measurement consent with the c15t heap helper, and check it in DevTools.
+- [Hightouch](./integrations/hightouch.md): Load the Hightouch Events browser SDK only after measurement consent with the c15t hightouch helper, and check page events in DevTools.
+- [Hotjar](./integrations/hotjar.md): Load Hotjar only after measurement consent with the c15t hotjar helper, and check its loader and recordings in DevTools.
+- [Intercom](./integrations/intercom.md): Load the Intercom messenger only after functionality consent with the c15t intercom helper, set its region and check it in DevTools.
+- [Klaviyo](./integrations/klaviyo.md): Load Klaviyo signup forms and onsite tracking only after marketing and measurement consent with the c15t klaviyo helper, gate your own events, and check it in DevTools.
+- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Load the LinkedIn Insight Tag only after marketing consent with the c15t linkedinInsights helper, guard lintrk conversion calls, and check it in DevTools.
+- [LogRocket](./integrations/logrocket.md): Load LogRocket session replay only after measurement consent with the c15t logRocket helper, including proxied setups, and check it in DevTools.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo after measurement consent with the c15t matomoAnalytics helper, or use Matomo's own consent mode, and check each mode in DevTools.
+- [Meta Pixel](./integrations/meta-pixel.md): Load the Meta Pixel only after marketing consent with the c15t metaPixel helper, guard fbq event calls, and check it in DevTools.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Load Microsoft Clarity only after measurement consent with the c15t clarity helper, send Consent V2 storage signals and check them in DevTools.
+- [Microsoft UET](./integrations/microsoft-uet.md): Load Microsoft Advertising UET on every page with the c15t microsoftUet helper, send ad_storage consent defaults and updates, and verify both in DevTools.
+- [Mixpanel](./integrations/mixpanel-analytics.md): Load the Mixpanel SDK on every page with the c15t mixpanelAnalytics helper, which switches Mixpanel tracking on and off with measurement consent, and check it in DevTools.
+- [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker only after measurement consent with the c15t oneDollarStats helper, forward its data-attribute settings, and check it in DevTools.
+- [OpenAI Pixel](./integrations/openai-pixel.md): Load the ChatGPT Ads Measurement Pixel only after marketing consent with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in DevTools.
+- [Integrations](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, email and SMS, chat and embedded content.
+- [Pinterest Tag](./integrations/pinterest-tag.md): Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.
+- [Pirsch](./integrations/pirsch.md): Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
+- [PostHog](./integrations/posthog.md): Load PostHog before or after measurement consent with the c15t posthog helper, choose its cookieless behavior, turn off PostHog modules you do not use, and sync consent with an SDK you already initialize.
+- [Promptwatch](./integrations/promptwatch.md): Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Load the Reddit Pixel only after marketing consent with the c15t redditPixel helper, guard rdt conversion calls, and check it in DevTools.
+- [RudderStack](./integrations/rudderstack.md): Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.
+- [Segment](./integrations/segment.md): Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.
+- [Umami Analytics](./integrations/umami-analytics.md): Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Load the Vercel Web Analytics script only after measurement consent with the c15t vercelAnalytics helper, choose the debug script, and check it in DevTools.
+- [X Pixel](./integrations/x-pixel.md): Load the X Pixel only after marketing consent with the c15t xPixel helper, guard twq conversion events, and check it in DevTools.
 - [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
 
 ## Reference
 
-- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
+- [Migrate to v3](./upgrade-v3.md): Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React providers, the JavaScript runtime, custom UI built on useConsentManager, callbacks, policies, stored consent and a self-hosted backend.

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](https://c15t.com/docs/frameworks/react/quickstart)                                                                        |
+| React Router framework mode, Remix, or another server-rendered React app               | Browser resolves consent after hydration                                               | [React rendering](https://c15t.com/docs/frameworks/react/rendering#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/concepts/consent-categories.md

@@ -0,0 +1,84 @@
+---
+title: Consent categories
+description: Assign scripts, embeds and features to c15t consent categories, and
+  understand which categories the preference dialog shows.
+group: concepts
+---
+
+## Choose categories by purpose
+
+| Category        | Purpose                                        |
+| --------------- | ---------------------------------------------- |
+| `necessary`     | Functionality required for the site to operate |
+| `functionality` | Optional features such as support widgets      |
+| `measurement`   | Analytics and usage measurement                |
+| `experience`    | Optional personalization                       |
+| `marketing`     | Advertising and marketing                      |
+
+`necessary` is always permitted. Assign categories based on what an integration
+does in your application; renaming analytics to necessary does not change its
+purpose.
+
+c15t discovers categories from registered scripts, network rules, React `ConsentGate`
+components, and iframes with `data-category` handled by the iframe blocker.
+The browser client also discovers inert scripts tagged with `data-c15t-category`.
+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 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
+script or unmounting a frame does not remove its category or erase consent.
+Discovery does not grant consent or change backend permission restrictions.
+
+## Respect policy scope
+
+A strict scope denies categories outside the rule. A permissive scope can allow
+out-of-scope categories unless another restriction applies. When a rule selects
+only some optional categories, set `scopeMode` explicitly. An omitted scope,
+`['*']`, or a list containing only `necessary` expands to the default optional
+categories; a necessary-only list is not a shortcut for disabling all tracking.
+
+For example, a backend rule with `categories: ['necessary']` and scripts assigned
+to `marketing` and `measurement` displays Necessary, Marketing, and Analytics,
+even without `consentCategories`. Accept All records both optional choices and
+keeps the banner dismissed after reload. An explicit list of
+`['necessary', 'measurement']` with no other integrations displays Necessary and
+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. 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 [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.