@c15t/react 2.1.0 → 2.2.0-canary-20260727202135

package/docs/{quickstart.md → frameworks/react/quickstart.md}

@@ -1,38 +1,26 @@
 ---
 title: Quickstart
 description: Add consent management to your React app in under 5 minutes.
-lastModified: 2026-02-10
-availableIn:
-  - framework: 'javascript'
-    url: '/docs/frameworks/javascript/quickstart'
-    title: 'JavaScript'
-  - framework: 'react'
-    url: '/docs/frameworks/react/quickstart'
-    title: 'React'
-  - framework: 'next'
-    url: '/docs/frameworks/next/quickstart'
-    title: 'Next.js'
+variants:
+  - value: javascript
+    href: /docs/frameworks/javascript/quickstart
+    label: JavaScript
+  - value: react
+    href: /docs/frameworks/react/quickstart
+    label: React
+  - value: next
+    href: /docs/frameworks/next/quickstart
+    label: Next.js
+group: frameworks
 ---
 ## Via CLI
 
-|Package manager|Command|
-|:--|:--|
-|npm|`npx @c15t/cli`|
-|pnpm|`pnpm dlx @c15t/cli`|
-|yarn|`yarn dlx @c15t/cli`|
-|bun|`bunx @c15t/cli`|
+<PackageCommandTabs command="@c15t/cli" />
 
 ## Manual Installation
 
 1. **Install package**
 
-   |Package manager|Command|
-   |:--|:--|
-   |npm|`npm install @c15t/react`|
-   |pnpm|`pnpm add @c15t/react`|
-   |yarn|`yarn add @c15t/react`|
-   |bun|`bun add @c15t/react`|
-
 2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
 
    ```css
@@ -42,7 +30,6 @@ availableIn:
    Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.With Tailwind v4, keep c15t at the end of the top-level @import block so Fumadocs, tw-animate-css, and other preset imports do not override c15t theme tokens.
 
    > ℹ️ Info:
-   >
    > If you are using the headless API or fully custom styling, you can skip this import. src/main.tsx should keep importing ./index.css as usual.
 
 3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
@@ -82,14 +69,12 @@ availableIn:
    ```
 
    > ℹ️ Info:
-   >
    > Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.
    >
-   > ℹ️ Info:
-   >
+   > ⚠️ Warning:
    > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.
 
