@c15t/react 3.1.0 → 3.2.0

package/docs/integrations/building-integrations.md

@@ -36,22 +36,22 @@ with your framework, follow any vendor guide, for example
 
 ## Script fields
 
-| Field                                           | Default                | Behavior                                                                                                              |
-| ----------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `id`                                            | Required               | Stable identifier. c15t tracks the script by it across renders.                                                       |
-| `category`                                      | Required               | A category name, or a condition such as `{ or: ['measurement', 'marketing'] }`, `{ and: [...] }` or `{ not: '...' }`. |
-| `src` / `textContent`                           | None                   | Set exactly one, unless `callbackOnly` is `true`.                                                                     |
-| `vendor`                                        | None                   | Vendor slug, so a visitor can turn this vendor off inside an allowed category.                                        |
-| `callbackOnly`                                  | `false`                | Run callbacks without adding a script element.                                                                        |
-| `alwaysLoad`                                    | `false`                | Load regardless of permission.                                                                                        |
-| `persistAfterConsentRevoked`                    | `false`                | Keep the script element when permission is revoked.                                                                   |
-| `onBeforeLoad`, `onLoad`, `onError`             | None                   | Run before the element is added, after it loads, and if it fails.                                                     |
-| `onConsentChange`                               | None                   | Runs when permissions change after the script has loaded, and when it is removed.                                     |
-| `onDispose`                                     | None                   | Runs when this configuration is removed or its loader is disposed. Revocation alone does not call it.                 |
-| `target`                                        | `'head'`               | `'head'` or `'body'`.                                                                                                 |
-| `async`, `defer`, `attributes`, `fetchPriority` | None                   | Copied to the script element.                                                                                         |
-| `nonce`                                         | The provider's `nonce` | Content Security Policy nonce for this element.                                                                       |
-| `anonymizeId`                                   | `true`                 | Use a random element ID. Set `false` for `c15t-script-<id>`.                                                          |
+| Field                                           | Default                | Behavior                                                                                                                                                                 |
+| ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                                            | Required               | Stable identifier. c15t tracks the script by it across renders.                                                                                                          |
+| `category`                                      | Required               | A category name, or a condition such as `{ or: ['measurement', 'marketing'] }`, `{ and: [...] }` or `{ not: '...' }`.                                                    |
+| `src` / `textContent`                           | None                   | Set exactly one, unless `callbackOnly` is `true` or returns `true`.                                                                                                      |
+| `vendor`                                        | None                   | Vendor slug, so a visitor can turn this vendor off inside an allowed category.                                                                                           |
+| `callbackOnly`                                  | `false`                | `true` or a zero-argument predicate returning `true` runs callbacks without adding a script element.                                                                     |
+| `alwaysLoad`                                    | `false`                | Load regardless of permission.                                                                                                                                           |
+| `persistAfterConsentRevoked`                    | `false`                | `true` keeps the element after withdrawal, including pending downloads. `'loaded'` keeps only elements whose load event completed; pending and failed loads are removed. |
+| `onBeforeLoad`, `onLoad`, `onError`             | None                   | Run before the element is added, after it loads, and if it fails.                                                                                                        |
+| `onConsentChange`                               | None                   | Runs when permissions change after the script has loaded, and when it is removed.                                                                                        |
+| `onDispose`                                     | None                   | Runs when this configuration is removed or its loader is disposed. Revocation alone does not call it.                                                                    |
+| `target`                                        | `'head'`               | `'head'` or `'body'`.                                                                                                                                                    |
+| `async`, `defer`, `attributes`, `fetchPriority` | None                   | Copied to the script element.                                                                                                                                            |
+| `nonce`                                         | The provider's `nonce` | Content Security Policy nonce for this element.                                                                                                                          |
+| `anonymizeId`                                   | `true`                 | Use a random element ID. Set `false` for `c15t-script-<id>`.                                                                                                             |
 
 Every callback receives `{ id, elementId, hasConsent, consents }`, plus
 `vendor` when the script declares one, and `element` for scripts with an
