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

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**
@@ -176,7 +176,7 @@ Add this component to pages using your consent-enabled base layout:
 <c15t-consent-embed style="display: block"></c15t-consent-embed>
 
 <script>
-  import { getConsentClient } from '@c15t/astro/client';
+  import { getConsentClient } from 'c15t/astro/client';
   import { mountConsentEmbed } from '../consent-embed';
 
   class ConsentEmbed extends HTMLElement {
@@ -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
@@ -80,6 +87,115 @@ be true before a visitor acts. A notice dismissal updates `noticeDismissal` and
 does not record consent. Global Privacy Control updates privacy signals and
 configured opt-out directives without turning a browser signal into a choice.
 
+## Replace `useConsentManager()`
+
+`useConsentManager()` is gone from `c15t/react`, `c15t/next`,
+`c15t/tanstack-start` and their `/headless` entries. It subscribed to the whole
+consent snapshot, so every component that called it re-rendered on every
+change, including changes to categories it never read. Call one hook per field
+instead; each re-renders only when its own value changes.
+
+Before, in v2 and earlier v3 alphas:
+
+```tsx title="components/marketing-banner.tsx"
+import { useConsentManager } from 'c15t/react';
+
+export function MarketingBanner() {
+  const { activeUI, has, saveConsents } = useConsentManager();
+  if (activeUI !== 'banner' || has('marketing')) {
+    return null;
+  }
+  return <button type="button" onClick={() => void saveConsents('all')}>Accept</button>;
+}
+```
+
+After:
+
+```tsx title="components/marketing-banner.tsx"
+import { useActiveUI, useConsent } from 'c15t/react';
+import { useHeadlessConsentUI } from 'c15t/react/headless';
+
+export function MarketingBanner() {
+  const activeUI = useActiveUI();
+  const marketing = useConsent('marketing');
+  const { performAction } = useHeadlessConsentUI();
+  if (activeUI !== 'banner' || marketing) {
+    return null;
+  }
+  return <button type="button" onClick={() => void performAction('accept')}>Accept</button>;
+}
+```
+
+Import hooks from the same entry you used for `useConsentManager()`:
+`c15t/next` and `c15t/next/headless` in Next.js, `c15t/tanstack-start` and
+`c15t/tanstack-start/headless` in TanStack Start.
+
+| `useConsentManager()` field                                   | v3 replacement                                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `activeUI`                                                    | `useActiveUI()`. It returns `null` before the kernel picks a surface; the old field reported `'none'`. |
+| `setActiveUI(ui)`                                             | `useSetActiveUI()`                                                                                     |
+| `has(category)`                                               | `useConsent(category)`, one call per category at the top of the component                              |
+| `consents`                                                    | `useConsents()`                                                                                        |
+| `effectivePermissions`                                        | `useEffectivePermissions()`                                                                            |
+| `explicitChoice`                                              | `useExplicitChoice()`                                                                                  |
+| `promptRequirement`                                           | `usePromptRequirement()`                                                                               |
+| `noticeDismissal`                                             | `useNoticeDismissal()`                                                                                 |
+| `privacySignals`                                              | `usePrivacySignals()`                                                                                  |
+| `optOutDirectives`                                            | `useOptOutDirectives()`                                                                                |
+| `restrictions`                                                | `useRestrictions()`                                                                                    |
+| `resolution`                                                  | `usePolicyResolution()`                                                                                |
+| `policyRule`                                                  | `usePolicyRule()`                                                                                      |
+| `policyCategories`                                            | `usePolicyCategories()`. The old list started with `'necessary'`; this one does not.                   |
+| `policyScopeMode`                                             | `usePolicyScopeMode()`                                                                                 |
+| `policyBanner`                                                | `usePromptPresentation()`                                                                              |
+| `policyDialog`                                                | `usePreferencesPresentation()`                                                                         |
+| `model`                                                       | `useModel()`. It returns `null` while no policy matches; the old field reported `'opt-in'`.            |
+| `branding`                                                    | `useBranding()`. It returns `null` when unset; the old field reported `'c15t'`.                        |
+| `iab`                                                         | `useIABSnapshot()`                                                                                     |
+| `vendors`                                                     | `useDeclaredVendors()`                                                                                 |
+| `vendorChoice`                                                | `useVendorChoice()`                                                                                    |
+| `getDisplayedVendors(category)`                               | `useDeclaredVendors()`, filtered to vendors whose category condition names the category                |
+| `subscribeToConsentChanges(listener)`                         | `useSubscribeToConsentChanges()`, or the provider's `onPermissionsChanged` callback                    |
+| `updateConsentCategories(categories)`                         | `useRegisterConsentCategories()`                                                                       |
+| `translationConfig`                                           | `useTranslations()` for the active strings                                                             |
+| `selectedConsents`, `selectedConsentTypes`                    | `useConsentDraft().values`                                                                             |
+| `setSelectedConsent(name, value)`                             | `useConsentDraft().set(name, value)`                                                                   |
+| `selectedVendors`                                             | `useConsentDraft().vendors`, or `useVendorDraft().vendors`                                             |
+| `setSelectedVendor(id, granted)`                              | `useConsentDraft().setVendor(id, granted)`                                                             |
+| `resetDraft()`                                                | `useConsentDraft().reset()`                                                                            |
+| `draftIsStale`                                                | `useConsentDraft().isStale`                                                                            |
+| `consentCategories`, `consentTypes`, `getDisplayedConsents()` | `useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`             |
+| `saveConsents('all')`                                         | `useHeadlessConsentUI().performAction('accept')`                                                       |
+| `saveConsents('necessary')`                                   | `useHeadlessConsentUI().performAction('reject')`                                                       |
+| `saveConsents('custom')`                                      | `useHeadlessConsentUI().performAction('save')`                                                         |
+| `manager`                                                     | Nothing. It was always `null` in v3.                                                                   |
+
+The old hook kept one private draft per component, shared by its selection and
+its save. `useConsentDraft()` and `useHeadlessConsentUI()` read the nearest
+`ConsentDraftProvider` instead. When one component stages choices and another
+saves them, or one component calls both hooks, render them inside the same
+`ConsentDraftProvider`; without one, each hook keeps its own draft and a custom
+save commits nothing you staged. `ConsentWidget` already provides one.
+
+`useHeadlessConsentUI()` saves the way the stock buttons do: it closes the
+surface after a successful save and refuses a draft that the policy made stale.
+`useSaveConsents()` calls the kernel directly and does neither.
+
+The CLI rewrites the common destructuring forms for you:
+
+```bash
+c15t codemods use-consent-manager-to-hooks --dry-run --json
+```
+
+It replaces each field that has a one-hook equivalent, turns `has('marketing')`
+calls with a literal category into `useConsent('marketing')`, and maps
+`saveConsents('all' | 'necessary' | 'custom')` calls to
+`useHeadlessConsentUI().saveCustomPreferences()`. Fields it cannot rewrite stay
+on a `useConsentManager()` call under a `TODO(c15t v3)` comment that names the
+replacement, so the build fails at each place that needs manual work. It also
+marks components that now need a shared `ConsentDraftProvider`. Review the
+result, then run it without `--dry-run`.
+
 ## Replace choice callbacks
 
 ```tsx
@@ -184,7 +300,7 @@ Notice acknowledgement uses `common.acknowledge`, falling back to
 
 ```astro
 ---
-import ConsentBanner from '@c15t/astro/components/consent-banner.astro';
+import ConsentBanner from 'c15t/astro/components/consent-banner.astro';
 ---
 
 <ConsentBanner dismissButtonText="Got it" />
@@ -252,6 +368,43 @@ 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.
+
+## Split dialog and widget entries are deferred
+
+`c15t/react/consent-dialog` and `c15t/react/consent-widget` (and their
+`@c15t/react/*` equivalents) now export the same deferred `ConsentDialog` and
+`ConsentWidget` as `c15t/react`. The dialog's code loads when it first opens
+instead of with every page. `<ConsentDialog />`, `<ConsentWidget />` and the
+`ConsentDialog.<Part>` properties need no change.
+
+The two entries no longer export the individual parts. Import those from the
+component entries, which keep the old, eagerly bundled exports:
+
+| Before                                                          | After                                                                      |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `import { Card, Header } from 'c15t/react/consent-dialog'`      | `import { Card, Header } from 'c15t/react/components/consent-dialog'`      |
+| `import { Accordion, Switch } from 'c15t/react/consent-widget'` | `import { Accordion, Switch } from 'c15t/react/components/consent-widget'` |
+
+To keep the dialog in the first load so its first open needs no download,
+import `ConsentDialog` from `c15t/react/components/consent-dialog`.
+
 ## Next.js RSC banner removal
 
 The `@c15t/nextjs/rsc` entry (`c15t/next/rsc`) and its `RscConsentBanner`,
@@ -332,3 +485,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/scripts",
-	"version": "3.0.0-alpha.0",
+	"version": "3.0.0-alpha.2",
 	"description": "Consent-aware script integrations for Google Tag Manager, Google Consent Mode v2, GA4, Google Ads, Meta Pixel, and more.",
 	"keywords": [
 		"adobe-analytics",
@@ -26,6 +26,7 @@
 		"logrocket",
 		"meta-pixel",
 		"microsoft-uet",
+		"pinterest-tag",
 		"pirsch",
 		"posthog",
 		"privacy",
@@ -133,6 +134,11 @@
 			"import": "./dist/vendors/analytics/mixpanel-analytics.js",
 			"default": "./dist/vendors/analytics/mixpanel-analytics.js"
 		},
+		"./one-dollar-stats": {
+			"types": "./dist-types/vendors/analytics/one-dollar-stats.d.ts",
+			"import": "./dist/vendors/analytics/one-dollar-stats.js",
+			"default": "./dist/vendors/analytics/one-dollar-stats.js"
+		},
 		"./pirsch": {
 			"types": "./dist-types/vendors/analytics/pirsch.d.ts",
 			"import": "./dist/vendors/analytics/pirsch.js",
@@ -178,11 +184,21 @@
 			"import": "./dist/vendors/functional/crisp.js",
 			"default": "./dist/vendors/functional/crisp.js"
 		},
+		"./front-chat": {
+			"types": "./dist-types/vendors/functional/front-chat.d.ts",
+			"import": "./dist/vendors/functional/front-chat.js",
+			"default": "./dist/vendors/functional/front-chat.js"
+		},
 		"./intercom": {
 			"types": "./dist-types/vendors/functional/intercom.d.ts",
 			"import": "./dist/vendors/functional/intercom.js",
 			"default": "./dist/vendors/functional/intercom.js"
 		},
+		"./cloudflare-zaraz": {
+			"types": "./dist-types/vendors/tag-managers/cloudflare-zaraz.d.ts",
+			"import": "./dist/vendors/tag-managers/cloudflare-zaraz.js",
+			"default": "./dist/vendors/tag-managers/cloudflare-zaraz.js"
+		},
 		"./google-tag-manager": {
 			"types": "./dist-types/vendors/tag-managers/google-tag-manager.d.ts",
 			"import": "./dist/vendors/tag-managers/google-tag-manager.js",
@@ -203,6 +219,11 @@
 			"import": "./dist/vendors/ads-and-pixels/openai-pixel.js",
 			"default": "./dist/vendors/ads-and-pixels/openai-pixel.js"
 		},
+		"./pinterest-tag": {
+			"types": "./dist-types/vendors/ads-and-pixels/pinterest-tag.d.ts",
+			"import": "./dist/vendors/ads-and-pixels/pinterest-tag.js",
+			"default": "./dist/vendors/ads-and-pixels/pinterest-tag.js"
+		},
 		"./reddit-pixel": {
 			"types": "./dist-types/vendors/ads-and-pixels/reddit-pixel.d.ts",
 			"import": "./dist/vendors/ads-and-pixels/reddit-pixel.js",
@@ -237,6 +258,11 @@
 			"types": "./dist-types/*.d.ts",
 			"import": "./dist/*.js",
 			"default": "./dist/*.js"
+		},
+		"./events": {
+			"types": "./dist-types/events.d.ts",
+			"import": "./dist/events.js",
+			"default": "./dist/events.js"
 		}
 	},
 	"publishConfig": {
@@ -254,8 +280,10 @@
 		"test:live-vendors": "bun --tsconfig-override live-vendors/tsconfig.json live-vendors/runner.ts",
 		"test:watch": "vitest"
 	},
