@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/building-integrations.md

@@ -1,239 +1,47 @@
 ---
-title: Build a Custom Script Integration
-description: Learn when to use a raw Script, when to build a reusable
-  manifest-backed integration, and how to debug and test custom consent-aware
-  scripts in c15t.
+title: Custom integrations
+description: Define loading, initialization and consent-change behavior for a
+  vendor without a helper.
 group: integrations
 ---
-If you cannot find a prebuilt integration in [`@c15t/scripts`](/docs/integrations), you have two good options:
 
-1. Build a one-off `Script` object directly in your app.
-2. Build a reusable manifest-backed integration helper.
+## Start with a script configuration
 
-Use the first option for app-specific scripts. Use the second option when you want something reusable, testable, and aligned with c15t's manifest system.
-
-## Choose the Right Level
-
-### One-off app script
-
-Use a raw `Script` when:
-
-* the integration is only used in one app
-* the vendor setup is small
-* you do not need to publish or share the helper
-
-```ts
-import type { Script } from 'c15t';
-
-export function acmeAnalytics(siteId: string): Script {
-  return {
-    id: 'acme-analytics',
-    src: `https://cdn.acme.com/analytics.js?site=${siteId}`,
-    category: 'measurement',
-    onBeforeLoad: () => {
-      window.acmeQueue = window.acmeQueue || [];
-    },
-    onConsentChange: ({ hasConsent }) => {
-      window.acme?.setConsent(hasConsent);
-    },
-  };
-}
-```
-
-### Reusable manifest-backed integration
-
-Use a manifest-backed helper when:
-
-* you want to contribute to `@c15t/scripts`
-* you want the integration to be reusable across apps
-* you need structured startup/setup phases
-* you want compatibility with c15t's server-side support for script loading
-
-Manifest integrations should be declarative, serializable, and built from structured steps rather than raw inline JavaScript strings.
-
-## Manifest Contract
-
-Every reusable manifest carries two contract fields:
-
-* `kind`: identifies the payload as a c15t vendor manifest
-* `schemaVersion`: identifies which manifest schema the runtime should compile
-
-Use `vendorManifestContract` so helpers stay aligned with the runtime's current contract:
-
-```ts
-const acmeManifest = {
-  ...vendorManifestContract,
-  vendor: 'acme-analytics',
-  // ...
-} as const satisfies VendorManifest;
-```
-
-If manifests are sent from a server later, these fields are how the client can validate that it knows how to interpret the payload before executing anything.
-
-## Manifest Mental Model
-
-The manifest runtime executes a script in ordered phases:
-
-* `bootstrap`: globals or stubs that must exist before anything else
-* `install`: startup steps plus a single `loadScript`
-* `afterLoad`: work that should run after the external script loads
-* `onBeforeLoadGranted` / `onBeforeLoadDenied`: initial consent-specific setup
-* `onLoadGranted` / `onLoadDenied`: post-load consent-specific setup
-* `onConsentChange`: runs on every consent update
-* `onConsentGranted` / `onConsentDenied`: branch-specific consent updates
-
-For vendors with explicit consent APIs, you can also use:
-
-* `consentMapping`
-* `consentSignal`
-* `consentSignalTarget`
-
-That is how the Google integrations map c15t consent categories to Consent Mode v2 and inject `default` and `update` signals in the correct phase order.
-
-`category` supports the same consent condition model as a plain `Script`, so manifests can represent simple or nested rules such as:
+Check the installed `@c15t/scripts` exports first. For an unlisted SDK, define a
+stable ID, category and source URL, then pass the configuration to the existing
+provider or loader:
 
 ```ts