@@ -137,6 +137,19 @@ a callback-only script runs `onBeforeLoad` and `onLoad` only once permission is
 allowed. [PostHog](./posthog.md#use-an-existing-posthog-sdk) shows
 this pattern with a real SDK.
 
+For runtime detection, `callbackOnly` also accepts a zero-argument function
+that returns a boolean. c15t evaluates it before each new mount, when reading
+diagnostics, and when selecting scripts for server startup. Return `true` to
+use callbacks alone, or `false` to load `src` or `textContent`. Keep the function
+free of side effects and safe to call on the server. It can run more than once,
+and it does not remove an element already mounted by that registration.
+A function survives script customization with object spread, so later mounts
+check the current runtime instead of a value captured when the copy was made.
+Keep the function reference stable across script updates, for example by
+defining it at module level. A new function counts as a resource change and
+remounts the registration. If a predicate throws during server startup, c15t
+leaves that script to the client loader and starts unrelated scripts normally.
+
 ## Revocation and verification
 
 By default c15t reloads the page when a visitor turns off a category or vendor

package/docs/integrations/clay.md

@@ -0,0 +1,305 @@
+---
+title: Clay
+description: Load Clay web intent only after marketing consent and understand
+  its storage and revocation limits.
+seoTitle: Clay web intent consent with c15t
+seoDescription: Gate Clay visitor identification on marketing consent with c15t
+  and verify the loader, storage and revocation behavior.
+icon: radar
+group: integrations
+---
+
+The `clay` helper waits for `marketing` consent before loading Clay web intent.
+Clay resolves visitors' IP addresses to companies and can use device fingerprints
+and identifiers from other vendors for sales profiling.
+
+## Configure Clay
+
+Copy the `id` from Settings > Web intent > JavaScript Snippet. Remove any direct
+Clay snippet or GTM copy so it cannot bypass c15t.
+
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
+
+```ts title="src/consent-scripts.ts"
+import { clay } from '@c15t/integrations/clay';
+
+export const scripts = [clay({ siteId: 'YOUR_SITE_ID' })];
+```
+
+## Register the scripts
+
+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 the vendor loads only through c15t.
+
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
+in the Next.js guide, add the helper to that array instead of creating a
+second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
+
+**Next.js**
+
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
+
+export default defineConsentConfig({ scripts });
+```
+
+Keep the rest of your config, such as `mode` and `routePrefix`, in the
+same call. `ConsentRoot` reads the config in the browser, so the layout
+keeps passing only `state`. App Router, Pages Router and static export all
+read the same file. See
+[Next.js scripts and embeds](https://c15t.com/docs/frameworks/next/scripts).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader from the
+[TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../consent-scripts';
+
+<ConsentRoot state={consent} scripts={scripts}>
+```
+
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](https://c15t.com/docs/frameworks/tanstack-start/scripts).
+
+**React**
+
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
+
+```tsx title="src/consent.tsx"
+import { scripts } from './consent-scripts';
+
+<ConsentProvider options={{ mode, scripts }}>
+```
+
+`mode` is the `manifest()` value from the
+[React quickstart](../frameworks/react/quickstart.md). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
+
+**Nuxt**
+
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from '../src/consent-scripts';
+
+export default defineAppConfig({
+  c15t: { scripts },
+});
+```
+
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](https://c15t.com/docs/frameworks/nuxt/scripts).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep your existing `mode` and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](https://c15t.com/docs/frameworks/vue/scripts).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
+which the integration finds on its own. Keep `astro.config.mjs` as it is.
+If the module already exports scripts, combine the two arrays.
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
+`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 { ConsentProvider, manifest } from 'c15t/svelte';
+  import { scripts } from './consent-scripts';
+</script>
+
+<ConsentProvider mode={manifest()} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentProvider>
+```
+
+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 `ConsentRoot` in the root layout. Keep the
+handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentRoot } from 'c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+</script>
+
+<ConsentRoot state={data.consent} {scripts}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentRoot>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](https://c15t.com/docs/frameworks/html/scripts).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
+
+```ts
+import { init, manifest } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep the mode from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](https://c15t.com/docs/frameworks/javascript/scripts).
+
+## Options
+
+| Option      | Default                                             | Behavior                                                                                                                                                 |
+| ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `siteId`    | Required                                            | Public ID from Clay's snippet. Trimmed and URL-encoded. Non-string, blank or invalid IDs log an error and skip loading.                                  |
+| `scriptUrl` | `https://static.claydar.com/init.v1.js?id=<siteId>` | Override for a proxy or pinned loader. Keep the `id` query parameter because Clay reads `document.currentScript.src`. A blank override uses the default. |
+
+## Loading and revocation
+
+The loader runs from a real script element in the body after marketing consent.
+It loads `cdn.claydar.com/releases/latest/radar.min.js`, which sends data to
+`api.claydar.com`. Include those hosts in the matching CSP directives.
+Measurement consent alone loads nothing. Clay's own CMP detection does not cover
+c15t.
+
+On load, the helper queues `giveCookieConsent`. On withdrawal it calls
+`denyCookieConsent` when available. These methods were verified in the served
+tracker, but Clay does not document them. Denial moves identifiers from persistent
+storage into session storage. It does not stop requests. Keep c15t's default
+`reloadOnConsentRevoked` behavior enabled. With reload disabled, the tracker can
+continue sending events until navigation. Removing its loader cannot unload the
+tracker or its child scripts.
+
+The served tracker uses `claydar_*` cookies and local storage, including a device
+ID cookie with a one-year lifetime. It also uses `radar_sn_*` session keys for
+fingerprints, `spotter_data` for company lookup and a temporary `__sn_tld_probe`
+cookie. Account settings and future vendor versions can change this inventory.
+
+## Verify Clay
+
+Filter Network by `claydar.com`. Denial and measurement-only consent must show no
+requests, no `Claydar` global and no vendor storage. Grant marketing and confirm
+one `init.v1.js?id=<siteId>` loader plus the tracker. Withdraw consent and confirm
+the page reloads, then confirm Clay stays blocked on the new page.
+
+The monitor uses a placeholder site ID. Successful loader and tracker execution
+does not establish account configuration or successful company identification.
+
+Sources: [Clay Web intent](https://university.clay.com/docs/website-tracking),
+[Clay's Web intent announcement](https://www.clay.com/blog/web-intent),
+[loader](https://static.claydar.com/init.v1.js), and
+[served tracker](https://cdn.claydar.com/releases/latest/radar.min.js).
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper lists its vendor by name in the preference dialog, so a visitor can
+turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.

package/docs/integrations/clearbit.md

@@ -165,7 +165,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -184,7 +184,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();
@@ -249,7 +249,7 @@ A kernel you create yourself needs a loader from
 
 `clearbit` uses the `marketing` category, not `measurement`. Clearbit
 identifies visitors and their companies for enrichment, so c15t treats it as
-marketing even though these docs list it with analytics. The `tags.js` script
+marketing. The `tags.js` script
 loads with `referrerpolicy="strict-origin-when-cross-origin"` only while
 marketing is allowed. On revocation the helper removes the script element and
 calls no Clearbit API.

package/docs/integrations/cloudflare-web-analytics.md

@@ -166,7 +166,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -185,7 +185,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();

package/docs/integrations/cloudflare-zaraz.md

@@ -206,7 +206,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -225,7 +225,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();

package/docs/integrations/crisp.md

@@ -164,7 +164,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -183,7 +183,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();