@c15t/nextjs 2.1.0 → 2.2.1

package/docs/frameworks/next/components/consent-manager-provider.md

@@ -0,0 +1,327 @@
+---
+title: ConsentManagerProvider
+description: The root provider component that initializes the consent system and
+  makes consent state available to all child components.
+group: frameworks
+---
+`ConsentManagerProvider` is the root component for the c15t consent system. It initializes the consent store, detects the user's jurisdiction, resolves translations, and provides consent state to all child components via React context.
+
+Every other c15t component and hook must be rendered inside this provider.
+
+## Basic Usage
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        consentCategories: ['necessary', 'measurement', 'marketing'],
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Options Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`CommonInlineStoreOptions\`|
+|Source Path|\`./packages/ui/src/theme/options.ts\`|
+
+\*ExtractedTypeTable: Could not extract "CommonInlineStoreOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentManagerContentOptions\`|
+|Source Path|\`./packages/ui/src/theme/options.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentManagerContentOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`UIOptions\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "UIOptions" 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.\*
+
+## Mode: hosted vs offline
+
+```tsx
+// Hosted mode — persists to hosted backend
+<ConsentManagerProvider
+  options={{
+    mode: 'hosted',
+    backendURL: '/api/c15t',
+  }}
+>
+
+// Offline mode — local cookie storage only
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+  }}
+>
+```
+
+See [Client Modes](/docs/frameworks/next/concepts/client-modes) for a detailed comparison.
+
+## Content Security Policy
+
+c15t injects a `<style id="c15t-theme">` element for your theme tokens, and the script loader injects a `<script>` element per consented vendor. Under a nonce-based Content Security Policy, both are blocked unless they carry your nonce.
+
+Pass it once through the `nonce` option and c15t applies it to everything it injects:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+    nonce: yourRequestNonce,
+  }}
+>
+  {children}
+</ConsentManagerProvider>
+```
+
+A `nonce` set on an individual script definition still wins, so you can override a single vendor without changing the provider.
+
+> 📝 **Note:**
+> Browsers hide the nonce content attribute once a policy is active. Inspecting the element shows no nonce="", but element.nonce still returns the value — this is expected and not a sign that c15t dropped it.
+
+### Inline style attributes
+
+The `nonce` option covers the elements c15t injects. It cannot cover inline `style="..."` attributes, which several components rely on — a nonce never authorizes a style attribute, because nonces apply to elements only.
+
+Style attributes are governed by `style-src-attr`, and when that directive is absent CSP falls back to `style-src`. A nonce-based style policy therefore blocks them:
+
+```http
+style-src 'self' 'nonce-abc123';
+```
+
+To keep the nonce requirement for stylesheets while still allowing style attributes, set `style-src-attr` explicitly:
+
+```http
+style-src 'self' 'nonce-abc123';
+style-src-attr 'unsafe-inline';
+```
+
+> ⚠️ **Warning:**
+> 'unsafe-inline' on style-src-attr permits any inline style attribute on the page. That is weaker than a nonce, but far narrower than replacing your nonce-based style-src with 'unsafe-inline', which would additionally authorize arbitrary injected \<style> elements. Note that adding 'unsafe-inline' alongside a nonce achieves nothing — a directive that specifies a nonce ignores it. If your threat model does not allow this, expect components that use inline styles to render unstyled.
+
+### Reading the nonce in the App Router
+
+Next.js does not expose the request nonce to client components, so read it in a server component and pass it down. Generate the nonce in middleware, forward it on a request header, then hand it to the provider from your layout:
+
+```ts title="middleware.ts"
+import { NextResponse, type NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const nonce = crypto.randomUUID();
+  const isDev = process.env.NODE_ENV === 'development';
+
+  const csp = [
+    `default-src 'self'`,
+    // Next.js dev tooling (React Refresh and HMR) requires 'unsafe-eval'.
+    `script-src 'self' 'nonce-${nonce}'${isDev ? " 'unsafe-eval'" : ''}`,
+    `style-src 'self' 'nonce-${nonce}'`,
+    // Nonces cannot authorize inline style attributes — see above.
+    `style-src-attr 'unsafe-inline'`,
+  ].join('; ');
+
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.set('x-nonce', nonce);
+  requestHeaders.set('Content-Security-Policy', csp);
+
+  const response = NextResponse.next({ request: { headers: requestHeaders } });
+  response.headers.set('Content-Security-Policy', csp);
+
+  return response;
+}
+```
+
+> ⚠️ **Warning:**
+> Set the same policy on both the forwarded request headers and the response. Next.js reads the nonce for its own runtime and hydration scripts from the Content-Security-Policy request header during rendering. Setting it only on the response leaves those scripts without a nonce, and the enforced policy then blocks them, so the page never hydrates.
+
+```tsx title="app/layout.tsx"
+import { headers } from 'next/headers';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const nonce = (await headers()).get('x-nonce') ?? undefined;
+
+  return (
+    <html lang="en">
+      <body>
+        <ConsentManagerProvider options={{ mode: 'offline', nonce }}>
+          {children}
+        </ConsentManagerProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Legal Links
+
+`legalLinks` defines the URLs shown in consent UI text (banner, dialog, and widget where applicable).
+Configure only the links you want to expose.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    legalLinks: {
+      privacyPolicy: {
+        href: '/privacy',
+        target: '_self',
+      },
+      cookiePolicy: {
+        href: '/cookies',
+        target: '_self',
+      },
+      termsOfService: {
+        href: 'https://example.com/terms',
+        target: '_blank',
+        rel: 'noopener noreferrer',
+        label: 'Terms of Service',
+      },
+    },
+  }}
+>
+```
+
+Notes:
+
+* Omitting a key (for example `termsOfService`) hides that link.
+* `label` overrides the translated text for that single link.
+* Use `_self` for internal pages and `_blank` + `rel="noopener noreferrer"` for external pages.
+* Control which of the configured links render in each component via the component's `legalLinks` prop.
+
+## Overrides
+
+`overrides` lets you force location/language signals instead of browser or network detection.
+This is useful for QA, local development, and preview environments.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      country: 'DE',
+      region: 'BY',
+      language: 'de-DE',
+    },
+  }}
+>
+```
+
+You can also override Global Privacy Control (GPC) behavior during testing:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      gpc: true,
+    },
+  }}
+>
+```
+
+> ⚠️ **Warning:**
+> Treat overrides as an environment/testing tool. Avoid hard-coding production overrides unless that behavior is intentional for your deployment.
+
+## Policy Packs
+
+In hosted mode (recommended), the backend resolves the correct policy automatically — no frontend policy config needed:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+```
+
+### Fallback: Offline Policies
+
+When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution during development, testing, previews, or temporary backend outages:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+    offlinePolicy: {
+      i18n: {
+        defaultProfile: 'default',
+        messages: {
+          default: {
+            translations: {
+              en: { cookieBanner: { title: 'Privacy choices' } },
+            },
+          },
+          qc: {
+            fallbackLanguage: 'fr',
+            translations: {
+              en: { cookieBanner: { title: 'Quebec Privacy Settings' } },
+              fr: { cookieBanner: { title: 'Paramètres de confidentialité du Québec' } },
+            },
+          },
+        },
+      },
+      policyPacks: [
+        {
+          id: 'qc_opt_in',
+          match: { regions: [{ country: 'CA', region: 'QC' }] },
+          i18n: { messageProfile: 'qc' },
+          consent: { model: 'opt-in', expiryDays: 365 },
+          ui: { mode: 'banner' },
+        },
+        {
+          id: 'default_world',
+          match: { isDefault: true },
+          consent: { model: 'none' },
+          ui: { mode: 'none' },
+        },
+      ],
+    },
+    overrides: {
+      country: 'CA',
+      region: 'QC',
+    },
+  }}
+>
+```
+
+Notes:
+
+* `offlinePolicy` is only used in `offline` mode.
+* Treat offline policies as a development/testing tool or resilience fallback, not the primary production source of truth.
+* `offlinePolicy.i18n` lets offline mode mirror hosted `messageProfile` and profile-local `fallbackLanguage` behavior.
+* Omitting `offlinePolicy.policyPacks` uses the built-in synthetic opt-in fallback banner. Hosted network fallback uses the same opt-in banner.
+* `offlinePolicy: { policyPacks: [] }` is explicit no-banner mode.
+* In hosted mode, backend `policyPacks` remain the source of truth — frontend offline policies never override a live backend decision.
+
+Read the full guide at [Policy Packs](/docs/frameworks/react/policy-packs) and the conceptual model at [Policy Packs Concept](/docs/frameworks/react/concepts/policy-packs).
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentManagerProviderProps\`|
+|Source Path|\`./packages/react/src/types/consent-manager.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentManagerProviderProps" from "./packages/react/src/types/consent-manager.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/{components → frameworks/next/components}/consent-widget.md

@@ -1,6 +1,8 @@
 ---
 title: ConsentWidget
-description: An inline consent management widget for embedding in settings or privacy pages. Shows category toggles with accordion layout.
+description: An inline consent management widget for embedding in settings or
+  privacy pages. Shows category toggles with accordion layout.
+group: frameworks
 ---
 `ConsentWidget` is a standalone, inline consent management widget. Unlike `ConsentDialog` (which is a modal), the widget embeds directly in your page layout - ideal for privacy settings pages, account preferences, or any page where users should be able to manage consent without a modal overlay.
 
@@ -128,9 +130,9 @@ If the stock widget structure is already correct, stay with tokens and slots ins
 
 ## Props
 
-### ConsentWidgetProps
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentWidgetProps\`|
+|Source Path|\`./packages/react/src/components/consent-widget/types.ts\`|
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|hideBranding|boolean \|undefined|Controls whether to hide the branding in the widget footer.|-|Optional|
-|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display in the widget footer.|-|Optional|
+\*ExtractedTypeTable: Could not extract "ConsentWidgetProps" from "./packages/react/src/components/consent-widget/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/{components → frameworks/next/components}/dev-tools.md

@@ -1,10 +1,12 @@
 ---
 title: DevTools
-description: A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
+description: A development tool for inspecting consent state, geolocation,
+  loaded scripts, and consent events in real time.
+group: frameworks
 ---
 `DevTools` is a floating panel that shows the internal state of the consent manager. Use it during development to inspect consent values, geolocation results, loaded scripts, and debug consent flows. Also exported as `C15TDevTools` if you need to avoid naming conflicts with other devtools.
 
-> ℹ️ **Info:**
+> ⚠️ **Warning:**
 > DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
 
 ## Installation
@@ -89,8 +91,9 @@ export function AppDevtools() {
 
 ## Props
 
-### C15TDevToolsProps
+|Property|Value|
+|:--|:--|
+|Type Name|\`C15TDevToolsProps\`|
+|Source Path|\`./packages/dev-tools/src/react.ts\`|
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|disabled|boolean \|undefined|Whether the DevTools should be disabled Useful for production builds|false|Optional|
+\*ExtractedTypeTable: Could not extract "C15TDevToolsProps" from "./packages/dev-tools/src/react.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/{components → frameworks/next/components}/frame.md

@@ -1,6 +1,8 @@
 ---
 title: Frame
-description: A consent-gated content wrapper - children only mount when the required consent category is granted.
+description: A consent-gated content wrapper - children only mount when the
+  required consent category is granted.
+group: frameworks
 ---
 `Frame` conditionally renders its children based on consent state. When consent for the specified category is not granted, a placeholder is shown instead. Children are not mounted at all until consent is given, preventing any network requests or script execution.
 
@@ -62,12 +64,9 @@ When `Frame` mounts, it automatically adds its `category` to the active `consent
 
 ## Props
 