+	"dependencies": {
+		"@c15t/core": "3.0.0-alpha.3"
+	},
 	"devDependencies": {
-		"@c15t/core": "3.0.0-alpha.0",
 		"@c15t/typescript-config": "0.0.1",
 		"@c15t/vitest-config": "1.0.0",
 		"playwright": "1.58.2",

package/readme.json

@@ -1,19 +0,0 @@
-{
-	"title": "@c15t/scripts: Prebuilt Consent Scripts",
-	"description": "Consent-aware script integrations for Google Tag Manager, Google Consent Mode v2, GA4, Google Ads, Meta Pixel, analytics tools, pixels, tag managers, and widgets.",
-	"features": [
-		"Prebuilt script loaders for popular analytics, advertising, marketing, and functional tools",
-		"Google Tag Manager support with Google Consent Mode v2 defaults and consent updates",
-		"Google Analytics 4 and Google Ads support through gtag.js",
-		"Consent-gated Meta Pixel and conversion pixel loading",
-		"Easy integration with c15t's script loader",
-		"Configuration options for each supported vendor",
-		"Supported vendors include Google Tag Manager, Meta Pixel, OpenAI Pixel, Amplitude, Heap, PostHog, TikTok Pixel, LinkedIn Insights, Microsoft UET, X Pixel, Reddit Pixel, Snapchat Pixel, Intercom, Crisp, and more"
-	],
-	"docsLink": "https://c15t.com/docs/integrations",
-	"showCLIGeneration": false,
-	"customSections": {
-		"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))\n- **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))\n- **Conversion pixels**: Meta Pixel, OpenAI Pixel, TikTok Pixel, LinkedIn Insights, Microsoft UET (Microsoft Ads), X Pixel, Reddit Pixel, Snapchat Pixel\n- **Analytics**: PostHog, Amplitude, Heap, Segment, RudderStack, Hightouch, Mixpanel, Microsoft Clarity, Hotjar, Plausible, Fathom, Matomo, Umami, Vercel Analytics\n- **Chat widgets**: Intercom, Crisp",
-		"Example": "```ts\nimport { googleTagManager } from '@c15t/scripts/google-tag-manager'\nimport { metaPixel } from '@c15t/scripts/meta-pixel'\n\nconst scripts = [\n  googleTagManager({ id: 'GTM-XXXXXX' }),\n  metaPixel({ pixelId: '000000000000000' }),\n]\n```"
-	}
-}