-4. **Mount ConsentManager at the app root** Wrap your existing app tree with ConsentManager so all routes/components can access consent state.
+4. **Mount ConsentManager at the app root** Wrap your existing app tree with `ConsentManager` so all routes/components can access consent state.
 
    ```tsx
    import { ConsentManager } from './components/consent-manager';
@@ -105,7 +90,9 @@ availableIn:
 
 5. **Verify it works** Start your development server and confirm:
 
-   A consent banner appears at the bottom of the pageClicking "Customize" opens a dialog with toggles for each consent categoryAfter accepting or rejecting, the banner dismisses and your choice persists across page reloads
+   1. A **consent banner** appears at the bottom of the page
+   2. Clicking **"Customize"** opens a dialog with toggles for each consent category
+   3. After accepting or rejecting, the banner dismisses and your choice persists across page reloads
 
 > ℹ️ **Info:**
 > Want to improve startup performance? See Optimization for the decision guide, prefetch setup, and network tuning.
@@ -114,12 +101,7 @@ availableIn:
 
 Install DevTools only if you want a runtime inspector while building and debugging:
 
-|Package manager|Command|
-|:--|:--|
-|npm|`npm install @c15t/dev-tools`|
-|pnpm|`pnpm add @c15t/dev-tools`|
-|yarn|`yarn add @c15t/dev-tools`|
-|bun|`bun add @c15t/dev-tools`|
+<PackageCommandTabs mode="install" command="@c15t/dev-tools" />
 
 Then add it inside your existing provider:
 
@@ -143,13 +125,15 @@ import { DevTools } from '@c15t/dev-tools/react';
 
 Install c15t agent skills to let AI agents help with styling, i18n, scripts & other configuration.
 
-|Package manager|Command|
-|:--|:--|
-|npm|`npx @c15t/cli skills`|
-|pnpm|`pnpm dlx @c15t/cli skills`|
-|yarn|`yarn dlx @c15t/cli skills`|
-|bun|`bunx @c15t/cli skills`|
+<PackageCommandTabs command="@c15t/cli skills" />
 
 See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
 
 ## Next steps
+
+* [Optimization](/docs/frameworks/react/optimization)
+* [Script Loader](/docs/frameworks/react/script-loader)
+* [Styling](/docs/frameworks/react/styling/overview)
+* [Consent Categories](/docs/frameworks/react/concepts/consent-categories)
+* [Components](/docs/frameworks/react/components/consent-banner)
+* [AI Agents](/docs/ai-agents)

package/docs/{script-loader.md → frameworks/react/script-loader.md}

@@ -1,22 +1,20 @@
 ---
 title: Script Loader
-description: Gate third-party scripts behind consent in React — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+description: Gate third-party scripts behind consent in React — 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.
 
-|Package manager|Command|
-|:--|:--|
-|npm|`npm install @c15t/scripts`|
-|pnpm|`pnpm add @c15t/scripts`|
-|yarn|`yarn add @c15t/scripts`|
-|bun|`bun add @c15t/scripts`|
+<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.
 >
-> ℹ️ **Info:**
+> 📝 **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:**
@@ -184,6 +182,8 @@ Some vendors are not just script tags. YouTube embeds, maps, calendars, and chec
 
 * 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
 
@@ -418,91 +418,136 @@ export function TenantAnalytics({ siteId }: { siteId: string }) {
 
 Some vendors need a render surface as well as a script — maps, video players, calendars, and checkout widgets all fall in this bucket.
 
-Split the problem into three layers:
+Use the built-in [Google Maps](/docs/integrations/google-maps) and
+[YouTube](/docs/integrations/youtube) renderable helpers when they fit:
+
+```tsx
+import { GoogleMap, YouTubeEmbed } from '@c15t/react';
+
+function Page() {
+  const googleMapsApiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
+
+  return (
+    <>
+      {googleMapsApiKey && (
+        <GoogleMap
+          apiKey={googleMapsApiKey}
+          authReferrerPolicy="origin"
+          center={{ lat: 40.7128, lng: -74.006 }}
+          className="overflow-hidden rounded-xl"
+          consentCategory="measurement"
+          mapId="YOUR_MAP_ID"
+          zoom={12}
+        />
+      )}
+
+      <YouTubeEmbed
+        consentCategory="marketing"
+        params={{ controls: true, playsinline: true }}
+        title="Product demo"
+        videoId="dQw4w9WgXcQ"
+      />
+    </>
+  );
+}
+```
+
+The design splits the problem into three layers:
 
 1. Use the script loader to gate and load the shared SDK once.
-2. Use React state (or a custom hook) to render a placeholder until consent is granted.
+2. Use `useConsentScript()` for SDK readiness when a vendor uses a callback-style loader.
 3. Create the widget instance only after the SDK is ready and clean it up on unmount.
 
-For iframe-only embeds, use the [iframe blocking](/docs/frameworks/react/iframe-blocking) pattern instead of loading a JavaScript SDK to hide an iframe. For SDK-backed widgets, treat the SDK as a singleton and each rendered component as its own instance.
+Google Maps is SDK-backed, so `GoogleMap` registers one shared Google Maps script through the c15t script manager and waits for the callback-shaped SDK readiness signal before creating each map instance. It uses the official Google Maps types and accepts the direct-loader options `libraries`, `language`, `region`, `version`, `authReferrerPolicy`, `mapIds`, `channel`, and `solutionChannel`.
+
+YouTube is iframe-only, so `YouTubeEmbed` builds on the existing `Frame` consent boundary instead of loading the YouTube iframe API. That keeps iframe media separate from SDK widgets and avoids a second source of truth for script readiness.
+
+`GoogleMap` has a default height of `320px`; override `style.height` or supply a class that sets an inline-compatible height when your layout needs another size. `mapId` is construction-time configuration in the Google Maps API, so changing it recreates the map. Other controlled values such as `center`, `zoom`, and updateable `options` are applied to the existing instance.
+
+The Maps JavaScript API is a page singleton. Before consent, c15t makes no Maps script request. After the first approved load, the SDK registration is retained for the consent-manager lifetime to avoid Google's duplicate-loader warning; map instances are still destroyed as soon as the component unmounts or consent becomes unavailable. All `GoogleMap` instances that share a `scriptId` must therefore use the same loader options. If another part of the application already loaded Maps, the component adopts that global API without injecting a second script.
+
+`GoogleMap` reports network, timeout, constructor, and Google's global authentication failures through `onError` and `errorFallback`. Authentication errors commonly mean the browser key, billing, or allowed referrers need attention.
+
+`YouTubeEmbed` defaults to a responsive, borderless 16:9 frame with stable
+placeholder dimensions, a localized loading state, native lazy loading, and
+the privacy-enhanced `youtube-nocookie.com` host. For overrides, `className` and
+the forwarded ref target the iframe while `wrapperClassName` and `frameProps`
+target the consent-gated `Frame`. Boolean values in `params` are serialized as
+YouTube's documented `1` and `0` values.
+
+For custom SDK-backed widgets, call `useConsentScript()` with a c15t `Script`
+object. The hook uses the consent manager as the source of truth, shares
+compatible registrations inside that provider, and exposes status, consent,
+the ready SDK value, errors, and a promise:
+
+```tsx
+import { useState } from 'react';
+import { useConsentScript } from '@c15t/react';
+
+export function VendorWidget() {
+  const [retryKey, setRetryKey] = useState(0);
+  const vendor = useConsentScript({
+    script: {
+      id: 'vendor-sdk',
+      src: 'https://cdn.example.com/sdk.js',
+      category: 'measurement',
+    },
+    resolveReady: () => window.vendorSdk ?? false,
+    registerReadyCallback: ({ resolve }) => {
+      window.onVendorReady = () => resolve(window.vendorSdk);
+
+      return () => {
+        delete window.onVendorReady;
+      };
+    },
+    readinessKey: 'vendor-sdk-v1',
+    retryKey,
+    timeoutMs: 10_000,
+    unmountBehavior: 'keep',
+  });
+
+  if (vendor.status === 'blocked') {
+    return <p>Enable Analytics consent to use this widget.</p>;
+  }
+
+  if (vendor.status === 'loading') {
+    return <p role="status">Loading widget…</p>;
+  }
+
+  if (vendor.status === 'error') {
+    return (
+      <div role="alert">
+        <p>The widget could not be loaded.</p>
+        <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  if (vendor.status !== 'ready' || !vendor.readyValue) {
+    return null;
+  }
+
+  return <div ref={(node) => node && vendor.readyValue.mount(node)} />;
+}
+```
+
+Inline script objects and lifecycle callbacks are safe. The hook compares the complete non-function script configuration, reads callbacks from the latest render, adopts a compatible script already owned by the provider, and never removes a registration it did not create. Use `unmountBehavior: 'remove'` (the default) for route-local scripts, or `'keep'` for a genuine page-level singleton.
+
+Change `retryKey` after a failed attempt to retry the same registration.
+Consumers sharing a script id must use identical script options,
+`readinessKey`, timeout, and unmount behavior. Conflicts throw
+`ConsentScriptConflictError`; choose another id only when the vendor genuinely
+supports multiple page-level loaders.
+
+For iframe-only embeds, use the [iframe blocking](/docs/frameworks/react/iframe-blocking) pattern or `YouTubeEmbed` instead of loading a JavaScript SDK to hide an iframe. For SDK-backed widgets, treat the SDK as a singleton and each rendered component as its own instance.
 
 ## API Reference
 
-### Script
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Unique identifier for the script|-|✅ Required|
-|src|string \|undefined|URL of the script to load|-|Optional|
-|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
-|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
-|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|false|Optional|
-|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|false|Optional|
-|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|false|Optional|
-|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
-|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
-|async|boolean \|undefined|Whether to use async loading|-|Optional|
-|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
-|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
-|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|true|Optional|
-|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|'head'|Optional|
-|onBeforeLoad|Object \|undefined|Callback executed before the script is loaded|-|Optional|
-|onLoad|Object \|undefined|Callback executed when the script loads successfully|-|Optional|
-|onError|Object \|undefined|Callback executed if the script fails to load|-|Optional|
-|onConsentChange|Object \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
-|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
-|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
-|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
-|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
-
-#### `onBeforeLoad`
-
-Callback executed before the script is loaded
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onLoad`
-
-Callback executed when the script loads successfully
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onError`
-
-Callback executed if the script fails to load
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onConsentChange`
-
-Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+|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.\*

package/docs/{server-side.md → frameworks/react/server-side.md}

@@ -1,6 +1,8 @@
 ---
 title: Server-Side Utilities
-description: Fetch consent data on the server for SSR hydration — eliminate the loading flash and improve performance.
+description: Fetch consent data on the server for SSR hydration — eliminate the
+  loading flash and improve performance.
+group: frameworks
 ---
 The `@c15t/react/server` module provides utilities for fetching consent data on the server before rendering. This enables SSR hydration — consent state is available immediately on page load without a client-side fetch, eliminating the consent banner flash.
 
@@ -36,9 +38,12 @@ const ssrData = await fetchSSRData({
 
 ### Options
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|headers|Headers|Request headers from the framework. These should be the incoming request headers that contain geo-location information (cf-ipcountry, x-vercel-ip-country, etc.)|-|✅ Required|
+|Property|Value|
+|:--|:--|
+|Type Name|\`FetchSSRDataOptions\`|
+|Source Path|\`./packages/react/src/server/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "FetchSSRDataOptions" from "./packages/react/src/server/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
 
 ### Return Value
 

package/docs/{styling → frameworks/react/styling}/classnames.md

@@ -1,6 +1,8 @@
 ---
 title: Class Names
-description: Style consent components using className props and per-slot className targeting via the theme.
+description: Style consent components using className props and per-slot
+  className targeting via the theme.
+group: frameworks
 ---
 ## Prefer Slots for Stock Components
 

package/docs/{styling → frameworks/react/styling}/color-scheme.md

@@ -1,6 +1,8 @@
 ---
 title: Color Scheme
-description: Support light mode, dark mode, and system preference detection in consent components.
+description: Support light mode, dark mode, and system preference detection in
+  consent components.
+group: frameworks
 ---
 c15t supports light and dark mode through the theme's `colors` and `dark` token groups. The active color scheme is determined by one of three methods:
 

package/docs/frameworks/react/styling/css-variables.md

@@ -0,0 +1,53 @@
+---
+title: CSS Variables
+description: Reference for all --c15t-* CSS custom properties generated by the theme system.
+group: frameworks
+---
+Every theme token is converted to a `--c15t-*` CSS custom property at runtime. You can override these variables in your stylesheet without using the JavaScript theme API.
+
+## Variable Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ThemeCSSVariables\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ThemeCSSVariables" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Overriding Variables
+
+Override in your stylesheet:
+
+```css
+:root {
+  --c15t-primary: #8b5cf6;
+  --c15t-surface: #fafafa;
+  --c15t-radius-md: 1rem;
+}
+
+/* Dark mode overrides */
+.dark,
+.c15t-dark {
+  --c15t-primary: #a78bfa;
+  --c15t-surface: #18181b;
+  --c15t-text: #fafafa;
+}
+```
+
+## Scoped Overrides
+
+Target specific components by scoping variables:
+
+```tsx
+<div className="checkout-consent">
+  <ConsentBanner />
+</div>
+```
+
+```css
+/* Only affect c15t components inside .checkout-consent */
+.checkout-consent {
+  --c15t-surface: #f0f9ff;
+  --c15t-radius-lg: 1.5rem;
+}
+```