@c15t/nextjs 2.1.0 → 2.2.1

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

@@ -1,38 +1,26 @@
 ---
 title: Quickstart
 description: Add consent management to your Next.js app in under 5 minutes.
-lastModified: 2026-03-11
-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/nextjs`|
-   |pnpm|`pnpm add @c15t/nextjs`|
-   |yarn|`yarn add @c15t/nextjs`|
-   |bun|`bun add @c15t/nextjs`|
-
 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. Your root layout should continue importing ./globals.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.
@@ -86,14 +73,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 app tree with ConsentManager so all routes/components can access consent state.
+4. **Mount ConsentManager at the app root** Wrap your app tree with `ConsentManager` so all routes/components can access consent state.
 
    ```tsx
    import { ConsentManager } from '@/components/consent-manager';
@@ -111,7 +96,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 better performance and static-route support? See Optimization for rewrites, prefetching, and network tuning. If you want server-side data prefetching, see Server-Side Data Fetching.
@@ -120,12 +107,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:
 
@@ -149,13 +131,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/next/optimization)
+* [Script Loader](/docs/frameworks/next/script-loader)
+* [Styling](/docs/frameworks/next/styling/overview)
+* [Consent Categories](/docs/frameworks/next/concepts/consent-categories)
+* [Components](/docs/frameworks/next/components/consent-banner)
+* [AI Agents](/docs/ai-agents)

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

@@ -1,22 +1,20 @@
 ---
 title: Script Loader
-description: Gate third-party scripts behind consent in Next.js — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+description: Gate third-party scripts behind consent in Next.js — 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:**
@@ -186,6 +184,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
 
@@ -298,6 +298,8 @@ Control where the script is injected and whether the element id is anonymized:
 
 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:
