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

package/docs/integrations/granular-consent.md

@@ -0,0 +1,208 @@
+---
+title: Granular consent
+description: Let visitors grant a category and still turn one vendor off,
+  without adopting IAB TCF.
+group: integrations
+---
+
+Granular consent is choice below the category level: a visitor grants
+marketing and still turns Meta off. The unit of that choice is a vendor, so
+the API names them `vendors`, `vendor` and `data-vendor`, and the hooks
+`useVendorAllowed` and `useVendorDraft`. Everything else stays as it is:
+categories, policies, and the preference center gain vendor rows rather than
+a second consent model.
+
+## Declare vendors
+
+Add `vendors` to your runtime options. Each vendor sits inside a category
+condition and needs a name and a privacy policy URL so the preference surface
+can list it. The React provider takes the same option once its preference
+center renders vendor rows; scripts, rules and iframes are gated the same way
+whichever place declares it:
+
+```ts
+import { hosted, type Vendor } from 'c15t';
+import { createConsentRuntime } from 'c15t/runtime';
+
+const vendors = [
+	{
+		id: 'meta-pixel',
+		name: 'Meta Pixel',
+		category: 'marketing',
+		privacyPolicyUrl: 'https://www.facebook.com/privacy/policy/',
+		description: 'Ad conversion measurement and audiences.',
+	},
+	{
+		id: 'google-analytics',
+		name: 'Google Analytics',
+		category: 'measurement',
+		privacyPolicyUrl: 'https://policies.google.com/privacy',
+	},
+] satisfies Vendor[];
+
+const runtime = createConsentRuntime({
+	mode: hosted({ url: '/api/c15t' }),
+	vendors,
+	scripts: [
+		{
+			id: 'meta-pixel',
+			category: 'marketing',
+			vendor: 'meta-pixel',
+			src: 'https://connect.facebook.net/en_US/fbevents.js',
+		},
+	],
+});
+
+// Start in the browser after mount. The endpoint must serve your c15t backend.
+runtime.start();
+```
+
+The `id` is a lowercase slug of up to 64 characters. Reuse it as the `vendor`
+field on scripts and network rules and as the `data-vendor` attribute on
+iframes. Integrations from `@c15t/scripts` already set `vendor` to their
+manifest slug, so `gtag()` and `metaPixel()` need no extra wiring.
+
+A backend can also declare vendors. Add `vendors` and an optional
+`vendorListVersion` to the manifest configuration; `/init` returns them and the
+client merges them with the vendors declared in code. When both declare the
+same id, the copy declared in code wins, and the backend copy comes back if the
+code declaration is removed later. A slug used by a script, rule or iframe
+but declared nowhere still gates loading. It is hidden from the preference surface, and the
+runtime warns about it outside production.
+
+## How a vendor is gated
+
+A target loads when its category condition passes and the visitor has not
+turned its vendor off:
+
+```text
+loads  =  category condition satisfied  AND  vendor not denied
+```
+
+The category is evaluated first, so an unknown category still throws as a
+configuration error. A vendor toggle never grants a category on its own: with
+marketing denied, `meta-pixel` stays blocked whatever its own switch says.
+A script with `alwaysLoad` still mounts, as it does for a denied category;
+its callbacks receive the vendor result in `info.vendor.granted` so a
+self-managing SDK can honor it.
+
+Under an `iab` policy the `vendor` slug is inert. Vendor consent then comes from
+the TC string through `vendorId`, and the vendor rows are not shown.
+
+The same rule applies to the three gates:
+
+| Surface         | Field                           |
+| --------------- | ------------------------------- |
+| Script loader   | `Script.vendor`                 |
+| Network blocker | `NetworkBlockerRule.vendor`     |
+| Iframe blocker  | `data-vendor` on the `<iframe>` |
+
+An iframe with `data-vendor` and no `data-category` is gated on the vendor
+alone. An unknown `data-vendor` value is granted rather than thrown: a vendor
+the visitor never saw cannot have been turned off. Such a frame has no
+category to follow, so a denial the visitor recorded earlier holds even while
+nothing declares the slug, for example before the backend's vendor list has
+arrived on a cold start.
+
+A script, rule or frame keeps its slug declared for as long as it is
+configured. If a backend list or a provider update drops the entry, the
+loader or blocker puts it back, so a stored denial keeps gating it. A slug
+several modules share stays under every category they name it with, whichever
+module updates last, and drops a category only once no module names it there.
+Disposing a loader or blocker, or removing a gated frame from the page, drops
+what only it named, so a vendor no live module owns stops being toggleable.
+
+## Record a vendor choice
+
+Vendor grants travel with the save. Stage them and confirm with the next save,
+or pass them next to the categories:
+
+```ts
+// Stage from a toggle handler; nothing changes until save({}) runs. The
+// empty patch confirms no category, so only the staged vendor is recorded;
+// save() with no input would reconfirm every displayed category too.
+runtime.stageVendorConsent('meta-pixel', false);
+await runtime.kernel.commands.save({});
+
+// Or confirm categories and vendors in one action.
+await runtime.kernel.commands.save({
+	marketing: true,
+	measurement: true,
+	vendors: { 'meta-pixel': false },
+});
+```
+
+`stageVendorConsent` stages a vendor slug for the next save; it is not the
+IAB handle's `setVendorConsent`, which sets a TCF vendor by numeric id and
+takes effect at once. The grants can also travel in the save context as
+`{ vendors }`, which wins when both are given.
+
+Only the vendors the visitor turned off are stored. Accept all and reject all
+both clear that list, so vendors follow their category on a bulk action. A bulk
+action narrowed to the displayed categories only lifts the denials of vendors
+those categories decide on their own; a vendor another granted category would
+still load keeps its denial. A
+vendor that is not declared, or is declared with `disabled: true`, is ignored.
+Under an opt-out policy every vendor starts on and the stored list is the
+do-not-sell list.
+
+A vendor-only change records without touching category receipts. The kernel
+emits `vendors:recorded` rather than `choice:recorded`, writes the
+`<storageKey>-vendors` cookie and localStorage entry, and sends the complete
+grant map to the backend as `vendorChoice`. Category confirmation times are not
+renewed. The vendor entry also carries the subject id, so a visitor whose first
+act only decided vendors keeps the same subject after a reload even though no
+category record exists yet.
+
+Scripts see the vendor result in their callbacks. `ScriptCallbackInfo.vendor`
+carries `{ id, granted }` outside IAB mode. Integrations that send Google
+Consent Mode or RudderStack signals send every category as denied while their
+vendor is off, so the vendor's own consent API cannot re-enable tracking.
+
+## Show vendors in the preference center
+
+The `ConsentWidget` and `ConsentDialog` in React, Vue and Svelte list vendors
+under their category when the provider declares them. Pass the same `vendors`
+array to `ConsentProvider`, to the `vendors` prop of `ConsentRoot` in
+[Next.js](https://c15t.com/docs/frameworks/next/script-loader#granular-consent) and
+[TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart#granular-consent),
+to the Nuxt module or Vue plugin config next to `scripts`, or to
+`ConsentManagerProvider` options in Svelte:
+
+```tsx
+import { ConsentProvider, hosted } from 'c15t/react';
+
+<ConsentProvider options={{ mode: hosted({ url: '/api/c15t' }), vendors }}>
+	{children}
+</ConsentProvider>;
+```
+
+Each category row expands to one card per vendor with its own switch. The
+switches disable while the category is off in the draft, and Save records the
+vendors the visitor moved. A custom control uses `useVendorDraft()` from
+`c15t/react` to read and stage the same grants, with `isStale` and `reset` for
+a draft the policy or vendor list changed under, and `useVendorAllowed(id)` to
+read one vendor's effective result. Copy comes from
+`consentManagerDialog.vendors.{title, privacyPolicy, disabledByCategory,
+switchLabel}` in the translations. In Vue, `useConsentDraft()` returns the
+same `vendors` map and `setVendor`; in Svelte, `getConsentManager()` exposes
+`selectedVendors`, `setSelectedVendor` and `getDisplayedVendors(category)`.
+The three frameworks render the same cards, and the parity suite compares
+their markup, accessibility tree, computed styles and geometry.
+
+## What a denial does not do
+
+Turning a vendor off blocks future loads and requests. It does not delete the
+cookies that vendor already set, and
+[clear on revocation](./clear-on-revocation.md) does not help here:
+it runs when a category is denied, and the category stays granted when only one
+of its vendors is off. Remove that vendor's cookies yourself from an
+`onConsentChange` callback that checks `info.vendor.granted`.
+
+A vendor denial has no expiry and no policy basis. It stays until the visitor
+changes it or a bulk action clears it, including across a policy change that
+requires the category choice again.
+
+Adding a vendor to the list does not reopen consent. New vendors default to on
+inside a granted category. Use the policy rule's `copyRevision` when a new
+vendor should prompt the visitor again.

package/docs/integrations/overview.md

@@ -34,15 +34,16 @@ behavior before choosing either approach.
 | [Google Maps](./google-maps.md) | Framework-specific consent-gated map iframe   | Iframe mounts only while the chosen permission is allowed |
 | [YouTube](./youtube.md)         | Framework-specific consent-gated video iframe | Iframe mounts only while the chosen permission is allowed |
 
-Both guides include all nine framework examples. React and Svelte use `Frame`;
+Both guides include all nine framework examples. React and Svelte use `ConsentGate`;
 Vue conditionally renders the iframe, and Astro and JavaScript use the existing
 kernel to control its DOM lifecycle. Embeds do not require `@c15t/scripts`.
 
 ## Tag managers
 
-| Integration                                   | Helper             | Category    | Loading behavior                     |
-| --------------------------------------------- | ------------------ | ----------- | ------------------------------------ |
-| [Google Tag Manager](./google-tag-manager.md) | `googleTagManager` | `necessary` | Always loads; signals Google consent |
+| Integration                                   | Helper             | Category    | Loading behavior                                 |
+| --------------------------------------------- | ------------------ | ----------- | ------------------------------------------------ |
+| [Cloudflare Zaraz](./cloudflare-zaraz.md)     | `cloudflareZaraz`  | `necessary` | Synchronizes purposes; Zaraz owns tool execution |
+| [Google Tag Manager](./google-tag-manager.md) | `googleTagManager` | `necessary` | Always loads; signals Google consent             |
 
 ## Analytics
 

package/docs/integrations/youtube.md

@@ -33,12 +33,12 @@ Render this component inside your existing consent boundary or provider.
 ```tsx title="src/consent-embed.tsx"
 'use client';
 
-import { Frame } from 'c15t/next';
+import { ConsentGate } from 'c15t/next';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -46,12 +46,12 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` keeps the iframe absent while permission is denied and removes it
 on revocation. Keep your existing consent styles and preferences dialog.
 
 **TanStack Start**
@@ -59,12 +59,12 @@ on revocation. Keep your existing consent styles and preferences dialog.
 Render this component inside your existing consent boundary or provider.
 
 ```tsx title="src/consent-embed.tsx"
-import { Frame } from 'c15t/tanstack-start';
+import { ConsentGate } from 'c15t/tanstack-start';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -72,12 +72,12 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` keeps the iframe absent while permission is denied and removes it
 on revocation. Keep your existing consent styles and preferences dialog.
 
 **React**
@@ -85,12 +85,12 @@ on revocation. Keep your existing consent styles and preferences dialog.
 Render this component inside your existing consent boundary or provider.
 
 ```tsx title="src/consent-embed.tsx"
-import { Frame } from 'c15t/react';
+import { ConsentGate } from 'c15t/react';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -98,12 +98,12 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` keeps the iframe absent while permission is denied and removes it
 on revocation. Keep your existing consent styles and preferences dialog.
 
 **Nuxt**
@@ -223,11 +223,11 @@ The provider from your quickstart supplies its consent state.
 
 ```svelte title="src/ConsentEmbed.svelte"
 <script lang="ts">
-  import { Frame } from '@c15t/svelte';
+  import { ConsentGate } from '@c15t/svelte';
   import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 </script>
 
-<Frame category={embedCategory}>
+<ConsentGate category={embedCategory}>
   <iframe
     src={embedURL}
     title={embedTitle}
@@ -238,10 +238,10 @@ The provider from your quickstart supplies its consent state.
     style:min-height="200px"
     style:border="0"
   ></iframe>
-</Frame>
+</ConsentGate>
 ```
 
-The Svelte `Frame` waits until the browser is mounted and the category is
+The Svelte `ConsentGate` waits until the browser is mounted and the category is
 allowed. Its default placeholder opens preferences. Revocation removes the
 iframe.
 
@@ -252,11 +252,11 @@ Keep the SvelteKit root provider and its server prefetch unchanged.
 
 ```svelte title="src/lib/ConsentEmbed.svelte"
 <script lang="ts">
-  import { Frame } from '@c15t/svelte';
+  import { ConsentGate } from '@c15t/svelte';
   import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
 </script>
 
-<Frame category={embedCategory}>
+<ConsentGate category={embedCategory}>
   <iframe
     src={embedURL}
     title={embedTitle}
@@ -267,10 +267,10 @@ Keep the SvelteKit root provider and its server prefetch unchanged.
     style:min-height="200px"
     style:border="0"
   ></iframe>
-</Frame>
+</ConsentGate>
 ```
 
-The Svelte `Frame` waits until the browser is mounted and the category is
+The Svelte `ConsentGate` waits until the browser is mounted and the category is
 allowed. Its default placeholder opens preferences. Revocation removes the
 iframe.
 
@@ -380,7 +380,7 @@ Set playback options in the iframe URL. For example, append `start=36` to begin
 [YouTube player parameters](https://developers.google.com/youtube/player_parameters)
 and reserve at least a 200-by-200-pixel player area.
 
-React and Svelte `Frame` components provide a blocked-state placeholder and
+React and Svelte `ConsentGate` components provide a blocked-state placeholder and
 consent action. Their `placeholder` APIs differ: React takes a node, Svelte
 takes a snippet. Keep a clear way to reopen preferences when customizing them.
 The Vue and browser examples show that action explicitly. `loading="lazy"` delays an
@@ -388,6 +388,11 @@ allowed iframe for performance; it does not implement consent gating.
 
 ## Consent behavior
 
+Add `data-vendor="youtube"` next to `data-category` and declare a `youtube`
+vendor in the runtime's `vendors` option or the backend manifest to let visitors
+turn YouTube off while keeping the rest of the category on. See
+[granular consent](./granular-consent.md).
+
 Each example keeps the iframe absent until the category is allowed. After
 permission, the iframe can load. Revoking permission removes the iframe and its
 embedded document. Requests already sent cannot be recalled.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/browser",
-	"version": "3.0.0-alpha.1",
+	"version": "3.0.0-alpha.2",
 	"description": "Drop-in consent banner and headless consent runtime for sites without a build step: Framer, Webflow, WordPress, Squarespace, and plain HTML.",
 	"keywords": [
 		"c15t",
@@ -93,12 +93,12 @@
 		"test:watch": "bun prebuild && vitest"
 	},
 	"dependencies": {
-		"@c15t/core": "3.0.0-alpha.1",
-		"@c15t/dev-tools": "3.0.0-alpha.1",
-		"@c15t/iab": "3.0.0-alpha.1",
-		"@c15t/schema": "3.0.0-alpha.0",
-		"@c15t/translations": "3.0.0-alpha.0",
-		"@c15t/ui": "3.0.0-alpha.1"
+		"@c15t/core": "3.0.0-alpha.2",
+		"@c15t/dev-tools": "3.0.0-alpha.2",
+		"@c15t/iab": "3.0.0-alpha.2",
+		"@c15t/schema": "3.0.0-alpha.1",
+		"@c15t/translations": "3.0.0-alpha.2",
+		"@c15t/ui": "3.0.0-alpha.2"
 	},
 	"devDependencies": {
 		"@c15t/conformance": "0.0.1",

package/readme.json

@@ -1,44 +0,0 @@
-{
-	"title": "@c15t/browser: Script-Tag Consent Banner",
-	"description": "Cookie banner, preference centre, and consent-gated script loading for sites without a build step: Framer, Webflow, WordPress, Squarespace, and plain HTML.",
-	"features": [
-		"One script tag from a CDN, configured with data attributes or calls queued on window.c15t",
-		"Prebuilt banner and preference centre rendered in a shadow root, immune to theme CSS",
-		"Headless build with the same runtime and window.c15t API for custom banners",
-		"data-c15t-action buttons and #c15t-preferences links wired for you",
-		"Hosted, self-hosted, offline, and manifest modes; an inlined manifest renders a location-independent policy with no request at all",
-		"DevTools panel as a second tag (c15t.devtools.js) with a Location tab for trying geo-keyed policies",
-		"Consent-gated script loading and Google Consent Mode through @c15t/scripts",
-		"ES module entry points for bundler projects without a framework"
-	],
-	"prerequisites": [
-		"A page you can add a <script> tag to",
-		"A hosted [c15t instance](https://inth.com) (free sign-up), [self-hosted deployment](https://c15t.com/docs/self-host/quickstart), or offline mode for browser-only storage"
-	],
-	"manualInstallation": [
-		"",
-		"Paste before `</head>`:",
-		"",
-		"```html\n<script\n  src=\"https://cdn.jsdelivr.net/npm/@c15t/browser@0.2.0/dist/c15t.js\"\n  data-backend-url=\"https://your-instance.c15t.dev\"\n  defer\n></script>\n```",
-		"",
-		"Drop `data-backend-url` for offline mode. Load `dist/c15t.headless.js` instead for the runtime without any UI.",
-		"",
-		"For bundler projects:",
-		"",
-		"```bash\npnpm add @c15t/browser\n```"
-	],
-	"usage": [
-		"Add the tag and reload; the banner appears on the first visit",
-		"Put `data-c15t-action=\"customize\"` on any button to open the preference centre",
-		"Read consent from `window.c15t` in your own code",
-		"For the full set of attributes and options, see the [script tag docs](https://c15t.com/docs/frameworks/javascript/script-tag)",
-		"```js\nc15t.on('consent', () => {\n  if (c15t.has('measurement')) {\n    startAnalytics();\n  }\n});\n\nawait c15t.ready();\nc15t.openDialog();\n```"
-	],
-	"docsLink": "https://c15t.com/docs/frameworks/javascript/script-tag",
-	"quickStartLink": "https://c15t.com/docs/frameworks/javascript/script-tag",
-	"showCLIGeneration": false,
-	"customSections": {
-		"Deployment Modes": "- **Hosted on inth.com**: Hosted c15t backend for policy storage, audit history, and hosted infrastructure\n- **Self-hosted backend**: Use @c15t/backend when you need full infrastructure control\n- **Manifest mode**: Inline or fetch the backend's cacheable `/manifest` and resolve the policy in the browser\n- **Offline mode**: Browser-only consent storage for portfolios, docs sites, previews, and demos",
-		"Optional IAB entry": "Load `c15t.iab.js` instead of `c15t.js`, or import `init` from `@c15t/browser/iab`. Configure `iab` with your registered CMP ID and vendor list. This entry includes the CMP, TC codec, purpose/vendor preferences, and IAB styles. The ordinary and headless entries exclude that implementation. Use `client.saveIAB()` to confirm individual IAB choices. See the [IAB script example](https://c15t.com/docs/frameworks/javascript/script-tag#optional-iab-entry)."
-	}
-}