-### FrameProps
+|Property|Value|
+|:--|:--|
+|Type Name|\`FrameProps\`|
+|Source Path|\`./packages/react/src/components/frame/types.ts\`|
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|children|ReactNode|Content rendered when consent is granted. Children are not mounted until consent is given, preventing unnecessary network requests.|-|✅ Required|
-|category|AllConsentNames|Consent category required to render children.|-|✅ Required|
-|placeholder|ReactNode|A custom placeholder component to display when consent is not met. If not provided, a default placeholder will be displayed.|-|Optional|
-|noStyle|boolean \|undefined|When true, removes all default styling from the component|false|Optional|
-|theme|any|Custom theme to override default styles while maintaining structure and accessibility. Merges with defaults. Ignored when \`noStyle=\{true}\`.|undefined|Optional|
+\*ExtractedTypeTable: Could not extract "FrameProps" from "./packages/react/src/components/frame/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/{concepts → frameworks/next/concepts}/client-modes.md

@@ -1,6 +1,8 @@
 ---
 title: Client Modes
-description: Choose how c15t connects to its backend - full hosted integration, offline-only, or bring your own backend.
+description: Choose how c15t connects to its backend - full hosted integration,
+  offline-only, or bring your own backend.
+group: frameworks
 ---
 c15t supports three client modes that determine how consent data is stored and synchronized. Choose the mode that matches your infrastructure:
 
@@ -8,7 +10,7 @@ c15t supports three client modes that determine how consent data is stored and s
 * **Offline mode** - Browser-only storage with no network requests. Best for local development, demos, static deployments, or controlled fallback scenarios.
 * **Custom mode** - Bring your own backend with custom endpoint handlers
 
-> ℹ️ **Info:**
+> ⚠️ **Warning:**
 > If you need durable consent records, server-side enforcement, or automatic jurisdiction detection, use hosted mode. Offline mode cannot provide those guarantees because consent lives only in the browser.
 
 <span id="c15t-mode" />

package/docs/{concepts → frameworks/next/concepts}/consent-categories.md

@@ -1,6 +1,7 @@
 ---
 title: Consent Categories
 description: How c15t organizes tracking technologies into five consent categories.
+group: frameworks
 ---
 c15t organizes tracking technologies into five consent categories that align with GDPR and ePrivacy Directive requirements. Rather than asking users to approve or deny individual cookies or scripts, each category groups related tracking purposes together so users can make meaningful, informed choices about how their data is used.
 

package/docs/{concepts → frameworks/next/concepts}/consent-models.md

@@ -1,6 +1,7 @@
 ---
 title: Consent Models
 description: How c15t determines consent behavior based on legal jurisdiction.
+group: frameworks
 ---
 c15t supports four consent models that control how consent defaults, banner visibility, and category gating behave:
 

package/docs/{concepts → frameworks/next/concepts}/cookie-management.md

@@ -1,7 +1,7 @@
 ---
 title: Cookie Management
 description: How c15t manages cookies through script, iframe, and network gating
-lastModified: 2026-02-10
+group: frameworks
 ---
 Cookie management is the most commonly misunderstood part of consent. A critical distinction: **c15t does not manage all cookies on your site.** It controls what scripts, iframes, and network requests are allowed to load - and those third-party resources are what set most cookies.
 
@@ -23,7 +23,7 @@ YouTube embeds, social media widgets, and other iframes can set cookies via thei
 **4. Network requests**
 Server responses can include `Set-Cookie` headers. If your page makes requests to third-party APIs or CDNs, those responses may set cookies. c15t's network blocker can intercept `fetch` and `XMLHttpRequest` calls to prevent these requests from happening without consent.
 
-> ℹ️ **Info:**
+> ⚠️ **Warning:**
 > Don't list these cookies in your banner. The cookie names above (\_ga, \_gid, \_fbp, \_fbc) are implementation details — they matter for developers understanding how tracking works, but they should not be exposed to end users in your consent UI. Users don't know what \_ga means, and listing it doesn't help them make an informed choice. Instead, use purpose-based consent categories like "measurement" or "marketing" that communicate why data is collected, not how it is stored.
 
 ## Why Revoking Consent Requires a Page Reload
@@ -76,7 +76,7 @@ function ConsentManager({ children }: { children: ReactNode }) {
 > ℹ️ **Info:**
 > The reload and deferred sync are part of the broader initialization flow. See Initialization Flow for the full sequence.
 >
-> ℹ️ **Info:**
+> ⚠️ **Warning:**
 > Setting reloadOnConsentRevoked: false means previously-loaded scripts will continue running after consent is revoked. Only disable this if you have a specific strategy for handling script cleanup.
 
 ## The Revocation Flow

package/docs/{concepts → frameworks/next/concepts}/glossary.md

@@ -1,6 +1,7 @@
 ---
 title: Glossary
 description: Key terms used throughout the c15t documentation.
+group: frameworks
 ---
 ### Core Terms
 

package/docs/{concepts → frameworks/next/concepts}/initialization-flow.md

@@ -1,6 +1,7 @@
 ---
 title: Initialization Flow
 description: What happens from provider mount to first render — the full consent lifecycle.
+group: frameworks
 ---
 When the consent provider mounts, it creates a cached consent runtime, reads any stored consent from the browser, fetches the resolved policy from the backend (or uses SSR/offline data), and decides whether to show the banner. This entire sequence completes before the first meaningful consent-aware render.
 

package/docs/{concepts → frameworks/next/concepts}/policy-packs.md

@@ -1,6 +1,7 @@
 ---
 title: Policy Packs
 description: How c15t resolves regional consent policies and what a policy pack controls.
+group: frameworks
 ---
 Different countries need different consent experiences. Policy packs let you define those rules once — c15t picks the right one automatically based on where the visitor is.
 

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

@@ -1,6 +1,8 @@
 ---
 title: Headless Mode
-description: Build fully custom consent UI using only hooks - no pre-built components required.
+description: Build fully custom consent UI using only hooks - no pre-built
+  components required.
+group: frameworks
 ---
 c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
 

package/docs/{hooks → frameworks/next/hooks}/use-color-scheme.md

@@ -1,6 +1,7 @@
 ---
 title: useColorScheme
 description: Manage light/dark mode preferences for consent components.
+group: frameworks
 ---
 `useColorScheme()` manages the color scheme preference for c15t components. It sets up the appropriate CSS class and media query listeners.
 

package/docs/{hooks → frameworks/next/hooks}/use-consent-manager/checking-consent.md

@@ -1,6 +1,8 @@
 ---
 title: Checking Consent
-description: Use has() for flexible consent checks with AND, OR, and NOT logic. Check if any consent exists with hasConsented().
+description: Use has() for flexible consent checks with AND, OR, and NOT logic.
+  Check if any consent exists with hasConsented().
+group: frameworks
 ---
 ## has(condition)
 

package/docs/{hooks → frameworks/next/hooks}/use-consent-manager/location-info.md

@@ -1,6 +1,8 @@
 ---
 title: Location Info
-description: Access detected jurisdiction, country, and region. Override geolocation for testing.
+description: Access detected jurisdiction, country, and region. Override
+  geolocation for testing.
+group: frameworks
 ---
 ## locationInfo