@c15t/nextjs 2.0.0-rc.0 → 2.0.0-rc.10

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

@@ -0,0 +1,425 @@
+---
+title: ConsentManagerProvider
+description: The root provider component that initializes the consent system and makes consent state available to all child components.
+---
+`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
+
+### CommonInlineStoreOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether c15t should be active.|true|Optional|
+|callbacks|[Callbacks \|undefined](https://v2.c15t.com/docs/frameworks/react/callbacks)|Event callbacks for consent actions.|-|Optional|
+|scripts|[Script \|undefined](https://v2.c15t.com/docs/frameworks/react/script-loader)|Dynamically load scripts based on consent state.|-|Optional|
+|legalLinks|Object \|undefined|Configuration for the legal links.|-|Optional|
+|storageConfig|StorageConfig \|undefined|Storage configuration for consent persistence.|-|Optional|
+|user|User \|undefined|The user's information. Usually your own internal ID for the user from your auth provider.|-|Optional|
+|overrides|Overrides \|undefined|Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.|-|Optional|
+|networkBlocker|[NetworkBlockerConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/network-blocker)|Configuration for the network request blocker.|-|Optional|
+|iab|[IABConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/iab/overview)|IAB TCF 2.3 configuration.|-|Optional|
+|ssrData|[Object \|undefined](https://v2.c15t.com/docs/frameworks/react/server-side)|SSR-prefetched data for hydration.|-|Optional|
+
+#### `callbacks` Callbacks
+
+Event callbacks for consent actions.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|onBannerFetched|Callback\<OnBannerFetchedPayload> \|undefined|Called when the consent banner is fetched.|-|Optional|
+|onConsentSet|Callback\<OnConsentSetPayload> \|undefined|Called when the consent is set.|-|Optional|
+|onConsentChanged|Callback\<OnConsentChangedPayload> \|undefined|Called only when an explicit consent save changes the previously saved consent state.|-|Optional|
+|onError|Callback\<OnErrorPayload> \|undefined|Called when an error occurs.|-|Optional|
+|onBeforeConsentRevocationReload|Callback\<OnConsentSetPayload> \|undefined|Called before the page reloads when consent is revoked.|-|Optional|
+
+#### `scripts` Script
+
+Dynamically load scripts based on consent state.
+
+|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.|-|Optional|
+|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|-|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.|-|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|-|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>\`|-|Optional|
+|onBeforeLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed before the script is loaded|-|Optional|
+|onLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed when the script loads successfully|-|Optional|
+|onError|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed if the script fails to load|-|Optional|
+|onConsentChange|((info: ScriptCallbackInfo) => void) \|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|
+
+#### `legalLinks`
+
+Configuration for the legal links.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|privacyPolicy|LegalLink \|undefined|-|-|✅ Required|
+|cookiePolicy|LegalLink \|undefined|-|-|✅ Required|
+|termsOfService|LegalLink \|undefined|-|-|✅ Required|
+
+#### `storageConfig` StorageConfig
+
+Storage configuration for consent persistence.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|storageKey|string \|undefined|Custom storage key for localStorage and cookies|-|Optional|
+|crossSubdomain|boolean \|undefined|Enable cross-subdomain cookies by default|-|Optional|
+|defaultDomain|string \|undefined|Custom default domain for cookies|-|Optional|
+|defaultExpiryDays|number \|undefined|Default cookie expiration in days|-|Optional|
+
+#### `user` User
+
+The user's information. Usually your own internal ID for the user from your auth provider.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Usually your own internal ID for the user from your auth provider|-|✅ Required|
+|identityProvider|string \|undefined|The identity provider of the user. Usually the name of the identity provider e.g. 'clerk', 'auth0', 'custom', etc.|-|Optional|
+
+#### `overrides` Overrides
+
+Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|country|string \|undefined|Country code to forcefully set|-|Optional|
+|region|string \|undefined|Region code to forcefully set|-|Optional|
+|language|string \|undefined|Language code to forcefully set|-|Optional|
+|gpc|boolean \|undefined|Override the Global Privacy Control (GPC) signal. When \`true\`, simulates GPC being active (opt-out of marketing/measurement). When \`false\`, suppresses the real browser GPC signal. When \`undefined\`, falls back to the browser's \`navigator.globalPrivacyControl\`.|-|Optional|
+
+#### `networkBlocker` NetworkBlockerConfig
+
+Configuration for the network request blocker.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|((info: BlockedRequestInfo) => void) \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+#### `iab` IABConfig
+
+IAB TCF 2.3 configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean|Enable IAB TCF 2.3 mode. Note: Only works in 'hosted' client mode (legacy alias: 'c15t') because it requires a backend. Options: Fetch GVL from gvl.consent.io; Initialize \_\_tcfapi CMP API; Generate TC Strings for IAB compliance|-|✅ Required|
+|\_module|IABModule \|undefined|IAB runtime module injected by \`@c15t/iab\`.|-|Optional|
+|cmpId|number \|undefined|CMP ID registered with IAB Europe. When using consent.io as the backend, this is automatically provided via the \`/init\` endpoint — no client-side configuration needed. Only set this if you self-host and have your own CMP registration. A valid (non-zero) CMP ID is required for IAB TCF compliance.|-|Optional|
+|cmpVersion|string \|number \|undefined|CMP version. When omitted, defaults to package version from \`\~/cmp-defaults\` (which uses \~/version).|-|Optional|
+|vendors|number\[] \|undefined|IAB-registered vendor IDs to include (optional). Used to scope the vendor list when fetching GVL or when hosted fallback paths are used (e.g. if GVL fetch fails).|-|Optional|
+|customVendors|NonIABVendor \|undefined|Custom vendors not registered with IAB. These are displayed separately in the consent UI with a note that they have different privacy practices than IAB vendors.|-|Optional|
+|publisherCountryCode|string \|undefined|Publisher country code (2-letter ISO).|-|Optional|
+|isServiceSpecific|boolean \|undefined|Whether consent is service-specific (not global).|-|Optional|
+|gvl|Object \|undefined \|null|Pre-loaded Global Vendor List for testing or SSR. Options: Testing (avoids network calls and mocking complexity); SSR (use server-fetched GVL); Offline/air-gapped deployments|-|Optional|
+
+#### `ssrData`
+
+SSR-prefetched data for hydration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|init|Object \|undefined \|null|Init endpoint response with jurisdiction, location, translations, and optional GVL.|-|✅ Required|
+|gvl|Object \|undefined \|null|Global Vendor List data for IAB TCF mode. Note: When init returns 200 without gvl, client IAB settings are overridden to disabled.|-|Optional|
+|metadata|SSRInitRequestMetadata \|undefined|Optional metadata for debugging SSR transport behavior.|-|Optional|
+
+### ConsentManagerContentOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|i18n|I18nConfig \|undefined|Preferred i18n configuration in c15t v2.|-|Optional|
+|translations|[TranslationConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/internationalization)|Translation configuration to seed the store with.|-|Optional|
+|consentCategories|[AllConsentNames \|undefined](https://v2.c15t.com/docs/frameworks/react/concepts/consent-categories)|Consent categories to show in the consent banner.|-|Optional|
+
+#### `i18n` I18nConfig
+
+Preferred i18n configuration in c15t v2.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|messages|Record\<string, Partial\<Translations>> \|undefined|Translation message map keyed by language code (\`en\`, \`de\`, \`fr\`, ...).|-|✅ Required|
+|locale|string \|undefined|Preferred language code used as the initial fallback locale.|-|Optional|
+|detectBrowserLanguage|boolean \|undefined|Whether to auto-detect from browser language settings.|-|Optional|
+
+#### `translations` TranslationConfig
+
+Translation configuration to seed the store with.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|translations|Record\<string, Partial\<Translations>> \|undefined|-|-|✅ Required|
+|defaultLanguage|string \|undefined|-|-|Optional|
+|disableAutoLanguageSwitch|boolean \|undefined|-|-|Optional|
+
+### UIOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|theme|[Theme \|undefined](https://v2.c15t.com/docs/frameworks/react/styling/tokens)|Visual theme to apply.|-|Optional|
+|disableAnimation|boolean \|undefined|Whether to disable animations.|false|Optional|
+|scrollLock|boolean \|undefined|Whether to lock scroll when dialogs are open.|false|Optional|
+|trapFocus|boolean \|undefined|Whether to trap focus within dialogs.|true|Optional|
+|colorScheme|["light" \|"dark" \|"system" \|undefined](https://v2.c15t.com/docs/frameworks/react/styling/color-scheme)|Color scheme preference. With this option, you can force the theme to be light, dark or system. Otherwise, the theme will be detected if you have '.dark' classname in your document.|-|Optional|
+|noStyle|[boolean \|undefined](https://v2.c15t.com/docs/frameworks/react/headless)|Whether to disable default styles.|false|Optional|
+
+#### `theme` Theme
+
+Visual theme to apply.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|colors|ColorTokens \|undefined|Color palette for light mode.|-|Optional|
+|dark|ColorTokens \|undefined|Dark mode color overrides.|-|Optional|
+|typography|TypographyTokens \|undefined|Typography settings for text elements.|-|Optional|
+|spacing|SpacingTokens \|undefined|Spacing scale for internal padding and margins.|-|Optional|
+|radius|RadiusTokens \|undefined|Border radius scale for rounded corners.|-|Optional|
+|shadows|ShadowTokens \|undefined|Box shadow scale for depth and elevation.|-|Optional|
+|motion|MotionTokens \|undefined|Animation and transition timing.|-|Optional|
+|consentActions|Object \|undefined|Semantic button styling for consent actions.|-|Optional|
+|slots|ComponentSlots \|undefined|Component-specific style overrides.|-|Optional|
+
+## 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.
+
+## 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
+
+### ConsentManagerProviderProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|React children to render within the provider.|-|✅ Required|
+|options|[ConsentManagerOptions](https://v2.c15t.com/docs/frameworks/react/components/consent-manager-provider)|Configuration options for the consent manager. This includes core, React, store, and translation settings.|-|✅ Required|
+
+#### `options` ConsentManagerOptions
+
+Configuration options for the consent manager. This includes core, React, store, and translation settings.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|store|StoreOptions \|undefined|-|-|Optional|
+|offlinePolicy|OfflinePolicyConfig \|undefined|Top-level offline policy configuration.|-|Optional|
+|storageConfig|StorageConfig \|undefined|Storage configuration for consent persistence|-|Optional|
+|mode|"c15t" \|"custom" \|"hosted" \|"offline" \|undefined|Operating mode - custom endpoint implementation|-|Optional|
+|backendURL|string \|undefined|Backend URL is not used in custom mode|-|Optional|
+|enabled|boolean \|undefined|Whether c15t should be active.|-|Optional|
+|callbacks|Callbacks \|undefined|Event callbacks for consent actions.|-|Optional|
+|scripts|Script \|undefined|Dynamically load scripts based on consent state.|-|Optional|
+|legalLinks|Partial\<Record\<keyof LegalLinksTranslations, LegalLink>> \|undefined|Configuration for the legal links.|-|Optional|
+|user|User \|undefined|The user's information. Usually your own internal ID for the user from your auth provider.|-|Optional|
+|overrides|Overrides \|undefined|Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.|-|Optional|
+|networkBlocker|NetworkBlockerConfig \|undefined|Configuration for the network request blocker.|-|Optional|
+|iab|IABConfig \|undefined|IAB TCF 2.3 configuration.|-|Optional|
+|ssrData|Promise\<SSRInitialData \|undefined> \|undefined|SSR-prefetched data for hydration.|-|Optional|
+|theme|Theme \|undefined|Visual theme to apply.|-|Optional|
+|disableAnimation|boolean \|undefined|Whether to disable animations.|-|Optional|
+|scrollLock|boolean \|undefined|Whether to lock scroll when dialogs are open.|-|Optional|
+|trapFocus|boolean \|undefined|Whether to trap focus within dialogs.|-|Optional|
+|colorScheme|"light" \|"dark" \|"system" \|undefined|Color scheme preference. With this option, you can force the theme to be light, dark or system. Otherwise, the theme will be detected if you have '.dark' classname in your document.|-|Optional|
+|noStyle|boolean \|undefined|Whether to disable default styles.|-|Optional|
+|i18n|I18nConfig \|undefined|Preferred i18n configuration in c15t v2.|-|Optional|
+|translations|TranslationConfig \|undefined|Translation configuration to seed the store with.|-|Optional|
+|consentCategories|AllConsentNames \|undefined|Consent categories to show in the consent banner.|-|Optional|

package/docs/components/consent-widget.md

@@ -0,0 +1,133 @@
+---
+title: ConsentWidget
+description: An inline consent management widget for embedding in settings or privacy pages. Shows category toggles with accordion layout.
+---
+`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.
+
+## Basic Usage
+
+```tsx
+import { ConsentWidget } from '@c15t/nextjs';
+
+export function PrivacySettingsPage() {
+  return (
+    <>
+      <h1>Privacy Settings</h1>
+      <p>Manage your cookie preferences below.</p>
+      <ConsentWidget />
+    </>
+  );
+}
+```
+
+## Configuration
+
+```tsx
+<ConsentWidget
+  hideBranding
+  legalLinks={['privacyPolicy', 'cookiePolicy']}
+  noStyle={false}
+  disableAnimation={false}
+/>
+```
+
+## Accordion Behavior
+
+Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
+
+## Styling First
+
+> ℹ️ **Info:**
+> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, and toggle before reaching for compound components. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentWidgetAccordion: 'rounded-3xl border border-black/10',
+        consentWidgetFooter: 'border-t border-black/10 px-6',
+        toggle: 'shadow-sm',
+      },
+    },
+  }}
+>
+  <ConsentWidget />
+</ConsentManagerProvider>
+```
+
+Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
+
+## Advanced: Compound Components
+
+Use compound components only when you need to rearrange the widget's existing primitives while keeping policy-aware action grouping:
+
+```tsx
+<ConsentWidget.Root>
+  <ConsentWidget.Accordion type="multiple">
+    <ConsentWidget.AccordionItems />
+  </ConsentWidget.Accordion>
+  <ConsentWidget.PolicyActions />
+</ConsentWidget.Root>
+```
+
+* `ConsentWidget.Root` — Theme context provider
+* `ConsentWidget.Accordion` — Radix-based accordion root
+* `ConsentWidget.AccordionItems` — Auto-generates toggle items from consent config
+* `ConsentWidget.AccordionItem` — Individual category item
+* `ConsentWidget.AccordionTrigger` — Clickable header for each item
+* `ConsentWidget.AccordionContent` — Collapsible content area
+* `ConsentWidget.AccordionArrow` — Expand/collapse indicator
+* `ConsentWidget.Switch` — Category toggle switch
+* `ConsentWidget.PolicyActions` — Renders grouped policy-aware actions
+* `ConsentWidget.Footer` — Footer container
+* `ConsentWidget.FooterSubGroup` — Groups related buttons
+* `ConsentWidget.AcceptAllButton` — Accepts all consent
+* `ConsentWidget.RejectButton` — Rejects all consent
+* `ConsentWidget.SaveButton` — Saves custom selections
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentWidget.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentWidget.PolicyActions />
+```
+
+`renderAction` is optional. Return the stock button compounds when you want custom mapping while preserving built-in c15t behavior and copy:
+
+```tsx
+<ConsentWidget.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentWidget.AcceptAllButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentWidget.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentWidget.SaveButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+`renderAction` is still meant for stock button compounds. If you want completely custom button elements and handlers, use `useHeadlessConsentUI()` and render `dialog.actionGroups` manually instead of `ConsentWidget.PolicyActions`.
+
+For a fixed footer layout, render `ConsentWidget.Footer` and `ConsentWidget.FooterSubGroup` manually instead of using `ConsentWidget.PolicyActions`.
+
+If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
+
+## Props
+
+### ConsentWidgetProps
+
+|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|

package/docs/components/dev-tools.md

@@ -0,0 +1,63 @@
+---
+title: DevTools
+description: A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
+---
+`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:**
+> DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
+
+## Installation
+
+DevTools lives in a separate package to keep it out of production bundles:
+
+```bash
+bun add -D @c15t/dev-tools
+```
+
+## Usage
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { DevTools } from '@c15t/dev-tools/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: '/api/c15t' }}>
+      {children}
+      {process.env.NODE_ENV === 'development' && <DevTools />}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Configuration
+
+```tsx
+<DevTools
+  position="bottom-right"  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  defaultOpen={false}       // Start with panel open
+  namespace="c15tStore"     // Store namespace to connect to
+  disabled={false}          // Disable without removing from tree
+/>
+```
+
+## Panels
+
+|Panel|What it shows|
+|--|--|
+|**Consents**|Current consent state for all categories|
+|**Location**|Detected jurisdiction, country, region, and consent model|
+|**Scripts**|Configured scripts and their load status|
+|**IAB**|IAB TCF state (when enabled) - TC string, vendor consents, purposes|
+|**Events**|Timeline of consent events and state changes|
+|**Actions**|Buttons to trigger consent actions (accept all, reject all, reset)|
+
+## Props
+
+### C15TDevToolsProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disabled|boolean \|undefined|Whether the DevTools should be disabled Useful for production builds|false|Optional|