@c15t/scripts 2.1.0 → 2.2.0-canary-20260804162155

package/dist-types/vendors/tag-managers/google-tag-manager.d.ts

@@ -14,44 +14,44 @@ declare global {
  * - Signals consent state via `gtag('consent', 'default'|'update', ...)`
  */
 export declare const googleTagManagerManifest: {
-    readonly vendor: "google-tag-manager";
-    readonly category: "necessary";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'google-tag-manager';
+    readonly category: 'necessary';
     readonly alwaysLoad: true;
     readonly bootstrap: [{
-        readonly type: "setGlobal";
-        readonly name: "dataLayer";
+        readonly type: 'setGlobal';
+        readonly name: 'dataLayer';
         readonly value: readonly [];
         readonly ifUndefined: true;
     }, {
-        readonly type: "defineQueueFunction";
-        readonly name: "gtag";
-        readonly queue: "dataLayer";
+        readonly type: 'defineQueueFunction';
+        readonly name: 'gtag';
+        readonly queue: 'dataLayer';
         readonly ifUndefined: true;
     }];
     readonly install: [{
-        readonly type: "pushToQueue";
-        readonly queue: "dataLayer";
+        readonly type: 'pushToQueue';
+        readonly queue: 'dataLayer';
         readonly value: {
             readonly 'gtm.start': {
                 readonly kind: "c15t.runtime-value";
-                readonly value: "timestamp";
+                readonly value: 'timestamp';
             };
-            readonly event: "gtm.js";
+            readonly event: 'gtm.js';
         };
     }, {
-        readonly type: "loadScript";
-        readonly src: "https://www.googletagmanager.com/gtm.js?id={{id}}";
+        readonly type: 'loadScript';
+        readonly src: 'https://www.googletagmanager.com/gtm.js?id={{id}}';
         readonly async: true;
     }];
     readonly onConsentChange: [{
-        readonly type: "callGlobal";
-        readonly global: "gtag";
+        readonly type: 'callGlobal';
+        readonly global: 'gtag';
         readonly args: ["event", "{{updateEventName}}"];
     }];
     readonly consentMapping: Record<string, string[]>;
-    readonly consentSignal: "gtag";
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
+    readonly consentSignal: 'gtag';
 };
 export interface GoogleTagManagerOptions {
     /**

package/docs/README.md

@@ -0,0 +1,62 @@
+# @c15t/scripts
+
+> Consent-aware script integration docs for analytics, advertising pixels, tag managers, widgets, and custom loaders.
+
+These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
+
+## Frameworks
+
+Install and configure c15t in JavaScript, React, and Next.js applications.
+
+- [Script Loader](./frameworks/javascript/script-loader.md): Gate third-party scripts behind consent — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+- [Script Loader](./frameworks/next/script-loader.md): Gate third-party scripts behind consent in Next.js — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+- [Script Loader](./frameworks/react/script-loader.md): Gate third-party scripts behind consent in React — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+
+## Integrations
+
+Connect analytics, advertising, maps, media, and other third-party tools behind consent.
+
+- [Adobe Analytics](./integrations/adobe-analytics.md): Adobe Analytics loaded through an Adobe Experience Platform Data Collection Tags embed URL.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
+- [Amplitude](./integrations/amplitude.md): Load Amplitude Browser SDK 2 with c15t and gate product analytics behind measurement consent.
+- [Build a Custom Script Integration](./integrations/building-integrations.md): 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.
+- [Clearbit](./integrations/clearbit.md): Visitor and company enrichment loaded with Clearbit's account-keyed tags.js snippet.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Cookieless analytics from Cloudflare with a prebuilt helper that serializes the beacon config into the `data-cf-beacon` attribute.
+- [Crisp](./integrations/crisp.md): Load Crisp live chat with website ID, runtime, cookie, and session options.
+- [Databuddy](./integrations/databuddy.md): Databuddy is a privacy-focused analytics platform that helps you understand user behavior and track events. It supports cookieless tracking and manages consent automatically through c15t's consent state synchronization.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that maps Fathom's data attributes into a c15t-managed script.
+- [Google Maps](./integrations/google-maps.md): Render Google Maps only after consent with one shared Maps JavaScript API loader and independently managed map instances.
+- [GA4 + Google Ads (gtag.js)](./integrations/google-tag.md): Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Deploy and manage marketing tags centrally with automatic consent state synchronization.
+- [Heap](./integrations/heap.md): Load Heap with c15t and gate autocapture product analytics behind measurement consent.
+- [Hightouch](./integrations/hightouch.md): Load Hightouch Events with c15t and gate the browser SDK behind measurement consent.
+- [Hotjar](./integrations/hotjar.md): Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
+- [Intercom](./integrations/intercom.md): Bootstrap Intercom settings and load the messenger widget bundle.
+- [LinkedIn Insights](./integrations/linkedin-insights.md): Track conversions and build matched audiences for LinkedIn advertising campaigns.
+- [LogRocket](./integrations/logrocket.md): Session replay and monitoring loaded after measurement consent with LogRocket's browser SDK.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
+- [Meta Pixel](./integrations/meta-pixel.md): Track conversions and build audiences for Facebook and Instagram advertising campaigns.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Session replay and behavior analytics with a prebuilt helper that keeps Clarity consent synchronized with c15t measurement state.
+- [Microsoft UET](./integrations/microsoft-uet.md): Track conversions and measure performance for Microsoft Advertising and Bing Ads.
+- [Mixpanel Analytics](./integrations/mixpanel-analytics.md): Load Mixpanel with c15t and let Mixpanel's own opt-in and opt-out APIs follow measurement consent.
+- [Integrations](./integrations/overview.md): Load analytics, pixels, tag managers, and widgets through c15t so consent state controls when they run, update, and appear in your consent UI.
+- [Pirsch](./integrations/pirsch.md): Privacy-friendly, cookieless analytics loaded with Pirsch's fixed script id and identification-code attributes.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that preserves Plausible's queue bootstrap and loader attributes.
+- [PostHog](./integrations/posthog.md): PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
+- [Promptwatch](./integrations/promptwatch.md): Promptwatch analyzes traffic on your site for Artificial Intelligence (AI) traffic and usage insights. Data is stored in the EU without user-identifiable information.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Track conversions and build retargeting audiences for Reddit advertising campaigns.
+- [RudderStack](./integrations/rudderstack.md): Load RudderStack's JavaScript SDK with c15t and gate the browser SDK behind measurement consent.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Privacy-friendly analytics with script-tag configuration via Rybbit's data attributes.
+- [Segment](./integrations/segment.md): Load Segment Analytics.js with c15t and gate it behind measurement consent.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Measure Snapchat ad performance and build remarketing audiences with a prebuilt pixel helper.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Measure ad performance and build audiences for TikTok advertising campaigns.
+- [Umami Analytics](./integrations/umami-analytics.md): Open-source, cookieless analytics with a prebuilt helper that maps Umami's data attributes into a c15t-managed script.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Bootstrap Vercel Analytics with a declarative queue and script attributes.
+- [X Pixel (Twitter Pixel)](./integrations/x-pixel.md): Track conversions and build audiences for advertising campaigns on X (formerly Twitter).
+- [YouTube](./integrations/youtube.md): Keep YouTube iframes unmounted until consent with a privacy-enhanced, lazy-loaded React or Next.js embed.
+
+## Reference
+
+Concepts, legal templates, open-source policies, and contributor documentation.
+
+- [Script Loader](./shared/react/guides/script-loader.md): Reference page for script loader.

package/docs/frameworks/javascript/script-loader.md

@@ -0,0 +1,356 @@
+---
+title: Script Loader
+description: Gate third-party scripts behind consent — load Google Analytics,
+  Meta Pixel, and other tracking scripts only when users grant permission.
+group: frameworks
+---
+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.
+
+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.
+
+<PackageCommandTabs mode="install" command="@c15t/scripts" />
+
+> ℹ️ **Info:**
+> 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.
+>
+> 📝 **Note:**
+> 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:**
+> 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
+
+Pass an array of `Script` objects to the runtime options:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { metaPixel } from '@c15t/scripts/meta-pixel';
+
+const { consentStore } = getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    metaPixel({ pixelId: '123456' }),
+    {
+      id: 'custom-analytics',
+      src: 'https://cdn.example.com/analytics.js',
+      category: 'measurement',
+    },
+  ],
+});
+```
+
+## Mental Model
+
+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:
+
+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.
+
+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.
+
+## Choose the Right Approach
+
+Most projects mix more than one style. Pick the smallest one that keeps consent behavior obvious:
+
+|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
+
+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
+
+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
+{
+  id: 'gtag-config',
+  textContent: `
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXXX');
+  `,
+  category: 'measurement',
+}
+```
+
+### Callback-Only Scripts
+
+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
+{
+  id: 'posthog-consent',
+  callbackOnly: true,
+  category: 'measurement',
+  onLoad: ({ hasConsent }) => {
+    if (hasConsent) {
+      posthog.opt_in_capturing();
+    }
+  },
+  onConsentChange: ({ hasConsent }) => {
+    if (hasConsent) {
+      posthog.opt_in_capturing();
+    } else {
+      posthog.opt_out_capturing();
+    }
+  },
+}
+```
+
+### Manifest-Backed Helpers
+
+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.
+
+Use a manifest-backed helper when:
+
+* 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.
+
+Read the [custom integration guide](/docs/integrations/building-integrations) for the manifest contract, phases, and testing checklist.
+
+### Iframe And Renderable Integrations
+
+Some vendors are not just script tags. YouTube embeds, maps, calendars, and checkout widgets often need a visible component, a placeholder, or an iframe.
+
+* 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.
+* Use `YouTubeEmbed` for the iframe-only YouTube candidate and `GoogleMap` for the callback-based SDK candidate.
+* Use `useConsentScript()` when building custom wrappers. It registers scripts through the consent store, follows `loadedScripts`, and returns a promise-shaped readiness contract for callback-based SDKs.
+
+## 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
+{
+  id: 'analytics',
+  src: 'https://analytics.example.com/v2.js',
+  category: 'measurement',
+  onBeforeLoad: ({ id }) => {
+    window.analyticsQueue = window.analyticsQueue || [];
+  },
+  onLoad: () => {
+    window.analytics.init('my-key');
+  },
+  onError: ({ error }) => {
+    console.error('Failed to load analytics:', error);
+  },
+  onConsentChange: ({ hasConsent }) => {
+    window.analytics.setConsent(hasConsent);
+  },
+}
+```
+
+## 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
+
+`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,
+}
+```
+
+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
+
+`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
+{
+  id: 'error-tracking',
+  src: 'https://errors.example.com/track.js',
+  category: 'measurement',
+  persistAfterConsentRevoked: true,
+  onConsentChange: ({ hasConsent }) => {
+    window.ErrorTracker.setConsent(hasConsent);
+  },
+}
+```
+
+As with `alwaysLoad`, `onConsentChange` is how the persisted SDK learns about consent updates.
+
+### `alwaysLoad` vs `persistAfterConsentRevoked`
+
+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'
+  anonymizeId: true,  // default: true, hides the c15t script id from ad blockers
+  nonce: 'abc123',    // optional CSP nonce
+}
+```
+
+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.
+
+You usually do not need a per-script `nonce`. Setting `nonce` once on the provider covers every injected script (and the theme stylesheet); a per-script value overrides it for that script alone.
+
+## Dynamic Management
+
+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
+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:
+
+```ts
+const state = consentStore.getState();
+
+// Add scripts dynamically
+state.setScripts([
+  { id: 'dynamic', src: 'https://cdn.example.com/widget.js', category: 'measurement' },
+]);
+
+// Remove a script
+state.removeScript('dynamic');
+
+// Check if a script is loaded
+const loaded = state.isScriptLoaded('custom-analytics');
+
+// Get all loaded script IDs
+const allLoaded = state.getLoadedScriptIds();
+```
+
+## API Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*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.\*