c15t 2.0.4 → 2.1.0

package/docs/script-loader.md

@@ -2,9 +2,9 @@
 title: Script Loader
 description: Gate third-party scripts behind consent — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
 ---
-The script loader manages third-party scripts based on consent state. Scripts are defined in the provider's `scripts` option and are automatically loaded when their required consent category is granted, and unloaded when consent is revoked.
+The script loader manages third-party JavaScript based on consent state. You declare scripts in your provider's `scripts` option, and c15t decides when each script should load, stay loaded, unload, or receive a consent update.
 
-c15t has a collection of premade scripts available in `@c15t/scripts`. Check the [integrations overview](/docs/integrations/overview) first before manually building a script.
+Use it for analytics, pixels, tag managers, product analytics, and other vendor snippets that should not run until the right consent condition is satisfied. Prebuilt helpers live in [`@c15t/scripts`](/docs/integrations/overview); custom scripts can be declared directly when the vendor is specific to your app.
 
 |Package manager|Command|
 |:--|:--|
@@ -14,13 +14,13 @@ c15t has a collection of premade scripts available in `@c15t/scripts`. Check the
 |bun|`bun add @c15t/scripts`|
 
 > ℹ️ **Info:**
-> We recommend using the pre-built integrations when possible.
+> Start with the integrations overview before writing your own script. Built-in helpers encode vendor boot order, consent updates, and common defaults so you do not have to.
 >
 > ℹ️ **Info:**
-> If you need a vendor we do not ship yet, see the custom integration guide. It covers both one-off Script objects and reusable manifest-backed integrations.
+> If you need a vendor c15t does not ship yet, see the custom integration guide. It explains when a one-off Script is enough and when to build a reusable manifest-backed helper.
 >
 > ℹ️ **Info:**
-> For app-specific scripts, use a plain Script object. For reusable integrations, prefer a manifest-backed helper so startup phases, consent signaling, and future server-side loading support stay structured.
+> The script loader handles JavaScript tags and callback lifecycles. For iframe-only embeds, use the iframe blocking pattern. For UI components such as maps or video players, combine consent state with a component-level placeholder or a dedicated renderable integration.
 
 ## Basic Usage
 