-category: { and: ['measurement', { not: 'marketing' }] }
-```
-
-## Structured Steps
-
-Prefer structured steps over raw script text. The current manifest DSL supports patterns like:
-
-* `setGlobal`
-* `setGlobalPath`
-* `defineQueueFunction`
-* `defineStubFunction`
-* `pushToQueue`
-* `callGlobal`
-* `defineQueueMethods`
-* `defineGlobalMethods`
-* `constructGlobal`
-* `loadScript`
-
-These steps are easier to validate, test, debug, and eventually transport from the server.
-
-## Example Manifest Integration
-
-If you are building a reusable helper, the pattern looks like this:
+import type { Script } from 'c15t/modules/script-loader';
 
-```ts
-import type { Script } from 'c15t';
-import { resolveManifest } from '@c15t/scripts/resolve';
-import {
-  vendorManifestContract,
-  type VendorManifest,
-} from '@c15t/scripts/types';
-
-const acmeManifest = {
-  ...vendorManifestContract,
-  vendor: 'acme-analytics',
+export const analyticsScript = {
+  id: 'example-analytics',
   category: 'measurement',
-  bootstrap: [
-    {
-      type: 'setGlobal',
-      name: 'acmeQueue',
-      value: [],
-      ifUndefined: true,
-    },
-    {
-      type: 'defineQueueFunction',
-      name: 'acme',
-      queue: 'acmeQueue',
-      ifUndefined: true,
-    },
-  ],
-  install: [
-    {
-      type: 'callGlobal',
-      global: 'acme',
-      args: ['init', '{{siteId}}'],
-    },
-    {
-      type: 'loadScript',
-      src: 'https://cdn.acme.com/analytics.js?site={{siteId}}',
-      async: true,
-    },
-  ],
-  onConsentGranted: [
-    {
-      type: 'callGlobal',
-      global: 'acme',
-      args: ['consent', true],
-    },
-  ],
-  onConsentDenied: [
-    {
-      type: 'callGlobal',
-      global: 'acme',
-      args: ['consent', false],
-    },
-  ],
-} as const satisfies VendorManifest;
-
-export function acmeAnalytics(siteId: string): Script {
-  return resolveManifest(acmeManifest, { siteId });
-}
+  src: 'https://analytics.example.com/sdk.js',
+  onLoad() {
+    // Initialize the vendor here using its documented API.
+  },
+  onError({ error }) {
+    console.error('Analytics SDK failed to load', error);
+  },
+} satisfies Script;
 ```
 
-## Design Guidelines
-
-When building an integration, prefer these rules:
-
-* Keep helper logic thin. Put behavior in the manifest, not in post-resolution callback mutation.
-* Keep manifests serializable. Avoid helper-only runtime branches where possible.
-* Use explicit config inputs. Avoid generic override bags when a named option is clearer.
-* Use `alwaysLoad` only when the vendor truly manages its own consent correctly.
-* Use `persistAfterConsentRevoked` only when the vendor exposes a real consent toggle and does not need a full reload.
-* Keep vendor-specific naming out of the core DSL when a generic step can express it.
-
-## Testing Checklist
-
-At minimum, test these flows:
-
-1. Initial page load with consent denied.
-2. Initial page load with consent granted.
-3. Consent granted after the script was previously denied.
-4. Consent revoked after the script was previously active.
-5. Existing script element reuse if the script persists after revocation.
-6. Error handling if the vendor global or loader is missing.
-
-If you are contributing to `@c15t/scripts`, add focused engine/helper tests similar to the existing tests in `packages/scripts/src/engine.test.ts` and `packages/scripts/src/helpers.test.ts`.
-
-## Debugging
-
-Use `@c15t/dev-tools` while implementing and testing integrations.
-
-The scripts panel now shows:
-
-* whether a script is loaded, pending, or blocked
-* grouped activity for `onBeforeLoad`, `onLoad`, and `onConsentChange`
-* manifest phase activity such as `bootstrap`, `consent-default`, `setup`, and `afterLoad`
-
-The events panel also records script lifecycle and manifest step events, which is useful when a vendor reads consent too early or a startup step runs in the wrong order.
-
-## When to Stop and Use a Plain Script
-
-Not every integration needs a reusable manifest helper.
-
-If the vendor snippet is tiny, unique to one app, or mostly static, a plain `Script` object in your runtime options is usually the simpler choice. Reach for the manifest system when you need reuse, consistency, structured startup behavior, or a path to server-driven manifests.
-
-## Reference Types
-
-### Script
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Replace the example URL and implement the vendor's initialization. This is a
+loader template, not a functioning analytics SDK. The script stays blocked
+while measurement permission is denied.
 
-\*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.\*
+## Define revocation deliberately
 
-### VendorManifest
+`onConsentChange` receives current permission information. Use it to update the
+vendor's consent API or disable future work. `persistAfterConsentRevoked` retains
+a loaded script when set; `alwaysLoad` bypasses initial category gating. Enable
+those only when the vendor's own consent behavior matches the intended design.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`VendorManifest\`|
-|Source Path|\`./packages/scripts/src/types.ts\`|
+For a library imported elsewhere, `callbackOnly` allows lifecycle callbacks
+without inserting a script element. It does not prevent that earlier import
+from running. For SDKs with side effects at import time, defer the import too.
 
-\*ExtractedTypeTable: Could not extract "VendorManifest" from "./packages/scripts/src/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+A browser cannot undo executed JavaScript merely by removing its script tag.
+Test cleanup, queued events, re-grant and navigation. Use the provider's nonce
+option or a per-script nonce for a nonce-based Content Security Policy.

package/docs/integrations/clearbit.md

@@ -1,130 +1,291 @@
 ---
 title: Clearbit
-description: Visitor and company enrichment loaded with Clearbit's account-keyed
-  tags.js snippet.
+description: Configure Clearbit with c15t v3, understand marketing permission
+  and verify loading and revocation.
 group: integrations
-icon: clearbit
 ---
-[Clearbit](https://clearbit.com) provides visitor and company enrichment for go-to-market workflows. The official embed loads `https://tag.clearbitscripts.com/v1/{publishableKey}/tags.js` with a `referrerpolicy` of `strict-origin-when-cross-origin`.
 
