@c15t/astro 3.0.0-alpha.0 → 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/docs/upgrade-v3.md

@@ -5,6 +5,13 @@ description: Migrate policy configuration, consent records, callbacks, and
 group: reference
 ---
 
+## React version requirement
+
+The v3 React and Next.js adapters require React and React DOM 18 or newer.
+Upgrade both packages together before installing v3. Earlier alpha peer ranges
+incorrectly allowed React 16 and 17 even though v3 already uses `useId` and
+`useSyncExternalStore`, which those versions do not provide.
+
 ## Start with a policy rule
 
 ```ts
@@ -252,6 +259,24 @@ TanStack Start (`c15t/tanstack-start`, `c15t/tanstack-start/server`):
 `consentLoaderOptions`, `backendURL`, `initRoute` and `DEFAULT_INIT_ROUTE` are
 unchanged.
 
+## `Frame` is now `ConsentGate`
+
+The component that mounts an embed only while its category is allowed is now
+`ConsentGate` in React, Next.js, TanStack Start, Svelte and Vue. The old names
+still work as deprecated aliases and will be removed in a later major release.
+
+| v2                                                                   | v3                                                                           |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `Frame`, `Frame.Root`, `Frame.Title`, `Frame.Button`                 | `ConsentGate`, `ConsentGate.Root`, `ConsentGate.Title`, `ConsentGate.Button` |
+| `FrameProps`, `FrameCompoundComponent`                               | `ConsentGateProps`, `ConsentGateCompoundComponent`                           |
+| `c15t/react/frame`, `c15t/react/components/frame`                    | `c15t/react/consent-gate`, `c15t/react/components/consent-gate`              |
+| Vue `ConsentFrame`, `@c15t/vue/runtime/components/consent-frame.vue` | `ConsentGate`, `@c15t/vue/runtime/components/consent-gate.vue`               |
+
+Props and behavior are unchanged. The placeholder keeps its `frame.*`
+translation keys, `--frame-*` CSS custom properties and
+`data-testid="frame-placeholder"`, so custom copy, styles and tests continue
+to apply.
+
 ## Next.js RSC banner removal
 
 The `@c15t/nextjs/rsc` entry (`c15t/next/rsc`) and its `RscConsentBanner`,
@@ -332,3 +357,25 @@ export function Banner() {
   );
 }
 ```
