@c15t/nextjs 2.0.0-rc.3 → 2.0.0-rc.5

package/client/components/consent-dialog-link.js

@@ -0,0 +1,3 @@
+'use client';
+
+export * from '@c15t/react/components/consent-dialog-link';

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_modules__={"./libs/initial-data"(_){_.exports=require("./libs/initial-data.cjs")},"@c15t/react"(_){_.exports=require("@c15t/react")}},__webpack_module_cache__={};function __webpack_require__(_){var e=__webpack_module_cache__[_];if(void 0!==e)return e.exports;var r=__webpack_module_cache__[_]={exports:{}};return __webpack_modules__[_](r,r.exports,__webpack_require__),r.exports}__webpack_require__.n=_=>{var e=_&&_.__esModule?()=>_.default:()=>_;return __webpack_require__.d(e,{a:e}),e},__webpack_require__.d=(_,e)=>{for(var r in e)__webpack_require__.o(e,r)&&!__webpack_require__.o(_,r)&&Object.defineProperty(_,r,{enumerable:!0,get:e[r]})},__webpack_require__.o=(_,e)=>Object.prototype.hasOwnProperty.call(_,e),__webpack_require__.r=_=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(_,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(_,"__esModule",{value:!0})};var __webpack_exports__={};for(var __rspack_i in(()=>{__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{fetchInitialData:()=>r.fetchInitialData});var _=__webpack_require__("@c15t/react"),e={};for(let r in _)0>["fetchInitialData","default"].indexOf(r)&&(e[r]=()=>_[r]);__webpack_require__.d(__webpack_exports__,e);var r=__webpack_require__("./libs/initial-data")})(),exports.fetchInitialData=__webpack_exports__.fetchInitialData,__webpack_exports__)-1===["fetchInitialData"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_modules__={"./libs/browser-initial-data"(e){e.exports=require("./libs/browser-initial-data.cjs")},"./libs/initial-data"(e){e.exports=require("./libs/initial-data.cjs")},"@c15t/react"(e){e.exports=require("@c15t/react")},c15t(e){e.exports=require("c15t")}},__webpack_module_cache__={};function __webpack_require__(e){var _=__webpack_module_cache__[e];if(void 0!==_)return _.exports;var t=__webpack_module_cache__[e]={exports:{}};return __webpack_modules__[e](t,t.exports,__webpack_require__),t.exports}__webpack_require__.n=e=>{var _=e&&e.__esModule?()=>e.default:()=>e;return __webpack_require__.d(_,{a:_}),_},__webpack_require__.d=(e,_)=>{for(var t in _)__webpack_require__.o(_,t)&&!__webpack_require__.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:_[t]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};for(var __rspack_i in(()=>{__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{C15tPrefetch:()=>r.C15tPrefetch,buildPrefetchScript:()=>t.buildPrefetchScript,ensurePrefetchedInitialData:()=>t.ensurePrefetchedInitialData,fetchInitialData:()=>a.fetchInitialData,getPrefetchedInitialData:()=>t.getPrefetchedInitialData});var e=__webpack_require__("@c15t/react"),_={};for(let t in e)0>["C15tPrefetch","fetchInitialData","default","buildPrefetchScript","ensurePrefetchedInitialData","getPrefetchedInitialData"].indexOf(t)&&(_[t]=()=>e[t]);__webpack_require__.d(__webpack_exports__,_);var t=__webpack_require__("c15t"),r=__webpack_require__("./libs/browser-initial-data"),a=__webpack_require__("./libs/initial-data")})(),exports.C15tPrefetch=__webpack_exports__.C15tPrefetch,exports.buildPrefetchScript=__webpack_exports__.buildPrefetchScript,exports.ensurePrefetchedInitialData=__webpack_exports__.ensurePrefetchedInitialData,exports.fetchInitialData=__webpack_exports__.fetchInitialData,exports.getPrefetchedInitialData=__webpack_exports__.getPrefetchedInitialData,__webpack_exports__)-1===["C15tPrefetch","buildPrefetchScript","ensurePrefetchedInitialData","fetchInitialData","getPrefetchedInitialData"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/index.js

@@ -1 +1 @@
-import{fetchInitialData as t}from"./libs/initial-data.js";export*from"@c15t/react";export{t as fetchInitialData};
+import{buildPrefetchScript as t,ensurePrefetchedInitialData as i,getPrefetchedInitialData as e}from"c15t";import{C15tPrefetch as r}from"./libs/browser-initial-data.js";import{fetchInitialData as a}from"./libs/initial-data.js";export*from"@c15t/react";export{r as C15tPrefetch,t as buildPrefetchScript,i as ensurePrefetchedInitialData,a as fetchInitialData,e as getPrefetchedInitialData};

package/dist/libs/browser-initial-data.cjs

@@ -0,0 +1 @@
+"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.n=e=>{var _=e&&e.__esModule?()=>e.default:()=>e;return __webpack_require__.d(_,{a:_}),_},__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{C15tPrefetch:()=>C15tPrefetch});const jsx_runtime_namespaceObject=require("react/jsx-runtime"),external_c15t_namespaceObject=require("c15t"),script_namespaceObject=require("next/script");var script_default=__webpack_require__.n(script_namespaceObject);const DEFAULT_SCRIPT_ID="c15t-initial-data-prefetch";function C15tPrefetch({id:e="c15t-initial-data-prefetch",..._}){return(0,jsx_runtime_namespaceObject.jsx)(script_default(),{id:e,strategy:"beforeInteractive",children:(0,external_c15t_namespaceObject.buildPrefetchScript)(_)})}for(var __rspack_i in exports.C15tPrefetch=__webpack_exports__.C15tPrefetch,__webpack_exports__)-1===["C15tPrefetch"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/libs/browser-initial-data.js

@@ -0,0 +1 @@
+import{jsx as t}from"react/jsx-runtime";import{buildPrefetchScript as r}from"c15t";import e from"next/script";function i({id:i="c15t-initial-data-prefetch",...c}){return t(e,{id:i,strategy:"beforeInteractive",children:r(c)})}export{i as C15tPrefetch};

package/dist/libs/initial-data.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{fetchInitialData:()=>fetchInitialData});const server_namespaceObject=require("@c15t/react/server"),headers_namespaceObject=require("next/headers");async function fetchInitialData(e){let _=await (0,headers_namespaceObject.headers)();return(0,server_namespaceObject.fetchSSRData)({...e,headers:_})}for(var __rspack_i in exports.fetchInitialData=__webpack_exports__.fetchInitialData,__webpack_exports__)-1===["fetchInitialData"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{fetchInitialData:()=>fetchInitialData});const server_namespaceObject=require("@c15t/react/server"),cache_namespaceObject=require("next/cache"),headers_namespaceObject=require("next/headers"),DEFAULT_REVALIDATE_SECONDS=1;async function fetchInitialData(e){let _=await (0,headers_namespaceObject.headers)(),r=(0,server_namespaceObject.normalizeBackendURL)(e.backendURL,_);if(!r)return;let a=e.nextCache?.revalidateSeconds;if(!1===a)return(0,server_namespaceObject.fetchSSRData)({...e,backendURL:r,headers:_});let t=(0,server_namespaceObject.createSSRInitCacheKey)({normalizedURL:r,headers:_,overrides:e.overrides});return(0,cache_namespaceObject.unstable_cache)(()=>(0,server_namespaceObject.fetchSSRData)({...e,backendURL:r,headers:_}),["c15t:nextjs:fetchInitialData",t],{revalidate:a??1})()}for(var __rspack_i in exports.fetchInitialData=__webpack_exports__.fetchInitialData,__webpack_exports__)-1===["fetchInitialData"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/libs/initial-data.js

@@ -1 +1 @@
-import{fetchSSRData as t}from"@c15t/react/server";import{headers as e}from"next/headers";async function r(r){let a=await e();return t({...r,headers:a})}export{r as fetchInitialData};
+import{createSSRInitCacheKey as e,fetchSSRData as t,normalizeBackendURL as a}from"@c15t/react/server";import{unstable_cache as r}from"next/cache";import{headers as n}from"next/headers";async function c(c){let i=await n(),o=a(c.backendURL,i);if(!o)return;let d=c.nextCache?.revalidateSeconds;return!1===d?t({...c,backendURL:o,headers:i}):r(()=>t({...c,backendURL:o,headers:i}),["c15t:nextjs:fetchInitialData",e({normalizedURL:o,headers:i,overrides:c.overrides})],{revalidate:d??1})()}export{c as fetchInitialData};

package/dist/version.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{version:()=>version});const version="2.0.0-rc.3";for(var __rspack_i in exports.version=__webpack_exports__.version,__webpack_exports__)-1===["version"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"use strict";const __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{version:()=>version});const version="2.0.0-rc.5";for(var __rspack_i in exports.version=__webpack_exports__.version,__webpack_exports__)-1===["version"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/version.js

@@ -1 +1 @@
-let e="2.0.0-rc.3";export{e as version};
+let e="2.0.0-rc.5";export{e as version};

package/dist-types/headless.d.ts

@@ -0,0 +1 @@
+export * from '../../react/dist-types/headless.d';

package/{dist → dist-types}/index.d.ts

@@ -7,7 +7,8 @@
  * @see {@link @c15t/react} for React components and hooks
  * @see {@link ./middleware} for Next.js middleware integration
  */
-export * from '@c15t/react';
+export * from '../../react/dist-types/index.d.ts';
+export { buildPrefetchScript, ensurePrefetchedInitialData, getPrefetchedInitialData, type PrefetchOptions, } from '../../core/dist-types/index.d.ts';
+export { C15tPrefetch } from './libs/browser-initial-data';
 export { fetchInitialData } from './libs/initial-data';
-export type { FetchInitialDataOptions, InitialDataPromise, ConsentManagerProps, } from './types';
-//# sourceMappingURL=index.d.ts.map
+export type { C15tPrefetchProps, ConsentManagerProps, FetchInitialDataOptions, InitialDataPromise, } from './types';

package/dist-types/libs/browser-initial-data.d.ts

@@ -0,0 +1,9 @@
+import type { C15tPrefetchProps } from '../types';
+/**
+ * Next.js script component that starts `/init` prefetching before hydration.
+ *
+ * @remarks
+ * Use in `app/layout.tsx` for static routes. Pair with
+ * `getPrefetchedInitialData()` or `ensurePrefetchedInitialData()` in your client provider.
+ */
+export declare function C15tPrefetch({ id, ...options }: C15tPrefetchProps): import("react/jsx-runtime").JSX.Element;

package/{dist → dist-types}/libs/initial-data.d.ts

@@ -1,4 +1,4 @@
-import type { SSRInitialData } from 'c15t';
+import type { SSRInitialData } from '../../../core/dist-types/index.d.ts';
 import type { FetchInitialDataOptions } from '../types';
 /**
  * Fetches initial consent data on the server for SSR hydration.
@@ -25,4 +25,3 @@ import type { FetchInitialDataOptions } from '../types';
  * ```
  */
 export declare function fetchInitialData(options: FetchInitialDataOptions): Promise<SSRInitialData | undefined>;
-//# sourceMappingURL=initial-data.d.ts.map

package/dist-types/types.d.ts

@@ -0,0 +1,38 @@
+import type { ConsentManagerProviderProps } from '../../react/dist-types/index.d.ts';
+import type { FetchSSRDataOptionsBase } from '../../react/dist-types/server';
+import type { PrefetchOptions } from '../../core/dist-types/index.d.ts';
+export type InitialDataPromise = NonNullable<ConsentManagerProviderProps['options']['store']>['ssrData'];
+export interface NextCacheOptions {
+    /**
+     * Cache lifetime in seconds for the Next.js data cache.
+     * Set to false to disable Next.js caching for this call.
+     *
+     * @default 1
+     */
+    revalidateSeconds?: number | false;
+}
+export interface C15tPrefetchProps extends PrefetchOptions {
+    /**
+     * Optional script element ID.
+     *
+     * @default 'c15t-initial-data-prefetch'
+     */
+    id?: string;
+}
+/**
+ * Options for the fetchInitialData function.
+ *
+ * @remarks
+ * Uses the base options from @c15t/react/server - headers are
+ * resolved automatically from Next.js.
+ */
+export interface FetchInitialDataOptions extends FetchSSRDataOptionsBase {
+    /**
+     * Optional Next.js cache controls for SSR init requests.
+     */
+    nextCache?: NextCacheOptions;
+}
+export interface ConsentManagerProps {
+    children: React.ReactNode;
+    ssrData?: InitialDataPromise;
+}

package/dist-types/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "2.0.0-rc.5";

package/docs/README.md

@@ -0,0 +1,73 @@
+# c15t Next.js Docs
+
+Next.js-focused c15t docs for consent UI, server-side behavior, callbacks, and integrations.
+
+If you are changing consent flows, consent UI, script loading, server-side setup, or backend configuration in an app that uses this package, start here before editing code.
+
+## Start Here
+
+- [Quickstart](./quickstart.md)
+- [Server Side](./server-side.md)
+- [Callbacks](./callbacks.md)
+- [Script Loader](./script-loader.md)
+- [Google Tag Manager](./integrations/google-tag-manager.md)
+
+## Workflow Rules
+
+### Server-Side Setup
+
+Use this when:
+- working on App Router or SSR consent initialization
+- connecting the provider to server-fetched consent data
+- deciding whether client-only setup is sufficient
+
+Prefer:
+- Prefer the documented server helpers and provider setup.
+- Use the server-side integration path before inventing custom cookie or init plumbing.
+
+Avoid:
+- Do not default to client-only initialization when the documented SSR flow already covers the use case.
+
+Read next:
+- [Quickstart](./quickstart.md)
+- [Server Side](./server-side.md)
+
+### Styling
+
+Use this when:
+- customizing component appearance in a Next.js app
+- deciding how to override the default consent UI
+
+Prefer:
+- Prefer design tokens first.
+- If tokens are not enough, use component slots.
+- Then use CSS variables or `className` for targeted overrides.
+
+If that is not enough:
+- Use `noStyle` or headless only as a last resort.
+
+Avoid:
+- Do not rebuild the consent UI if the documented styling layers can express the design.
+
+Read next:
+- [Overview](./styling/overview.md)
+- [Tokens](./styling/tokens.md)
+- [Slots](./styling/slots.md)
+
+### Scripts & Integrations
+
+Use this when:
+- wiring scripts through Next.js routes, layouts, or providers
+- adding analytics or advertising behind consent
+
+Prefer:
+- Prefer premade scripts from `@c15t/scripts/*`.
+- Start from the integration docs before wiring scripts through Next-specific code paths.
+
+Avoid:
+- Do not use custom script injection when a documented integration already exists.
+
+Read next:
+- [Script Loader](./script-loader.md)
+- [Google Tag Manager](./integrations/google-tag-manager.md)
+- [Meta Pixel](./integrations/meta-pixel.md)

package/docs/building-headless-components.md

@@ -0,0 +1,250 @@
+---
+title: Building Headless Components
+description: Build policy-aware custom consent components in Next.js using the headless hooks and policy-pack tooling.
+---
+Building headless components is easier now because c15t exposes policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
+
+The headless stack is:
+
+* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary action hints
+* `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
+* `useTranslations()` for the resolved copy
+* `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution
+
+> ℹ️ **Info:**
+> This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
+
+## What the Headless Tooling Gives You
+
+The main win is that your custom UI can stay aligned with policy packs without duplicating policy logic in your components.
+
+`useHeadlessConsentUI()` already resolves:
+
+* which actions are allowed
+* the order those actions should render in
+* grouped actions from policy `layout`
+* layout `direction` (`row` or `column`)
+* the primary action
+* UI profile and scroll-lock hints
+* whether the banner or dialog should currently be visible
+
+That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.
+
+## Provider Setup for Local Policy Testing
+
+```tsx title="components/consent-manager/provider.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentManagerProvider,
+  policyPackPresets,
+} from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'offline',
+        offlinePolicy: {
+          policyPacks: [
+            policyPackPresets.californiaOptOut(),
+            policyPackPresets.europeOptIn(),
+            policyPackPresets.worldNoBanner(),
+          ],
+        },
+        overrides: {
+          country: 'GB',
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Policy-Aware Banner Example
+
+```tsx title="components/consent-manager/custom-banner.tsx"
+'use client';
+
+import { useHeadlessConsentUI, useTranslations } from '@c15t/nextjs/headless';
+
+export function CustomConsentBanner() {
+  const { banner, openDialog, performAction } = useHeadlessConsentUI();
+  const translations = useTranslations();
+
+  if (!banner.isVisible) return null;
+
+  return (
+    <aside className="rounded-xl border bg-white p-6 shadow-lg">
+      <h2 className="text-lg font-semibold">{translations.cookieBanner.title}</h2>
+      <p className="mt-2 text-sm text-gray-600">
+        {translations.cookieBanner.description}
+      </p>
+
+      <div className="mt-4 space-y-2">
+        {banner.actionGroups.map((group, index) => (
+          <div key={`${group.join('-')}-${index}`} className="flex gap-2">
+            {group.map((action) => (
+              <button
+                key={action}
+                type="button"
+                className={action === banner.primaryAction ? 'btn-primary' : 'btn-secondary'}
+                onClick={() => {
+                  if (action === 'customize') {
+                    openDialog();
+                    return;
+                  }
+                  void performAction(action, { surface: 'banner' });
+                }}
+              >
+                {action === 'accept'
+                  ? translations.common.acceptAll
+                  : action === 'reject'
+                    ? translations.common.rejectAll
+                    : translations.common.customize}
+              </button>
+            ))}
+          </div>
+        ))}
+      </div>
+    </aside>
+  );
+}
+```
+
+## Category List That Respects the Resolved Policy
+
+```tsx title="components/consent-manager/custom-dialog.tsx"
+'use client';
+
+import {
+  useConsentManager,
+  useHeadlessConsentUI,
+  useTranslations,
+} from '@c15t/nextjs/headless';
+
+export function CustomConsentDialog() {
+  const { dialog, performDialogAction, saveCustomPreferences } = useHeadlessConsentUI();
+  const {
+    consentTypes,
+    consentCategories,
+    consents,
+    selectedConsents,
+    setSelectedConsent,
+  } = useConsentManager();
+  const translations = useTranslations();
+
+  if (!dialog.isVisible) return null;
+
+  const displayedTypes = consentTypes.filter(
+    (type) => type.display && consentCategories.includes(type.name)
+  );
+
+  return (
+    <section className="rounded-xl border bg-white p-6 shadow-xl">
+      <h2 className="text-lg font-semibold">
+        {translations.consentManagerDialog.title}
+      </h2>
+
+      <div className="mt-4 space-y-3">
+        {displayedTypes.map((type) => (
+          <label key={type.name} className="flex items-start justify-between gap-4">
+            <div>
+              <p className="font-medium">
+                {translations.consentTypes[type.name]?.title ?? type.name}
+              </p>
+              <p className="text-sm text-gray-600">{type.description}</p>
+            </div>
+            <input
+              type="checkbox"
+              checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
+              disabled={type.disabled}
+              onChange={(event) =>
+                setSelectedConsent(type.name, event.target.checked)
+              }
+            />
+          </label>
+        ))}
+      </div>
+
+      <div className="mt-4 flex gap-2">
+        {dialog.orderedActions.map((action) => (
+          <button
+            key={action}
+            type="button"
+            onClick={() => {
+              if (action === 'customize') {
+                void saveCustomPreferences();
+                return;
+              }
+              void performDialogAction(action);
+            }}
+          >
+            {action === 'accept'
+              ? translations.common.acceptAll
+              : action === 'reject'
+                ? translations.common.rejectAll
+                : translations.common.save}
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+```
+
+## What a Policy-Aware Headless Component Should Respect
+
+When you build custom banner or dialog components, make sure they use:
+
+* `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
+* `allowedActions`, `orderedActions`, or `actionGroups` instead of hard-coding buttons
+* `primaryAction` for visual emphasis
+* `consentCategories` when deciding which category toggles to render
+* `policyDecision` when you want to debug why a specific UI state was chosen
+
+If you ignore those values, your custom UI can drift away from the resolved policy pack even though the underlying consent engine is configured correctly.
+
+## Test Custom UI Against the Resolved Policy
+
+```ts
+import {
+  getEffectivePolicy,
+  type PolicyUIState,
+  validateUIAgainstPolicy,
+} from 'c15t';
+
+const policy = getEffectivePolicy(initData);
+
+const dialogState: PolicyUIState = {
+  mode: 'dialog',
+  actions: ['accept', 'reject', 'customize'],
+  layout: 'split',
+  uiProfile: 'compact',
+  scrollLock: true,
+};
+
+const issues = validateUIAgainstPolicy({
+  policy,
+  state: dialogState,
+});
+
+expect(issues).toEqual([]);
+```
+
+## Validation and Testing
+
+If you are building a reusable headless component library, validate your rendered UI against the resolved runtime policy in tests.
+
+The core package exposes:
+
+* `getEffectivePolicy(initData)` to read the resolved policy from `/init`
+* `validateUIAgainstPolicy({ policy, state })` to detect mismatches such as wrong actions, layout, or mode
+
+This is useful when your design system renders custom button arrangements and you want tests to catch policy drift early.
+
+> ℹ️ **Info:**
+> Pair this with Policy Packs when you want to exercise multiple regional UI states locally before wiring a live backend.

package/docs/callbacks.md

@@ -0,0 +1,117 @@
+---
+title: Callbacks
+description: React to consent lifecycle events - initialization, consent changes, errors, and revocation reloads.
+---
+Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider's `callbacks` option, or register them dynamically via `useConsentManager()`.
+
+## Configuration
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        callbacks: {
+          onBannerFetched: ({ jurisdiction, location, translations }) => {
+            console.log('Jurisdiction:', jurisdiction);
+            console.log('Country:', location.countryCode);
+            console.log('Language:', translations.language);
+          },
+          onConsentSet: ({ preferences }) => {
+            // Fire analytics event
+            analytics.track('consent_updated', { preferences });
+          },
+          onError: ({ error }) => {
+            errorReporter.captureMessage(error);
+          },
+          onBeforeConsentRevocationReload: ({ preferences }) => {
+            // Flush pending analytics before page reloads
+            analytics.flush();
+          },
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Available Callbacks
+
+### `onBannerFetched`
+
+Called when the consent banner data is fetched from the backend (or loaded from SSR data). The payload includes jurisdiction info, location data, and resolved translations.
+
+```tsx
+onBannerFetched: ({ jurisdiction, location, translations }) => {
+  // jurisdiction: 'GDPR' | 'CCPA' | { code: 'GDPR', message: '...' } | ...
+  // location: { countryCode: 'DE', regionCode: 'BY' }
+  // translations: { language: 'de', translations: {...} }
+}
+```
+
+### `onConsentSet`
+
+Called whenever consent preferences are saved - whether by user action (`saveConsents()`), automatic defaults, or on initialization when no jurisdiction is detected.
+
+```tsx
+onConsentSet: ({ preferences }) => {
+  // preferences: { necessary: true, measurement: true, marketing: false, ... }
+  if (preferences.measurement) {
+    loadAnalytics();
+  }
+}
+```
+
+### `onError`
+
+Called when an error occurs during consent operations (e.g., API request failure). If no `onError` callback is provided, errors are logged to `console.error`.
+
+```tsx
+onError: ({ error }) => {
+  // error: string describing what went wrong
+  Sentry.captureMessage(`Consent error: ${error}`);
+}
+```
+
+### `onBeforeConsentRevocationReload`
+
+Called synchronously before the page reloads due to consent revocation. This is your last chance to run cleanup before the reload. Keep this callback fast - avoid async operations.
+
+```tsx
+onBeforeConsentRevocationReload: ({ preferences }) => {
+  // Flush any pending data
+  navigator.sendBeacon('/api/flush', JSON.stringify({ session: sessionId }));
+}
+```
+
+## Dynamic Registration
+
+Register or update callbacks at runtime using `setCallback()`:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@c15t/nextjs';
+
+function ConsentAnalytics() {
+  const { setCallback } = useConsentManager();
+
+  useEffect(() => {
+    setCallback('onConsentSet', ({ preferences }) => {
+      analytics.track('consent_changed', preferences);
+    });
+
+    return () => {
+      setCallback('onConsentSet', undefined);
+    };
+  }, [setCallback]);
+
+  return null;
+}
+```