@c15t/browser 3.0.0-alpha.0 → 3.0.0-alpha.2

package/docs/README.md

@@ -27,14 +27,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](https://c15t.com/docs/guides/verify-consent).
+
+## 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/javascript/script-tag.md

@@ -15,7 +15,7 @@ Paste this before `</head>` (Framer: Site Settings → Custom Code; Webflow: Pro
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.js"
+  src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.js"
   data-backend-url="https://your-instance.c15t.dev"
   defer
 ></script>
@@ -72,7 +72,7 @@ For anything the attributes cannot express, queue a `config` call on `window.c15
     },
   }]);
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.js" defer></script>
 ```
 
 With `data-manual`, a later `c15t.init()` retains the original tag's attributes. Queued `config` calls override those attributes, and options passed directly to `init()` win over both. Changing or removing the tag after it loads does not change the captured configuration. After `dispose()`, a new `init()` reuses the captured attributes and queued defaults, including backend-injected settings. Pass new options to `init()` to override them.
@@ -93,6 +93,30 @@ An activated inline or external script cannot be undone. Supply cleanup through
 
 See [script gating](./script-loader.md) for the full `scripts` option, and the [integrations](../../integrations/overview.md) for ready-made GTM, GA4, and pixel loaders.
 
+## Clear data when consent is withdrawn
+
+Queue `clearOnRevocation` before the bundle loads, or pass it to `c15t.init()`:
+
+```html
+<script>
+  window.c15t = window.c15t || [];
+  c15t.push(['config', {
+    clearOnRevocation: {
+      measurement: {
+        cookies: ['_ga', '_ga_*'],
+        localStorage: ['analytics:*'],
+        sessionStorage: ['analytics:session'],
+      },
+    },
+  }]);
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.js" defer></script>
+```
+
+The client removes these entries when measurement permission becomes denied. It also clears them at startup after the policy resolves if measurement is already denied. Other categories and c15t's own consent records stay intact.
+
+Cleanup is disabled unless configured. The configuration is initial-only; call `dispose()` and `init()` to replace it. Deleting data does not stop an already running tracker, so use the vendor's consent or shutdown API too. See [clear on revocation](../../integrations/clear-on-revocation.md) for prefix matching, cookie scopes, and browser limits.
+
 ## Buttons and links
 
 Any element on the page can drive the banner. Add `data-c15t-action` and the client wires it:
@@ -148,7 +172,7 @@ Load `c15t.headless.js` instead and no banner or CSS ships. The runtime still re
   <button data-c15t-action="reject">Reject</button>
   <button data-c15t-action="accept">Accept</button>
 </div>
-<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.headless.js" data-backend-url="https://your-instance.c15t.dev" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.headless.js" data-backend-url="https://your-instance.c15t.dev" defer></script>
 <script>
   window.c15t = [['on', 'ui', (surface) => { document.getElementById('banner').hidden = surface !== 'banner'; }]];
 </script>
@@ -216,7 +240,7 @@ Or fetch a cached manifest with `data-manifest-url`. When you host the manifest
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.js"
+  src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.js"
   data-manifest-url="https://cdn.example.com/consent-policy.json"
   data-backend-url="https://your-instance.c15t.dev"
   defer
@@ -260,7 +284,7 @@ Anything the page queues with `c15t.push(['config', ...])` before the tag still
 Add a second tag and the c15t DevTools panel attaches to the page's client. It shows consents, gated scripts, the resolved policy and every kernel event, and its Location tab changes country, region, language and GPC and re-runs init, so you can watch a geo-keyed policy switch without spoofing headers or a VPN.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.devtools.js" data-open data-tab="location" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.devtools.js" data-open data-tab="location" defer></script>
 ```
 
 Tag order does not matter; the panel waits for the client. It is also on `window.c15t.devtools`, so `c15t.devtools.actions.setOverrides({ country: 'US' })` followed by `c15t.devtools.actions.init()` does the same from the console. Leave the tag out of production pages; it shows internal state. Bundler users import `mountDevTools` from `@c15t/browser/devtools`.
@@ -307,7 +331,7 @@ Load `c15t.iab.js` instead of `c15t.js` when your policy requires IAB TCF. This
     },
   }]];
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.iab.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.iab.js" defer></script>
 <button type="button" data-c15t-action="customize">Privacy settings</button>
 ```
 

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.