@@ -422,98 +424,78 @@ export function WorkspaceAnalytics({ workspaceId }: { workspaceId: string }) {
 
 Some integrations need a visible component, not just a script tag. Google Maps, YouTube, checkout widgets, and calendars all need consent gating plus component lifecycle.
 
-Split the problem into three layers:
+Use the [Google Maps](/docs/integrations/google-maps) and
+[YouTube](/docs/integrations/youtube) renderable integrations through
+`@c15t/nextjs` in client components:
+
+```tsx
+'use client';
+
+import { GoogleMap, YouTubeEmbed } from '@c15t/nextjs';
+
+export function ConsentAwareMedia() {
+  const googleMapsApiKey = process.env.NEXT_PUBLIC_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"
+          zoom={12}
+        />
+      )}
+
+      <YouTubeEmbed
+        consentCategory="marketing"
+        title="Product demo"
+        videoId="dQw4w9WgXcQ"
+      />
+    </>
+  );
+}
+```
+
+The implementation splits the problem into three layers:
 
 1. Use the script loader as the source of truth for shared SDK loading.
-2. 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 on the client and clean it up on unmount.
 
-For iframe-only embeds, use the [iframe blocking](/docs/frameworks/next/iframe-blocking) pattern. For SDK-backed widgets, load the SDK once and let each component instance create and clean up its own widget. Avoid mixing `next/script` with c15t for the same vendor.
+Google Maps is SDK-backed and uses one shared c15t-managed script plus per-component map instances. The script is never requested before consent. Once loaded, its manager registration is retained to respect Google's one-loader-per-page constraint, while each map instance is destroyed on unmount or when consent becomes unavailable. The component adopts an existing Google Maps global, has a visible `320px` default height, uses the official API types, and reports loader, authentication, and constructor failures through `onError` and `errorFallback`.
+
+All maps with the same `scriptId` must use the same loader configuration. `mapId` changes recreate the instance; `center`, `zoom`, and updateable `options` update it in place. You can pass Google's direct-loader options through `libraries`, `language`, `region`, `version`, `authReferrerPolicy`, `mapIds`, `channel`, and `solutionChannel`.
+
+YouTube is iframe-only and uses the existing `Frame` boundary rather than the
+YouTube iframe API. It defaults to a responsive, borderless 16:9 frame with a
+localized loading state, stable placeholder dimensions, native lazy loading,
+and the privacy-enhanced host. Its `className` and forwarded ref target the
+iframe; `wrapperClassName` and `frameProps` target the `Frame`. Boolean `params`
+become `1` or `0`.
+
+For a custom client-side SDK, `useConsentScript()` exposes `blocked`, `loading`,
+`ready`, and `error` states plus `readyValue`, `error`, and `ready`. Change its
+`retryKey` after a failed attempt to retry the same script id. Registrations
+with one id must use compatible script and readiness options; conflicts surface
+as `ConsentScriptConflictError`.
+
+For iframe-only embeds, use the [iframe blocking](/docs/frameworks/next/iframe-blocking) pattern or `YouTubeEmbed`. For SDK-backed widgets, load the SDK once and let each component instance create and clean up its own widget. Avoid mixing `next/script` with c15t for the same vendor.
 
 ## App Router Notes
 
 * The provider and any component that calls `useConsentManager()` must be client components.
 * Keep vendor ids out of static examples when they differ per environment — read them from `process.env.NEXT_PUBLIC_*` or runtime config.
 * If a script must be available before a page becomes interactive, prefer a built-in helper that models denied-consent defaults rather than adding a separate `next/script` tag.
-* If you use CSP nonces, pass the nonce through the `Script` object so c15t applies it to the generated script element.
+* If you use CSP nonces, set `nonce` on the provider options so c15t applies it to every injected script element and the theme stylesheet. See [Content Security Policy](/docs/frameworks/next/components/consent-manager-provider#content-security-policy) for reading the nonce in the App Router.
 
 ## 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/next/server-side.md}

@@ -1,6 +1,8 @@
 ---
 title: Server-Side Data Fetching
-description: Pre-fetch consent data in Server Components with fetchInitialData for dynamic Next.js routes.
+description: Pre-fetch consent data in Server Components with fetchInitialData
+  for dynamic Next.js routes.
+group: frameworks
 ---
 The `@c15t/nextjs` package provides `fetchInitialData`, a server-side function that fetches consent data before rendering. Use it when the route is already dynamic, or when you want the fastest first banner and are okay opting the route into dynamic rendering. If you need to keep a route fully static, use `C15tPrefetch` instead.
 
@@ -27,7 +29,7 @@ const ssrData = fetchInitialData({
 });
 ```
 
-> ℹ️ **Info:**
+> ⚠️ **Warning:**
 > Do not await fetchInitialData() in Server Components. Pass the Promise directly to your client component so Next.js can stream the page while the consent data loads in parallel.
 >
 > ℹ️ **Info:**
@@ -48,29 +50,24 @@ sequenceDiagram
     participant BE as c15t Backend
 
     SC->>BE: fetchInitialData() → GET /init
-    Note right of SC: Returns a Promise - (not awaited)
-    SC->>NR: Render page tree - (Promise passed as prop)
+    Note right of SC: Returns a Promise<br/>(not awaited)
+    SC->>NR: Render page tree<br/>(Promise passed as prop)
     NR->>BR: Stream initial HTML
     BR->>BR: Hydrate — no consent data yet
 
     BE-->>NR: /init response resolves
     NR->>BR: Stream resolved data chunk
-    BR->>BR: Provider receives SSR data - skips client-side /init fetch
+    BR->>BR: Provider receives SSR data,<br/>skips client-side /init fetch
 ```
 
 ### Options
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|nextCache|NextCacheOptions \|undefined|Optional Next.js cache controls for SSR init requests.|-|Optional|
-
-#### `nextCache` NextCacheOptions
-
-Optional Next.js cache controls for SSR init requests.
+|Property|Value|
+|:--|:--|
+|Type Name|\`FetchInitialDataOptions\`|
+|Source Path|\`./packages/nextjs/src/types.ts\`|
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|revalidateSeconds|number \|false \|undefined|Cache lifetime in seconds for the Next.js data cache. Set to false to disable Next.js caching for this call.|-|Optional|
+\*ExtractedTypeTable: Could not extract "FetchInitialDataOptions" from "./packages/nextjs/src/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/next/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/next/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/next/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;
+}
+```