@c15t/scripts 2.2.0 → 3.0.0-alpha.1

package/docs/integrations/building-integrations.md

@@ -1,239 +1,52 @@
 ---
-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
+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
-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:
+import type { Script } from 'c15t/modules/script-loader';
 
-```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:
-
-```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:
-
-```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
+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.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Add `vendor: 'example-analytics'` and declare the vendor in the runtime's
+`vendors` option or in the backend manifest when visitors should be able to
+turn this vendor off inside a granted category. See
+[granular consent](./granular-consent.md).
 
-\*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/clear-on-revocation.md

@@ -0,0 +1,167 @@
+---
+title: Clear on revocation
+description: Remove configured first-party cookies and Web Storage keys when
+  their consent category is denied.
+group: integrations
+---
+
+## Configure cleanup
+
+Add `clearOnRevocation` to your provider or runtime options. Declare only the
+data owned by each optional category:
+
+```ts
+import { hosted, type ClearOnRevocationConfig } from 'c15t';
+import { createConsentRuntime } from 'c15t/runtime';
+
+const clearOnRevocation = {
+	measurement: {
+		cookies: ['_ga', '_ga_*'],
+		localStorage: ['analytics:*'],
+	},
+	marketing: {
+		cookies: ['_fbp'],
+		sessionStorage: ['campaign-id'],
+	},
+} satisfies ClearOnRevocationConfig;
+
+const runtime = createConsentRuntime({
+	mode: hosted({ url: '/api/c15t' }),
+	clearOnRevocation,
+});
+
+// Start in the browser after mount. The endpoint must serve your c15t backend.
+runtime.start();
+
+// Call runtime.dispose() when the app no longer needs consent management.
+```
+
+For React, pass the same configuration through `ConsentProvider.options`:
+
+```tsx
+import type { ReactNode } from 'react';
+import { ConsentProvider, hosted } from 'c15t/react';
+
+const mode = hosted({ url: '/api/c15t' });
+
+export function Consent({ children }: { children: ReactNode }) {
+	return (
+		<ConsentProvider
+			options={{
+				mode,
+				clearOnRevocation: {
+					measurement: { cookies: ['_ga', '_ga_*'] },
+				},
+			}}
+		>
+			{children}
+		</ConsentProvider>
+	);
+}
+```
+
+The same option is available in Next.js and TanStack Start `ConsentRoot` props, Vue and
+Nuxt configuration, Svelte providers, and Astro integration options. Solid and
+other headless integrations can use `createConsentRuntime` as shown above.
+Every adapter uses the same cleanup module.
+
+Omitting `clearOnRevocation` leaves cleanup disabled. The provider option is
+initial-only. Remount the provider to replace its cleanup configuration. For
+a shared runtime, configure the runtime owner rather than a borrowing provider.
+
+## Matching names and cookie scopes
+
+Use an exact string or a nonempty prefix followed by `*`. `_ga_*` matches
+`_ga_ABC123`; it does not match `_ga`. Regular expressions, wildcards in other
+positions, and a bare `*` are unsupported. Web Storage keys may contain spaces,
+Unicode, and punctuation. Cookie names use their raw spelling, without URL
+decoding.
+
+Cookies can share a name while having different domains or paths. Cleanup
+tries the current host and its parent domains, and the current path and its
+ancestors. To target a specific scope, use an object:
+
+```ts
+const clearOnRevocation = {
+	measurement: {
+		cookies: [
+			{ name: 'analytics-id', domain: 'example.com', path: '/' },
+			{ name: 'checkout-metrics', domain: '', path: '/checkout' },
+			{ name: 'partitioned-metrics', partitioned: true },
+		],
+	},
+};
+```
+
+An empty `domain` means host-only. Explicit domains and paths replace the
+automatic attempts for that field. Exact names can be deleted at a configured
+path even when the current page cannot read that cookie. Prefix matching can
+only discover cookie names visible to the current page, so use an exact name
+for a cookie on another path.
+
+Partitioned cookies require `partitioned: true`; ordinary targets remove
+unpartitioned cookies. Cookie deletion preserves the browser's `__Secure-`
+and `__Host-` prefix requirements. c15t protects its own consent, notice,
+privacy, pending-save, and IAB consent records in cookies and localStorage,
+including configured custom storage keys, even if your patterns match them.
+c15t does not store consent in sessionStorage, so targeted entries there are
+removed even when their names match consent storage keys.
+
+## When cleanup runs
+
+The runtime attaches cleanup after persistence and the script loader. Cleanup
+waits while the policy is pending. On the first settled snapshot, it removes
+configured data for every denied category. This includes a new opt-in visitor
+who has not made a choice and a returning visitor whose permission expired.
+
+After that first pass, cleanup runs when a category changes from allowed to
+denied. Saving a refusal, expiry, a policy change, Global Privacy Control,
+or synchronized records can cause that transition. Under an opt-out policy,
+an expired grant that remains effectively allowed does not trigger deletion.
+The `necessary` category cannot be configured for cleanup.
+
+Cleanup keeps waiting if a failed initial request leaves the policy pending.
+If a previously settled policy falls back to denial after an initialization
+failure, cleanup removes its configured data. A later successful retry cannot
+restore deleted data.
+
+Runtime construction, server rendering, draft checkbox edits, opening the
+dialog, and disposal do not clear data. Cleanup does not poll storage or repeat
+on unrelated UI updates.
+
+## Use an existing kernel
+
+For a manually assembled integration, attach the module in the browser after
+persistence hydration and script-loader setup:
+
+```ts
+import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';
+
+const cleanup = createClearOnRevocation({
+	kernel,
+	config: { measurement: { cookies: ['_ga', '_ga_*'] } },
+	storageConfig,
+});
+
+// Stop observing consent when this integration is torn down.
+cleanup.dispose();
+```
+
+Here `kernel` is your existing consent kernel. Pass the same `storageConfig`
+used by persistence so cleanup protects custom record keys. Attaching the
+module can immediately clear denied categories if the policy is already
+settled. Do not also attach it when your provider or runtime owns cleanup.
+
+## Browser limits
+
+Cleanup can remove JavaScript-accessible first-party cookies and keys in the
+current origin's `localStorage` and `sessionStorage`. It cannot remove
+`HttpOnly` cookies or another origin's data. Keep `HttpOnly` protections and
+use your server to expire cookies that require server access. Cookie deletion
+must match the cookie's scope. See the
+[browser cookie documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
+
+Browser restrictions can prevent reads or deletions. Cleanup failures do not
+block consent updates. A running SDK may write data again after a sweep, so
+keep script gating and the integration's consent-change or teardown behavior
+configured. Deleting a script element cannot undo JavaScript it already ran.