-## Integrate with c15t
+## Configure Clearbit
 
-**React**
+Use the publishable key from your Clearbit tag installation. The helper loads the account-specific `tags.js` URL. Do not put a secret enrichment API key in browser code.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { clearbit } from '@c15t/scripts/clearbit';
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-const scripts = [
-  clearbit({
-    publishableKey: 'YOUR_PUBLISHABLE_KEY',
-  }),
-];
+```ts title="src/consent-scripts.ts"
+import { clearbit } from '@c15t/scripts/clearbit';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [clearbit({ publishableKey: 'YOUR_PUBLISHABLE_KEY' })];
 ```
 
+## 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 c15t owns loading once.
+
+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.
+
 **Next.js**
 
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+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 { clearbit } from '@c15t/scripts/clearbit';
+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 = [
-  clearbit({
-    publishableKey: 'YOUR_PUBLISHABLE_KEY',
-  }),
-];
+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).
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+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 { clearbit } from '@c15t/scripts/clearbit';
+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';
+
+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>
+```
+
+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**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```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';
+
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    clearbit({
-      publishableKey: 'YOUR_PUBLISHABLE_KEY',
-    }),
-  ],
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
 });
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-## How c15t loads it
+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).
 
-* **Category:** `marketing` (Analytics discovery, marketing-sensitive consent)
-* **Loads when:** marketing consent is granted
-* **On revocation:** unloaded — c15t removes the script element from the DOM.
+**Astro**
 
-Clearbit enrichment tools are privacy-sensitive because they can identify visitors and companies for profiling, enrichment, and intent use cases. The GitHub issue left the category open between measurement and marketing; c15t defaults this integration to `marketing` because enrichment is not just aggregate measurement. The script stays blocked until marketing consent is granted. On revocation c15t removes the script element it created; tags that Clearbit's loader has already appended can keep running until the next page load (c15t reloads the page on revocation by default), so treat the load gate as the consent boundary.
+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:
 
-The helper maps Clearbit's official snippet:
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
 
-```ts
-clearbit({
-  publishableKey: 'YOUR_PUBLISHABLE_KEY',
-})
+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>
 ```
 
-To proxy or self-host the loader, pass a custom URL:
+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
-clearbit({
-  publishableKey: 'YOUR_PUBLISHABLE_KEY',
-  scriptUrl: 'https://analytics.example.com/clearbit-tags.js',
-})
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
 ```
 
-## Types
+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).
+
+## Options
 
-### ClearbitOptions
+| Option           | Behavior                                                                   |
+| ---------------- | -------------------------------------------------------------------------- |
+| `publishableKey` | Required non-empty publishable key.                                        |
+| `scriptUrl`      | Optional full loader override; otherwise derived from the publishable key. |
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`ClearbitOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/clearbit.ts\`|
+## Consent behavior
 
-\*ExtractedTypeTable: Could not extract "ClearbitOptions" from "./packages/scripts/src/vendors/analytics/clearbit.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Clearbit is listed under Analytics for discovery, but its helper uses marketing permission because it performs enrichment. The helper has no vendor revocation callback; do not assume removing the tag stops an enrichment SDK that already ran.
 
-### Script
+## Verify the integration
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Check the account key in the requested loader URL and inspect enrichment requests. Confirm marketing rejection prevents the initial load, even when measurement is allowed.
 
-\*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.\*
+Use a fresh session with an opt-in policy to check initial denial. Then grant
+`marketing`, revoke it, and reload. Inspect both network requests and future
+application events. Removing a script cannot undo code or requests that already
+ran. Follow the [consent verification guide](../guides/verify-consent.md).