@c15t/scripts 3.0.0-alpha.0 → 3.0.0-alpha.1

package/AGENTS.md

@@ -47,14 +47,17 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 - [Ahrefs Analytics](./docs/integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
 - [Amplitude](./docs/integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
 - [Custom integrations](./docs/integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
+- [Clear on revocation](./docs/integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
 - [Clearbit](./docs/integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
 - [Cloudflare Web Analytics](./docs/integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Cloudflare Zaraz](./docs/integrations/cloudflare-zaraz.md): Synchronize c15t permissions with Zaraz purposes while Cloudflare manages your tools.
 - [Crisp](./docs/integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
 - [Databuddy](./docs/integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
 - [Fathom Analytics](./docs/integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
 - [Google Maps](./docs/integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
 - [Google Tag](./docs/integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
 - [Google Tag Manager](./docs/integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Granular consent](./docs/integrations/granular-consent.md): Let visitors grant a category and still turn one vendor off, without adopting IAB TCF.
 - [Heap](./docs/integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hightouch](./docs/integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hotjar](./docs/integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.

package/README.md

@@ -37,6 +37,7 @@ For further information, guides, and examples visit the [reference documentation
 ## Integrations
 
 - **Google Tag Manager**: Loads with Google Consent Mode v2 defaults set to denied; GTM-managed tags fire only once matching consent is granted ([guide](https://c15t.com/docs/integrations/google-tag-manager))
+- **Cloudflare Zaraz**: Maps c15t effective permissions to Zaraz purpose IDs for tools managed in Cloudflare ([guide](https://c15t.com/docs/integrations/cloudflare-zaraz))
 - **Google Analytics 4 + Google Ads (gtag.js)**: Consent Mode v2 defaults and consent updates when users make a choice ([guide](https://c15t.com/docs/integrations/google-tag))
 - **Conversion pixels**: Meta Pixel, OpenAI Pixel, TikTok Pixel, LinkedIn Insights, Microsoft UET (Microsoft Ads), X Pixel, Reddit Pixel, Snapchat Pixel
 - **Analytics**: PostHog, Amplitude, Heap, Segment, RudderStack, Hightouch, Mixpanel, Microsoft Clarity, Hotjar, Plausible, Fathom, Matomo, Umami, Vercel Analytics

package/dist/engine/runtime.js

@@ -292,6 +292,16 @@ const runtime_partitionConsentIds = function(mapping, consents) {
         deniedConsentIds
     };
 };
+const ALL_DENIED = {
+    experience: false,
+    functionality: false,
+    marketing: false,
+    measurement: false,
+    necessary: true
+};
+const runtime_signalConsents = function(info) {
+    return info.vendor?.granted === false ? ALL_DENIED : info.consents;
+};
 const runtime_getConsentSignalSteps = function(resolvedManifest, mode, consents) {
     if (!resolvedManifest.consentMapping || !resolvedManifest.consentSignal) return [];
     switch(resolvedManifest.consentSignal){
@@ -346,7 +356,8 @@ const runtime_resolvedManifestToScript = function(resolvedManifest) {
         defer: resolvedManifest.loadScript?.defer,
         id: resolvedManifest.vendor,
         persistAfterConsentRevoked: resolvedManifest.persistAfterConsentRevoked,
-        src: resolvedManifest.loadScript?.src
+        src: resolvedManifest.loadScript?.src,
+        vendor: resolvedManifest.vendor
     };
     if (resolvedManifest.bootstrapSteps.length > 0 || resolvedManifest.setupSteps.length > 0 || resolvedManifest.onBeforeLoadGrantedSteps.length > 0 || resolvedManifest.onBeforeLoadDeniedSteps.length > 0 || hasConsentMapping) script.onBeforeLoad = (info)=>{
         const baseContext = {
@@ -359,7 +370,7 @@ const runtime_resolvedManifestToScript = function(resolvedManifest) {
             ...baseContext,
             phase: 'bootstrap'
         });
-        runtime_executePhaseSteps(runtime_getConsentSignalSteps(resolvedManifest, 'default', info.consents), {
+        runtime_executePhaseSteps(runtime_getConsentSignalSteps(resolvedManifest, 'default', runtime_signalConsents(info)), {
             ...baseContext,
             phase: 'consent-default'
         });
@@ -415,7 +426,7 @@ const runtime_resolvedManifestToScript = function(resolvedManifest) {
             hasConsent: info.hasConsent,
             scriptId: resolvedManifest.vendor
         };
-        runtime_executePhaseSteps(runtime_getConsentSignalSteps(resolvedManifest, 'update', info.consents), {
+        runtime_executePhaseSteps(runtime_getConsentSignalSteps(resolvedManifest, 'update', runtime_signalConsents(info)), {
             ...baseContext,
             phase: 'consent-update'
         });

package/dist/registry.js

@@ -17,6 +17,16 @@ const BUILT_IN_INTEGRATION_CATEGORIES = [
     }
 ];
 const builtInScriptIntegrations = [
+    {
+        consentCategory: 'necessary',
+        docsSlug: 'cloudflare-zaraz',
+        hint: 'Consent bridge for tools managed by Zaraz',
+        integrationCategory: 'tag-manager',
+        key: 'cloudflareZaraz',
+        label: 'Cloudflare Zaraz',
+        packageSubpath: 'cloudflare-zaraz',
+        vendor: 'cloudflare-zaraz'
+    },
     {
         consentCategory: 'necessary',
         docsSlug: 'google-tag-manager',

package/dist/vendors/analytics/microsoft-clarity.js

@@ -48,7 +48,10 @@ const microsoft_clarity_getClarityConsentPayload = function(consents, defaultCon
     return fallback;
 };
 const microsoft_clarity_syncClarityConsent = function(info, defaultConsent) {
-    window.clarity?.('consentv2', microsoft_clarity_getClarityConsentPayload(info.consents, defaultConsent));
+    window.clarity?.('consentv2', info.vendor?.granted === false ? {
+        ad_Storage: 'denied',
+        analytics_Storage: 'denied'
+    } : microsoft_clarity_getClarityConsentPayload(info.consents, defaultConsent));
 };
 const clarityManifest = {
     ...vendorManifestContract,

package/dist/vendors/tag-managers/cloudflare-zaraz.js

@@ -0,0 +1,98 @@
+const consentCategories = [
+    'necessary',
+    'functionality',
+    'experience',
+    'measurement',
+    'marketing'
+];
+const readyEvent = 'zarazConsentAPIReady';
+const isConsentApi = (api)=>'object' == typeof api && null !== api && 'APIReady' in api && true === api.APIReady && 'getAll' in api && 'function' == typeof api.getAll && 'set' in api && 'function' == typeof api.set && 'sendQueuedEvents' in api && 'function' == typeof api.sendQueuedEvents;
+const getConsentApi = ()=>{
+    if ("u" < typeof window || !('zaraz' in window)) return;
+    const { zaraz } = window;
+    if ('object' != typeof zaraz || null === zaraz || !('consent' in zaraz)) return;
+    return isConsentApi(zaraz.consent) ? zaraz.consent : void 0;
+};
+const cloudflareZaraz = (options)=>{
+    const mappings = new Map();
+    for (const category of consentCategories)for (const purpose of options.purposes[category] ?? []){
+        if (!purpose.trim() || purpose !== purpose.trim()) throw new Error('Zaraz purpose IDs must be non-empty and have no surrounding whitespace.');
+        if (mappings.has(purpose)) throw new Error(`Zaraz purpose '${purpose}' is mapped more than once.`);
+        mappings.set(purpose, category);
+    }
+    if (0 === mappings.size) throw new Error('Map at least one Zaraz purpose to a c15t category.');
+    let latest;
+    let listeningDocument;
+    let initialized = false;
+    const pendingReplay = new Set();
+    const synchronize = ()=>{
+        const api = getConsentApi();
+        if (!latest || !api) return false;
+        const previous = api.getAll();
+        const permissions = {};
+        let changed = false;
+        for (const purpose of Object.keys(previous)){
+            const category = mappings.get(purpose);
+            const allowed = void 0 !== category && true === latest[category];
+            Object.defineProperty(permissions, purpose, {
+                enumerable: true,
+                value: allowed
+            });
+            changed ||= previous[purpose] !== allowed;
+            if (allowed && true !== previous[purpose]) pendingReplay.add(purpose);
+        }
+        for (const purpose of pendingReplay)if (true !== permissions[purpose]) pendingReplay.delete(purpose);
+        if (false !== options.hideBuiltInModal && true === api.modal) api.modal = false;
+        if (changed) api.set(permissions);
+        if (pendingReplay.size > 0 && false !== options.sendQueuedEvents) api.sendQueuedEvents();
+        pendingReplay.clear();
+        return true;
+    };
+    const apply = ()=>{
+        try {
+            if (!synchronize()) return false;
+        } catch (error) {
+            if (!options.onError) throw error;
+            options.onError(error);
+            return false;
+        }
+        listeningDocument?.removeEventListener(readyEvent, apply);
+        listeningDocument = void 0;
+        if (!initialized) {
+            initialized = true;
+            options.onReady?.();
+        }
+        return true;
+    };
+    const update = ({ consents })=>{
+        latest = consents;
+        if ("u" < typeof document) return;
+        let applied = false;
+        try {
+            applied = apply();
+        } finally{
+            if (!applied && !listeningDocument) {
+                listeningDocument = document;
+                document.addEventListener(readyEvent, apply);
+            }
+        }
+    };
+    return {
+        alwaysLoad: true,
+        callbackOnly: true,
+        category: 'necessary',
+        id: 'cloudflare-zaraz',
+        onConsentChange: (info)=>{
+            if (info.hasConsent) update(info);
+        },
+        onDispose: ()=>{
+            listeningDocument?.removeEventListener(readyEvent, apply);
+            listeningDocument = void 0;
+            latest = void 0;
+            initialized = false;
+            pendingReplay.clear();
+        },
+        onLoad: update
+    };
+};
+export { cloudflareZaraz };

package/dist-types/__tests__/helpers.d.ts

@@ -1,5 +1,5 @@
 import type { ConsentState, Script, ScriptCallbackInfo } from '@c15t/core';
-import type { BuiltInScriptIntegrationKey } from '../registry';
+import type { BuiltInScriptIntegrationKey } from '../registry.js';
 /**
  * Typed view of `globalThis` used by script helper tests.
  *
@@ -31,7 +31,7 @@ export interface ExpectedScriptSnapshot {
     /** Expected consent-revocation persistence flag from the generated script. */
     persistAfterConsentRevoked: boolean | undefined;
     /** Expected remote script URL from the generated helper script. */
-    src: string;
+    src: string | undefined;
 }
 /**
  * Consent state with only required storage enabled.

package/dist-types/engine/compile.d.ts

@@ -1,3 +1,3 @@
-import type { ResolvedManifest, VendorManifest } from '../types';
+import type { ResolvedManifest, VendorManifest } from '../types.js';
 export declare const interpolateValue: (value: unknown, config: Record<string, unknown>) => unknown;
 export declare const compileManifest: (manifest: VendorManifest, config?: Record<string, unknown>) => ResolvedManifest;

package/dist-types/engine/runtime.d.ts

@@ -1,3 +1,3 @@
 import type { Script } from '@c15t/core';
-import type { ResolvedManifest } from '../types';
+import type { ResolvedManifest } from '../types.js';
 export declare const resolvedManifestToScript: (resolvedManifest: ResolvedManifest) => Script;

package/dist-types/registry.d.ts

@@ -77,6 +77,15 @@ export declare const BUILT_IN_INTEGRATION_CATEGORIES: readonly [{
  * the CLI can discover it from the same source.
  */
 export declare const builtInScriptIntegrations: readonly [{
+    readonly consentCategory: 'necessary';
+    readonly docsSlug: 'cloudflare-zaraz';
+    readonly hint: 'Consent bridge for tools managed by Zaraz';
+    readonly integrationCategory: 'tag-manager';
+    readonly key: 'cloudflareZaraz';
+    readonly label: 'Cloudflare Zaraz';
+    readonly packageSubpath: 'cloudflare-zaraz';
+    readonly vendor: 'cloudflare-zaraz';
+}, {
     readonly consentCategory: 'necessary';
     readonly docsSlug: 'google-tag-manager';
     readonly hint: 'GTM container script';

package/dist-types/resolve.d.ts

@@ -1,5 +1,5 @@
 import type { Script } from '@c15t/core';
-import type { VendorManifest } from './types';
+import type { VendorManifest } from './types.js';
 /**
  * Compiles a `VendorManifest` + config into a `Script` object.
  *

package/dist-types/vendors/_shared/install-builders.d.ts

@@ -1,4 +1,4 @@
-import type { VendorManifest } from '../../types';
+import type { VendorManifest } from '../../types.js';
 /**
  * Optional tracking call inserted between the vendor init call and script load.
  */

package/dist-types/vendors/analytics/adobe-analytics.d.ts

@@ -1,5 +1,5 @@
 import type { Script } from '@c15t/core';
-import type { VendorManifest } from '../../types';
+import type { VendorManifest } from '../../types.js';
 declare global {
     interface Window {
         adobeDataLayer?: unknown[];

package/dist-types/vendors/analytics/matomo-analytics.d.ts

@@ -1,5 +1,5 @@
 import type { Script } from '@c15t/core';
-import type { VendorManifest } from '../../types';
+import type { VendorManifest } from '../../types.js';
 declare global {
     interface Window {
         _paq?: unknown[];

package/dist-types/vendors/tag-managers/cloudflare-zaraz.d.ts

@@ -0,0 +1,39 @@
+import type { AllConsentNames, Script } from '@c15t/core';
+/** The Zaraz Consent API methods used by the bridge. */
+export interface ZarazConsentApi {
+    APIReady: boolean;
+    modal?: unknown;
+    getAll: () => Record<string, boolean>;
+    set: (permissions: Record<string, boolean>) => void;
+    sendQueuedEvents: () => void;
+}
+export interface CloudflareZarazOptions {
+    /** Map c15t categories to purpose IDs from the Zaraz dashboard. */
+    purposes: Partial<Record<AllConsentNames, readonly string[]>>;
+    /** Hide the currently visible Zaraz modal. Disable auto-display in Zaraz too. @default true */
+    hideBuiltInModal?: boolean;
+    /** Replay Zaraz's queued pageview events after a denied purpose becomes allowed. @default true */
+    sendQueuedEvents?: boolean;
+    /**
+     * Called once after the first successful synchronization. With automatic
+     * pageviews disabled in Zaraz, send the initial Pageview from this callback.
+     */
+    onReady?: () => void;
+    /** Called when synchronization fails. Retried on the next consent update or readiness event. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Synchronize c15t effective permissions with externally loaded Zaraz tools.
+ * Does not load Zaraz or configure tools. Unmapped Zaraz purposes are denied.
+ * Disable automatic pageviews and send the first Pageview from onReady to avoid
+ * running tools with a stale Zaraz consent cookie before synchronization.
+ *
+ * @param options - Purpose mapping and synchronization callbacks.
+ * @returns A callback-only script for the existing c15t script loader.
+ * @throws {Error} If the mapping is empty, contains blank IDs, or maps an ID twice.
+ * @example
+ * ```ts
+ * cloudflareZaraz({ purposes: { measurement: ['analytics-purpose'] } });
+ * ```
+ */
+export declare const cloudflareZaraz: (options: CloudflareZarazOptions) => Script;

package/docs/README.md

@@ -47,14 +47,17 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 - [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
 - [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
 - [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
+- [Clear on revocation](./integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
 - [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
 - [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Synchronize c15t permissions with Zaraz purposes while Cloudflare manages your tools.
 - [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
 - [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
 - [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
 - [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
 - [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
 - [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Granular consent](./integrations/granular-consent.md): Let visitors grant a category and still turn one vendor off, without adopting IAB TCF.
 - [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.

package/docs/frameworks/javascript/script-loader.md

@@ -45,3 +45,50 @@ assuming all helpers have the same network behavior.
 The loader exposes `updateScripts`, `getLoadedScriptIds` and `dispose`.
 Unloading an element cannot reverse requests or code that already ran. Test
 revocation and vendor cleanup with [verification](../../guides/verify-consent.md).
+
+## Dispose integration resources
+
+Ordinary scripts keep their mounted resource when `updateScripts` receives a
+fresh object with the same ID and unchanged element configuration. New callback
+functions alone do not reload the vendor or send a temporary denial. Changing
+the source, inline code or element attributes starts a new loading lifecycle.
+Consent conditions are reevaluated on every configuration update. Pending
+load and error events use the latest registered callbacks and consent state.
+Setting `persistAfterConsentRevoked` to `false` removes an owned retained element
+when the script no longer has consent.
+
+Custom script configurations can use `onDispose(info)` to release event
+listeners or other resources. Adding this hook opts the configuration into an
+object-owned lifecycle: replacing the object disposes its resources and starts
+again, even with the same ID. Keep these objects stable across framework
+rerenders. The loader also calls the hook when the configuration is removed or
+the loader is disposed, including configurations that never loaded.
+`info.element` contains the last loaded or retained element when available,
+even when configuration removal has already detached it.
+
+Duplicate references receive one cleanup per registration. Re-registering a
+removed object starts a new lifecycle. Updates requested from lifecycle
+callbacks run after the current pass; if several are requested, the latest
+configuration wins. Disposal stops further reconciliation. A callback feedback
+loop exceeding 100 consecutive passes disposes the loader and reports an
+`error` debug event. Avoid callbacks that keep changing consent or replacing
+their own configuration.
+
+`onBeforeLoad` prepares a loading attempt. If a callback changes consent or
+replaces configurations, the loader cancels that attempt before loading and
+reevaluates the latest state. A still-eligible script can retry preparation
+with a new element and updated consent. Make `onBeforeLoad` safe to repeat;
+use `onLoad` for initialization that requires a completed load. This also
+applies to callback-only scripts, whose `onLoad` is skipped when preparation
+invalidates the current pass.
+
+Consent revocation alone does not call `onDispose`. Use `onConsentChange` for
+vendor opt-out commands. Cleanup errors are reported through the loader's debug
+events and do not prevent other configurations from being cleaned up.
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries that a script
+already wrote. Configure [clear on revocation](../../integrations/clear-on-revocation.md)
+on your runtime, or attach its module to your existing kernel, to remove
+declared data when its category is denied.

package/docs/frameworks/next/script-loader.md

@@ -166,3 +166,45 @@ with DevTools, or follow [verification](../../guides/verify-consent.md) in your
 Use [custom integrations](../../integrations/building-integrations.md) for an
 unlisted vendor. Google helpers have a separate
 [Consent Mode contract](../../integrations/google-tag-manager.md).
+
+## Granular consent
+
+A visitor can grant marketing and still turn one vendor off. Declare the
+vendors next to the scripts in `lib/scripts.ts`, with the `vendor` slug each
+script already carries, and pass both to `ConsentRoot`:
+
+```ts title="lib/scripts.ts"
+import type { Vendor } from 'c15t';
+
+export const vendors: Vendor[] = [
+  {
+    id: 'x-pixel',
+    name: 'X Pixel',
+    category: 'marketing',
+    privacyPolicyUrl: 'https://x.com/privacy',
+  },
+];
+```
+
+```tsx title="components/consent.tsx"
+import { scripts, vendors } from '../lib/scripts';
+
+<ConsentRoot state={state} config={consentConfig} scripts={scripts} vendors={vendors}>
+  {children}
+</ConsentRoot>
+```
+
+The preference center lists each vendor under its category with a switch.
+Integrations from `@c15t/scripts` set `vendor` to their manifest slug, so
+`xPixel()` needs no extra wiring; give a hand-written script the same slug
+in its `vendor` field. A backend manifest can declare vendors too. See
+[granular consent](../../integrations/granular-consent.md) for storage,
+bulk actions and the hooks a custom control uses.
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries that a script
+already wrote. Add `clearOnRevocation` to your `ConsentRoot` or provider
+options to remove declared data when its category is denied. See
+[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
+and browser limits.

package/docs/frameworks/react/script-loader.md

@@ -53,3 +53,11 @@ Use [custom integrations](../../integrations/building-integrations.md) for an
 unlisted vendor and [verification](../../guides/verify-consent.md) for the network
 checks. Google helpers have a separate
 [Consent Mode contract](../../integrations/google-tag-manager.md).
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries that a script
+already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
+declared data when its category is denied. See
+[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
+and browser limits.

package/docs/guides/deployment-modes.md

@@ -30,6 +30,18 @@ in your application while consent writes still go to Inth. Regular backend
 browser setup. See [data fetching and transports](./data-fetching.md) for
 the comparison, including custom transports and offline mode.
 
+Manifest resolution removes the per-visitor `/init` request, and with it the
+backend's only count of visitors. The server adapters replace it with a session
+report: after each resolution, on a server-rendered page or the same-origin
+init route, the host posts a small report to the backend's `POST /sessions`,
+server-to-server and detached from the response. The browser makes no request
+and the report stores no identity; the visitor's IP and user agent travel as
+forwarded headers under the backend's usual IP handling. Each report is one
+resolution; a page view can produce a `render` and a `route` report, and the
+consuming side groups them into sessions by address and user agent within a
+window. Static output resolves in the browser and sends none. Set `reportSessions: false` on an adapter to turn
+it off.
+
 ## Match initialization to your application output
 
 | Application output | Initial state             | Required setup                                              |

package/docs/integrations/building-integrations.md

@@ -31,6 +31,11 @@ Replace the example URL and implement the vendor's initialization. This is a
 loader template, not a functioning analytics SDK. The script stays blocked
 while measurement permission is denied.
 
+Add `vendor: 'example-analytics'` and declare the vendor in the runtime's
+`vendors` option or in the backend manifest when visitors should be able to
+turn this vendor off inside a granted category. See
+[granular consent](./granular-consent.md).
+
 ## Define revocation deliberately
 
 `onConsentChange` receives current permission information. Use it to update the

package/docs/integrations/clear-on-revocation.md

@@ -0,0 +1,167 @@
+---
+title: Clear on revocation
+description: Remove configured first-party cookies and Web Storage keys when
+  their consent category is denied.
+group: integrations
+---
+
+## Configure cleanup
+
+Add `clearOnRevocation` to your provider or runtime options. Declare only the
+data owned by each optional category:
+
+```ts
+import { hosted, type ClearOnRevocationConfig } from 'c15t';
+import { createConsentRuntime } from 'c15t/runtime';
+
+const clearOnRevocation = {
+	measurement: {
+		cookies: ['_ga', '_ga_*'],
+		localStorage: ['analytics:*'],
+	},
+	marketing: {
+		cookies: ['_fbp'],
+		sessionStorage: ['campaign-id'],
+	},
+} satisfies ClearOnRevocationConfig;
+
+const runtime = createConsentRuntime({
+	mode: hosted({ url: '/api/c15t' }),
+	clearOnRevocation,
+});
+
+// Start in the browser after mount. The endpoint must serve your c15t backend.
+runtime.start();
+
+// Call runtime.dispose() when the app no longer needs consent management.
+```
+
+For React, pass the same configuration through `ConsentProvider.options`:
+
+```tsx
+import type { ReactNode } from 'react';
+import { ConsentProvider, hosted } from 'c15t/react';
+
+const mode = hosted({ url: '/api/c15t' });
+
+export function Consent({ children }: { children: ReactNode }) {
+	return (
+		<ConsentProvider
+			options={{
+				mode,
+				clearOnRevocation: {
+					measurement: { cookies: ['_ga', '_ga_*'] },
+				},
+			}}
+		>
+			{children}
+		</ConsentProvider>
+	);
+}
+```
+
+The same option is available in Next.js and TanStack Start `ConsentRoot` props, Vue and
+Nuxt configuration, Svelte providers, and Astro integration options. Solid and
+other headless integrations can use `createConsentRuntime` as shown above.
+Every adapter uses the same cleanup module.
+
+Omitting `clearOnRevocation` leaves cleanup disabled. The provider option is
+initial-only. Remount the provider to replace its cleanup configuration. For
+a shared runtime, configure the runtime owner rather than a borrowing provider.
+
+## Matching names and cookie scopes
+
+Use an exact string or a nonempty prefix followed by `*`. `_ga_*` matches
+`_ga_ABC123`; it does not match `_ga`. Regular expressions, wildcards in other
+positions, and a bare `*` are unsupported. Web Storage keys may contain spaces,
+Unicode, and punctuation. Cookie names use their raw spelling, without URL
+decoding.
+
+Cookies can share a name while having different domains or paths. Cleanup
+tries the current host and its parent domains, and the current path and its
+ancestors. To target a specific scope, use an object:
+
+```ts
+const clearOnRevocation = {
+	measurement: {
+		cookies: [
+			{ name: 'analytics-id', domain: 'example.com', path: '/' },
+			{ name: 'checkout-metrics', domain: '', path: '/checkout' },
+			{ name: 'partitioned-metrics', partitioned: true },
+		],
+	},
+};
+```
+
+An empty `domain` means host-only. Explicit domains and paths replace the
+automatic attempts for that field. Exact names can be deleted at a configured
+path even when the current page cannot read that cookie. Prefix matching can
+only discover cookie names visible to the current page, so use an exact name
+for a cookie on another path.
+
+Partitioned cookies require `partitioned: true`; ordinary targets remove
+unpartitioned cookies. Cookie deletion preserves the browser's `__Secure-`
+and `__Host-` prefix requirements. c15t protects its own consent, notice,
+privacy, pending-save, and IAB consent records in cookies and localStorage,
+including configured custom storage keys, even if your patterns match them.
+c15t does not store consent in sessionStorage, so targeted entries there are
+removed even when their names match consent storage keys.
+
+## When cleanup runs
+
+The runtime attaches cleanup after persistence and the script loader. Cleanup
+waits while the policy is pending. On the first settled snapshot, it removes
+configured data for every denied category. This includes a new opt-in visitor
+who has not made a choice and a returning visitor whose permission expired.
+
+After that first pass, cleanup runs when a category changes from allowed to
+denied. Saving a refusal, expiry, a policy change, Global Privacy Control,
+or synchronized records can cause that transition. Under an opt-out policy,
+an expired grant that remains effectively allowed does not trigger deletion.
+The `necessary` category cannot be configured for cleanup.
+
+Cleanup keeps waiting if a failed initial request leaves the policy pending.
+If a previously settled policy falls back to denial after an initialization
+failure, cleanup removes its configured data. A later successful retry cannot
+restore deleted data.
+
+Runtime construction, server rendering, draft checkbox edits, opening the
+dialog, and disposal do not clear data. Cleanup does not poll storage or repeat
+on unrelated UI updates.
+
+## Use an existing kernel
+
+For a manually assembled integration, attach the module in the browser after
+persistence hydration and script-loader setup:
+
+```ts
+import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';
+
+const cleanup = createClearOnRevocation({
+	kernel,
+	config: { measurement: { cookies: ['_ga', '_ga_*'] } },
+	storageConfig,
+});
+
+// Stop observing consent when this integration is torn down.
+cleanup.dispose();
+```
+
+Here `kernel` is your existing consent kernel. Pass the same `storageConfig`
+used by persistence so cleanup protects custom record keys. Attaching the
+module can immediately clear denied categories if the policy is already
+settled. Do not also attach it when your provider or runtime owns cleanup.
+
+## Browser limits
+
+Cleanup can remove JavaScript-accessible first-party cookies and keys in the
+current origin's `localStorage` and `sessionStorage`. It cannot remove
+`HttpOnly` cookies or another origin's data. Keep `HttpOnly` protections and
+use your server to expire cookies that require server access. Cookie deletion
+must match the cookie's scope. See the
+[browser cookie documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
+
+Browser restrictions can prevent reads or deletions. Cleanup failures do not
+block consent updates. A running SDK may write data again after a sweep, so
+keep script gating and the integration's consent-change or teardown behavior
+configured. Deleting a script element cannot undo JavaScript it already ran.