@@ -44,30 +44,46 @@ const { consentStore } = getOrCreateConsentRuntime({
 });
 ```
 
-## Choose the Right Approach
+## Mental Model
 
-* Use a plain `Script` for one-off app code.
-* Use a manifest-backed helper in `@c15t/scripts` for reusable integrations, contributions, or anything that needs structured startup behavior.
+Every script you register has the same lifecycle. c15t evaluates each script against the current consent state, then drives it through a small number of states:
 
-If you are building something reusable, start with the [custom integration guide](/docs/integrations/building-integrations) before using raw callbacks.
+1. **Pending** — registered but waiting for consent. Nothing is in the DOM yet.
+2. **Loaded** — consent matched, c15t injected the script (or ran callbacks for callback-only scripts).
+3. **Updated** — already loaded, consent state changed, `onConsentChange` ran so the SDK can react.
+4. **Unloaded** — consent was revoked. c15t removed the script element unless you opted into persistence.
 
-## Reusable Integrations
+Four lifecycle callbacks let you hook into transitions: `onBeforeLoad`, `onLoad`, `onConsentChange`, and `onError`. Two flags — [`alwaysLoad`](#always-load) and [`persistAfterConsentRevoked`](#persist-after-revocation) — change how c15t treats consent boundaries. Everything else (DOM placement, ad-block evasion, dynamic management) is a refinement on top of this core model.
 
-For app-specific use, raw `Script` objects are usually enough.
+## Choose the Right Approach
 
-For reusable integrations, c15t uses a manifest-backed model in `@c15t/scripts`. That keeps startup phases, consent signaling, and vendor-specific boot logic structured instead of hidden inside large callback bodies.
+Most projects mix more than one style. Pick the smallest one that keeps consent behavior obvious:
 
-If you are building an integration for multiple apps or contributing upstream, use the [custom integration guide](/docs/integrations/building-integrations).
+|Style|Use when|
+|--|--|
+|**Built-in helper** from `@c15t/scripts`|c15t already ships the vendor. See the [integrations overview](/docs/integrations/overview).|
+|**Plain `Script`**|One-off app code with simple load and callback behavior.|
+|**Callback-only `Script`**|Another package already loaded the SDK; c15t only synchronizes consent.|
+|**Manifest-backed helper**|Reusable vendor integration with structured setup phases, queues, stubs, or a vendor consent API.|
+|**Iframe / renderable integration**|Vendor exposes an iframe or React component, not just a `<script>` tag.|
 
 ## Script Types
 
 ### Standard Scripts
 
-Load an external JavaScript file via a `<script>` tag. Use `src` to specify the URL.
+Standard scripts load an external JavaScript file via a `<script>` tag. This is the default for most analytics and pixel SDKs:
+
+```tsx
+{
+  id: 'analytics',
+  src: 'https://cdn.example.com/analytics.js',
+  category: 'measurement',
+}
+```
 
 ### Inline Scripts
 
-Execute inline JavaScript code. Use `textContent` instead of `src`:
+Inline scripts execute JavaScript from `textContent` instead of loading a URL. Use these sparingly; a manifest-backed helper is usually better for reusable vendor code.
 
 ```tsx
 {
@@ -84,7 +100,7 @@ Execute inline JavaScript code. Use `textContent` instead of `src`:
 
 ### Callback-Only Scripts
 
-Don't inject any `<script>` tag - just execute callbacks based on consent changes. Useful for controlling libraries that are already loaded:
+Callback-only scripts do not inject a script tag. They run lifecycle callbacks when consent allows them to. Use this when another package has already loaded the SDK and c15t only needs to drive consent:
 
 ```tsx
 {
@@ -106,31 +122,34 @@ Don't inject any `<script>` tag - just execute callbacks based on consent change
 }
 ```
 
-## Consent Conditions
+### Manifest-Backed Helpers
 
-The `category` field accepts a `HasCondition` - either a simple string or a logical expression:
+Built-in integrations in `@c15t/scripts` are manifest-backed. A manifest describes vendor setup as structured phases, then c15t compiles it into a `Script`. Manifests keep queue stubs, script URLs, consent signaling, and post-load work consistent across apps and they are safe to ship from a server.
 
-```tsx
-// Simple: requires measurement consent
-{ category: 'measurement' }
+Use a manifest-backed helper when:
 
-// AND: requires both measurement and marketing
-{ category: { and: ['measurement', 'marketing'] } }
+* the integration should be reused across projects,
+* the vendor snippet has ordered setup steps,
+* the vendor exposes a consent API,
+* or you plan to contribute the integration back to c15t.
 
-// OR: requires either measurement or marketing
-{ category: { or: ['measurement', 'marketing'] } }
-```
+Read the [custom integration guide](/docs/integrations/building-integrations) for the manifest contract, phases, and testing checklist.
 
-## Script Callbacks
+### Iframe And Renderable Integrations
 
-Every script supports four lifecycle callbacks:
+Some vendors are not just script tags. YouTube embeds, maps, calendars, and checkout widgets often need a visible component, a placeholder, or an iframe.
 
-|Callback|When|Use Case|
-|--|--|--|
-|`onBeforeLoad`|Before the script tag is injected|Set up global variables|
-|`onLoad`|Script loaded successfully|Initialize the library|
-|`onError`|Script failed to load|Log error, load fallback|
-|`onConsentChange`|Consent state changed (script already loaded)|Toggle tracking on/off|
+* For iframe-only embeds, gate the iframe `src` with the [iframe blocking](/docs/frameworks/react/iframe-blocking) pattern instead of loading a script just to hide an iframe.
+* For SDK-backed UI, use the script loader for the shared SDK and render the component only when consent and SDK readiness agree.
+
+## Lifecycle Callbacks
+
+Every script supports four callbacks. Each receives a `ScriptCallbackInfo` payload (id, element, hasConsent, consents):
+
+* `onBeforeLoad` — runs before the script tag is injected. Create globals, queues, or vendor stubs here.
+* `onLoad` — runs after the browser loads the script. Call vendor `init()` APIs here.
+* `onConsentChange` — runs for loaded scripts when consent changes. Forward the new consent state to the vendor SDK.
+* `onError` — runs when the script fails to load. Record diagnostics or render a fallback.
 
 ```tsx
 {
@@ -138,38 +157,60 @@ Every script supports four lifecycle callbacks:
   src: 'https://analytics.example.com/v2.js',
   category: 'measurement',
   onBeforeLoad: ({ id }) => {
-    console.log(`Loading script: ${id}`);
+    window.analyticsQueue = window.analyticsQueue || [];
   },
-  onLoad: ({ element }) => {
+  onLoad: () => {
     window.analytics.init('my-key');
   },
   onError: ({ error }) => {
     console.error('Failed to load analytics:', error);
   },
-  onConsentChange: ({ hasConsent, consents }) => {
+  onConsentChange: ({ hasConsent }) => {
     window.analytics.setConsent(hasConsent);
   },
 }
 ```
 
-## Advanced Options
+## Consent Conditions
+
+The `category` field accepts a `HasCondition`. It can be a single consent category or a logical expression:
+
+```tsx
+// Simple: requires measurement consent
+{ category: 'measurement' }
+
+// AND: requires both measurement and marketing
+{ category: { and: ['measurement', 'marketing'] } }
+
+// OR: requires either measurement or marketing
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Consent categories use the same names as the rest of c15t (`necessary`, `functionality`, `experience`, `measurement`, `marketing`).
+
+## Persistence Options
 
 ### Always Load
 
-Scripts that manage their own consent internally (like GTM in consent mode):
+`alwaysLoad` loads the script regardless of whether its category is currently granted. Use it only when the vendor must be present early **and** has a reliable consent API of its own — Google Tag Manager with Consent Mode is the canonical example.
 
 ```tsx
 {
   id: 'google-tag-manager',
   src: 'https://www.googletagmanager.com/gtm.js?id=GTM-XXXX',
   category: 'measurement',
-  alwaysLoad: true, // Loads regardless of consent state
+  alwaysLoad: true,
 }
 ```
 
+When `alwaysLoad` is on, `onConsentChange` becomes mandatory: it is how the loaded SDK learns about every transition.
+
+> ⚠️ **Warning:**
+> alwaysLoad shifts compliance responsibility to the vendor integration. Make sure the script receives denied-by-default consent signals before it can track.
+
 ### Persist After Revocation
 
-Keep the script loaded even after consent is revoked (the page won't reload for this script):
+`persistAfterConsentRevoked` keeps a script in the page after consent is revoked instead of unloading it. Use it only when the vendor exposes a runtime consent toggle — otherwise unloading is safer because removing the element guarantees the SDK stops.
 
 ```tsx
 {
@@ -177,35 +218,111 @@ Keep the script loaded even after consent is revoked (the page won't reload for
   src: 'https://errors.example.com/track.js',
   category: 'measurement',
   persistAfterConsentRevoked: true,
+  onConsentChange: ({ hasConsent }) => {
+    window.ErrorTracker.setConsent(hasConsent);
+  },
 }
 ```
 
-### Script Placement
+As with `alwaysLoad`, `onConsentChange` is how the persisted SDK learns about consent updates.
+
+### `alwaysLoad` vs `persistAfterConsentRevoked`
 
-Control where in the DOM the script is injected:
+These two flags answer different questions. Use this table to keep them straight:
+
+|Question|`alwaysLoad`|`persistAfterConsentRevoked`|
+|--|--|--|
+|Loads before consent is granted?|Yes|No (waits for consent like a normal script)|
+|Stays loaded after consent is revoked?|Yes|Yes|
+|Requires a vendor consent API?|Yes|Yes|
+
+## DOM Placement
+
+Control where the script is injected and whether the element id is anonymized:
 
 ```tsx
 {
   id: 'widget',
   src: 'https://widget.example.com/embed.js',
   category: 'experience',
-  target: 'body', // 'head' (default) or 'body'
+  target: 'body',     // 'head' (default) or 'body'
+  anonymizeId: true,  // default: true, hides the c15t script id from ad blockers
+  nonce: 'abc123',    // optional CSP nonce
 }
 ```
 
-### Ad Blocker Evasion
+Set `anonymizeId: false` only when another script or test needs a stable DOM id. Pass `nonce` when your CSP requires it; c15t applies it directly to the generated `<script>` element.
+
+## Dynamic Management
 
-Script element IDs are anonymized by default to avoid ad blocker pattern matching:
+Framework packages expose script-manager methods so integrations can be added, removed, or inspected at runtime. Use this for tenant-specific tools, feature-flagged scripts, or vendors that are configured after sign-in:
+
+* `setScripts(scripts)` — registers script definitions and immediately evaluates them against consent.
+* `removeScript(id)` — removes a definition and unloads its element if needed.
+* `isScriptLoaded(id)` — returns whether c15t has loaded a script.
+* `getLoadedScriptIds()` — returns every currently loaded script id.
+
+Dynamic scripts should still use stable ids. If the same vendor is added repeatedly with different ids, c15t treats each call as a new script.
+
+## Calling Vendor APIs From Your App
+
+The script loader controls **when the vendor SDK loads**. It does not intercept calls your application code makes to that SDK afterwards. Whether your event calls are safe before consent is granted depends on the script's persistence flags:
+
+|Vendor pattern|What c15t does|What your app code must do|
+|--|--|--|
+|Consent-gated load, unloaded on revoke (e.g. cookieless analytics)|Script not in DOM until consent granted; removed on revoke. Global is `undefined` outside that window.|**Guard every call.** Unguarded `window.vendor.track(...)` throws when the global is absent.|
+|Consent-gated load with `persistAfterConsentRevoked` (e.g. Meta Pixel)|Script not in DOM until consent granted; stays after revoke. c15t calls vendor's consent-revoke API on revocation.|Guard calls only for the pre-initial-consent window. Once loaded, the SDK handles its own suppression.|
+|`alwaysLoad: true` with a vendor consent API (e.g. GTM, gtag, Databuddy, PostHog)|Script in DOM on page start; c15t signals consent state through the vendor's API.|Calls are safe — the vendor SDK suppresses transmission when consent is denied.|
+|No app-facing API (e.g. Cloudflare Web Analytics)|Script in/out of DOM based on consent. Tracking is fully automatic.|Nothing to guard.|
+
+The safe pattern in React is to read consent state through `useConsentManager().has(category)` before calling the SDK:
 
 ```tsx
-{
-  id: 'analytics',
-  src: '...',
-  category: 'measurement',
-  anonymizeId: true, // default: true
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+
+function useTrackSignup() {
+  const { has } = useConsentManager();
+
+  return useCallback(() => {
+    if (has('measurement')) {
+      window.fathom?.trackEvent('signup');
+    }
+  }, [has]);
+}
+
+function SignupButton() {
+  const trackSignup = useTrackSignup();
+
+  return <button onClick={trackSignup}>Sign up</button>;
 }
 ```
 
+From non-React code, read the consent store directly:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window.fathom?.trackEvent('signup');
+}
+```
+
+Each [integration page](/docs/integrations/overview) includes a vendor-specific **Tracking events in your app** block that names which pattern applies.
+
+## Debugging Checklist
+
+When a script does not behave as expected:
+
+1. Confirm the script's `category` matches the consent that has been granted.
+2. Check whether the script is `alwaysLoad` or consent-gated.
+3. Confirm `onBeforeLoad` creates any globals before the vendor code reads them.
+4. Confirm `onConsentChange` updates persisted or always-loaded scripts when consent changes.
+5. Check whether the browser or an ad blocker blocked the request.
+6. Use c15t devtools to inspect script lifecycle events when available.
+
 ## Dynamic Script Management
 
 Add, remove, or check scripts at runtime via the store:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "c15t",
-	"version": "2.0.4",
+	"version": "2.1.0",
 	"description": "Headless cookie banner, consent manager & preference center for JavaScript / TypeScript. GDPR, CCPA, LGPD and IAB TCF compliant.",
 	"keywords": [
 		"consent",
@@ -74,8 +74,8 @@
 		"not op_mini all"
 	],
 	"dependencies": {
-		"@c15t/schema": "2.0.1",
-		"@c15t/translations": "2.0.0",
+		"@c15t/schema": "2.1.0",
+		"@c15t/translations": "2.1.0",
 		"zustand": "5.0.12"
 	},
 	"devDependencies": {