+
+## Session reports in manifest mode
+
+A host that resolves init from a cached manifest never calls `/init`, so a v3
+backend could not count the visitors it served. From this release every
+server-side resolution sends `POST /sessions` to the backend after the fact,
+server-to-server and detached from the response: the Next.js, TanStack Start,
+SvelteKit, Nuxt and Astro init routes, and the Next.js, TanStack Start and
+Astro render-time prefetches. The browser makes no request.
+
+This is a new outbound data flow from your server to the consent backend. The
+report carries the manifest revision, the matched policy, the jurisdiction,
+country, region, language and GPC signal, plus the visitor's user agent and
+address as request headers. It carries no cookies and no identifier. Nothing is
+stored on the backend; the report reaches a `sessions.onReport` sink and the
+request log.
+
+Reporting is on by default and needs an absolute backend URL. Set
+`reportSessions: false` on the adapter to send none. Each report is one
+resolution, not one visitor: a page view can produce a `render` report and a
+`route` report, and nothing in them links the two. A consumer counting sessions
+groups reports by the forwarded address and user agent within a window.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/astro",
-	"version": "3.0.0-alpha.0",
+	"version": "3.0.0-alpha.2",
 	"description": "Astro consent management: server-rendered cookie banner, on-demand Svelte, React or Vue preference-centre islands, geo-aware middleware, and consent-gated script loading.",
 	"keywords": [
 		"astro",
@@ -133,12 +133,12 @@
 		"test:watch": "vitest"
 	},
 	"dependencies": {
-		"@c15t/core": "3.0.0-alpha.0",
-		"@c15t/iab": "3.0.0-alpha.0",
-		"@c15t/schema": "3.0.0-alpha.0",
-		"@c15t/svelte": "3.0.0-alpha.0",
-		"@c15t/translations": "3.0.0-alpha.0",
-		"@c15t/ui": "3.0.0-alpha.0"
+		"@c15t/core": "3.0.0-alpha.2",
+		"@c15t/iab": "3.0.0-alpha.2",
+		"@c15t/schema": "3.0.0-alpha.1",
+		"@c15t/svelte": "3.0.0-alpha.2",
+		"@c15t/translations": "3.0.0-alpha.2",
+		"@c15t/ui": "3.0.0-alpha.2"
 	},
 	"devDependencies": {
 		"@c15t/conformance": "0.0.1",
@@ -153,8 +153,8 @@
 		"vue": "^3.5.0"
 	},
 	"peerDependencies": {
-		"@c15t/react": "^3.0.0-alpha.0",
-		"@c15t/vue": "^3.0.0-alpha.0",
+		"@c15t/react": "^3.0.0-alpha.2",
+		"@c15t/vue": "^3.0.0-alpha.2",
 		"astro": "^5.0.0",
 		"react": "^18.0.0 || ^19.0.0",
 		"react-dom": "^18.0.0 || ^19.0.0",

package/src/components/islands/panel-surface.tsx

@@ -22,13 +22,61 @@ import {
 	ConsentDraftProvider,
 	ConsentProvider,
 } from '@c15t/react';
-import { lazy, Suspense } from 'react';
+import { useEffect, useState } from 'react';
+import type { ComponentType } from 'react';
 
 import type { DialogPresentationOptions } from '../../ui/provider-props';
+import type { IABDialogSurfaceProps } from './iab-dialog-surface';
 
 // The TCF surface is the larger half of this island and only an IAB site
 // ever opens it, so it arrives on its own chunk.
-const IABDialogSurface = lazy(() => import('./iab-dialog-surface'));
+let loadedIABSurface: ComponentType<IABDialogSurfaceProps> | undefined;
+let iabSurfacePromise:
+	| Promise<ComponentType<IABDialogSurfaceProps>>
+	| undefined;
+const loadIABSurface = () => {
+	iabSurfacePromise ??= (async () => {
+		const module = await import('./iab-dialog-surface');
+		loadedIABSurface = module.default;
+		return loadedIABSurface;
+	})();
+	return iabSurfacePromise;
+};
+
+// This island only mounts in the browser. Resolve its component through state
+// so the first open does not wait for React's Suspense retry throttle.
+const IABDialogSurface = (props: IABDialogSurfaceProps) => {
+	const [loadedComponent, setLoadedComponent] = useState(
+		() => loadedIABSurface
+	);
+	const [failure, setFailure] = useState<{ error: unknown }>();
+	useEffect(() => {
+		if (loadedComponent) {
+			return;
+		}
+		let active = true;
+		void (async () => {
+			try {
+				const loaded = await loadIABSurface();
+				if (active) {
+					setLoadedComponent(() => loaded);
+				}
+			} catch (error) {
+				if (active) {
+					setFailure({ error });
+				}
+			}
+		})();
+		return () => {
+			active = false;
+		};
+	}, [loadedComponent]);
+	if (failure) {
+		throw failure.error;
+	}
+	const Component = loadedComponent;
+	return Component ? <Component {...props} /> : null;
+};
 
 /** Props the React dialog adapter passes in. */
 export interface ConsentDialogSurfaceProps {
@@ -53,9 +101,7 @@ const ConsentDialogSurface = ({
 		options={options}
 	>
 		{kind === 'iab' ? (
-			<Suspense fallback={null}>
-				<IABDialogSurface tab={tab} />
-			</Suspense>
+			<IABDialogSurface tab={tab} />
 		) : (
 			<ConsentDraftProvider>
 				<ConsentDialog />