@c15t/scripts 2.2.0 → 3.0.0-alpha.1

package/docs/integrations/google-tag.md

@@ -1,134 +1,305 @@
 ---
-title: GA4 + Google Ads (gtag.js)
-description: Send data to Google Analytics 4 and Google Ads with automatic
-  Consent Mode v2 support.
-icon: google-analytics
+title: Google Tag
+description: Configure gtag with c15t Consent Mode signals and understand its
+  loading behavior.
 group: integrations
 ---
-Google Tag (`gtag.js`) is Google's unified tracking script for sending data to Google Analytics 4 (GA4), Google Ads, and Floodlight. It measures user behavior, tracks conversions, and powers Google's advertising ecosystem.
 
-c15t initializes Google Tag with Consent Mode v2 defaults set to denied and automatically updates the consent state when users make choices. You don't need to configure Google Consent Mode yourself.
+## Register gtag
 
-> ℹ️ **Info:**
-> Use GTM if your team needs centralized tag management in the GTM UI. Use gtag.js if you only need GA4/Google Ads directly in code. Don't run both for the same destination unless intentional, or you may duplicate events.
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-**Choosing the right category:**
+```ts title="src/consent-scripts.ts"
+import { gtag } from '@c15t/scripts/google-tag';
 
-* Use `category: 'measurement'` for analytics-only tracking (GA4 events)
-* Use `category: 'marketing'` for advertising and conversion tracking (Google Ads)
+export const scripts = [gtag({ id: 'G-XXXXXXXXXX', category: 'measurement' })];
+```
 
-## Integrate with c15t
+Use your Google tag ID and pass `scripts` to the existing provider options.
+Choose `marketing` for a configuration whose purpose is advertising. The
+category describes the integration but does not override `alwaysLoad`.
+Remove a separately installed `gtag.js` snippet or a duplicate tag-manager
+configuration before testing.
 
-**React**
+## Register the scripts
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { gtag } from '@c15t/scripts/google-tag';
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry so c15t owns loading once.
 
-const scripts = [
-  gtag({
-    id: 'G-XXXXXXXXXX',
-    category: 'measurement', // or 'marketing'
-  }),
-];
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
 ```
 
-**Next.js**
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
 
 ```tsx
-'use client';
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { gtag } from '@c15t/scripts/google-tag';
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
+
+**TanStack Start**
 
-const scripts = [
-  gtag({
-    id: 'G-XXXXXXXXXX',
-    category: 'measurement', // or 'marketing'
-  }),
-];
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+function Root() {
+  const state = Route.useLoaderData();
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
   );
 }
 ```
 
-**JavaScript**
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
 
 ```ts
-import { getOrCreateConsentRuntime } from 'c15t';
-import { gtag } from '@c15t/scripts/google-tag';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
+
+**Nuxt**
+
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    gtag({
-      id: 'G-XXXXXXXXXX',
-      category: 'measurement', // or 'marketing'
-    }),
-  ],
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
 });
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-## How c15t loads it
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+
+**Vue**
 
-* **Category:** configurable — `measurement` (default, Analytics) or `marketing`
-* **Loads when:** [`alwaysLoad`](/docs/frameworks/react/script-loader#always-load) — runs on page start regardless of consent state, with Consent Mode v2 defaults set to denied
-* **On consent change:** [persists](/docs/frameworks/react/script-loader#persist-after-revocation) — c15t pushes a Consent Mode v2 `update` to gtag instead of removing the script
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-## Tracking events in your app
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
 
-`gtag.js` is `alwaysLoad: true`, so `window.gtag` is present from page start regardless of consent. Calls like `gtag('event', 'sign_up')` are **safe at any time** — c15t sets Consent Mode v2 defaults to denied before the user makes a choice, and Google's SDK suppresses transmission of events while the relevant consent is denied. When consent later changes, c15t emits a Consent Mode v2 `update` so events fire correctly going forward.
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
+
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
+
+**Astro**
+
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
+
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
+
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
+
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
+
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
+
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**JavaScript**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
 
 ```ts
-window.gtag?.('event', 'sign_up', { method: 'email' });
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
 ```
 
-You do not need to wrap `gtag(...)` calls in a `useConsentManager().has(...)` check — Consent Mode handles the suppression for you.
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
 
-## Types
+## Consent Mode is not a zero-request gate
 
-### GtagOptions
+This helper sets `alwaysLoad: true`. It prepares the Google queue, sends consent
+defaults and updates, and loads Google's script even before a visitor makes a
+choice. That is different from preventing any request to Google until consent.
+Google describes the distinction in its
+[Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode).
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`GtagOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/google-tag.ts\`|
+The default mapping is:
 
-\*ExtractedTypeTable: Could not extract "GtagOptions" from "./packages/scripts/src/vendors/analytics/google-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+| c15t category   | Google consent types                               |
+| --------------- | -------------------------------------------------- |
+| `necessary`     | `security_storage`                                 |
+| `functionality` | `functionality_storage`                            |
+| `measurement`   | `analytics_storage`                                |
+| `marketing`     | `ad_storage`, `ad_user_data`, `ad_personalization` |
+| `experience`    | `personalization_storage`                          |
 
-### Script
+`consentMapping` replaces the mapping when supplied. Keep the full set of
+signals your integration needs. Test both default and update commands and the
+actual tag behavior. Do not infer a saved grant from an allowed default under an
+opt-out policy.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+## Test event delivery
 
-\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Confirm the initial consent command precedes configuration and event commands.
+Then reject, grant and revoke permission and inspect updates. Test page-view
+behavior during client navigation so a separate routing integration does not
+send duplicate events or bypass your chosen consent behavior.

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](../frameworks/next/script-loader.md#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.