@c15t/nextjs 2.0.0-rc.6 → 2.0.0-rc.8

package/README.md

@@ -63,6 +63,13 @@ The CLI will:
 pnpm add @c15t/nextjs
 ```
 
+Then add the prebuilt stylesheet to your app-level CSS entrypoint:
+
+```css
+/* app/globals.css */
+@import "@c15t/nextjs/styles.css";
+```
+
 To manually install, follow the guide in our [docs – manual setup](https://c15t.com/docs/frameworks/nextjs/quickstart#manual-setup).
 
 ## Usage

package/dist/iab/styles.css

@@ -1 +1,12 @@
-@import "@c15t/react/iab/styles.css";
+/**
+ * @c15t/nextjs — IAB TCF component styles.
+ *
+ * Add this stylesheet to the same global CSS entrypoint as your base c15t styles
+ * when using IAB consent components in Next.js. Do not import either stylesheet
+ * from JS/TSX.
+ *
+ * Usage (app/globals.css):
+ *   @import "@c15t/nextjs/styles.css";
+ *   @import "@c15t/nextjs/iab/styles.css";
+ */
+@import "@c15t/react/iab/styles.css";

package/dist/iab/styles.tw3.css

@@ -0,0 +1,14 @@
+/**
+ * @c15t/nextjs/iab — Tailwind 3-compatible IAB component styles.
+ *
+ * Add this stylesheet to the same global CSS entrypoint as your base c15t styles.
+ * Do not import either stylesheet from JS/TSX files.
+ *
+ * Usage (app/globals.css):
+ *   @tailwind base;
+ *   @tailwind components;
+ *   @import "@c15t/nextjs/styles.tw3.css";
+ *   @import "@c15t/nextjs/iab/styles.tw3.css";
+ *   @tailwind utilities;
+ */
+@import "@c15t/react/iab/styles.tw3.css";

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="u"<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=>{"u">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});
+"use strict";const __rslib_import_meta_url__="u"<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 r=__webpack_module_cache__[e]={exports:{}};return __webpack_modules__[e](r,r.exports,__webpack_require__),r.exports}__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=>{"u">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:()=>t.C15tPrefetch,buildPrefetchScript:()=>r.buildPrefetchScript,fetchInitialData:()=>a.fetchInitialData});var e=__webpack_require__("@c15t/react"),_={};for(let r in e)0>["fetchInitialData","default","buildPrefetchScript","C15tPrefetch"].indexOf(r)&&(_[r]=()=>e[r]);__webpack_require__.d(__webpack_exports__,_);var r=__webpack_require__("c15t"),t=__webpack_require__("./libs/browser-initial-data"),a=__webpack_require__("./libs/initial-data")})(),exports.C15tPrefetch=__webpack_exports__.C15tPrefetch,exports.buildPrefetchScript=__webpack_exports__.buildPrefetchScript,exports.fetchInitialData=__webpack_exports__.fetchInitialData,__webpack_exports__)-1===["C15tPrefetch","buildPrefetchScript","fetchInitialData"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/index.js

@@ -1 +1 @@
-export*from"@c15t/react";export{buildPrefetchScript,ensurePrefetchedInitialData,getPrefetchedInitialData}from"c15t";export{C15tPrefetch}from"./libs/browser-initial-data.js";export{fetchInitialData}from"./libs/initial-data.js";
+export*from"@c15t/react";export{buildPrefetchScript}from"c15t";export{C15tPrefetch}from"./libs/browser-initial-data.js";export{fetchInitialData}from"./libs/initial-data.js";

package/dist/styles.css

@@ -1 +1,10 @@
-@import "@c15t/react/styles.css";
+/**
+ * @c15t/nextjs — Non-IAB prebuilt component styles.
+ *
+ * Import this stylesheet once from your app-level CSS entrypoint when using
+ * prebuilt (styled) consent components.
+ *
+ * Usage (app/globals.css):
+ *   @import "@c15t/nextjs/styles.css";
+ */
+@import "@c15t/react/styles.css";

package/dist/styles.tw3.css

@@ -0,0 +1,13 @@
+/**
+ * @c15t/nextjs — Tailwind 3-compatible prebuilt component styles.
+ *
+ * Import this stylesheet in the same global CSS entrypoint as Tailwind 3,
+ * after `@tailwind components;` and before `@tailwind utilities;`.
+ *
+ * Usage (app/globals.css):
+ *   @tailwind base;
+ *   @tailwind components;
+ *   @import "@c15t/nextjs/styles.tw3.css";
+ *   @tailwind utilities;
+ */
+@import "@c15t/react/styles.tw3.css";

package/dist/version.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="u"<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=>{"u">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.6";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__="u"<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=>{"u">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.8";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.6";export{e as version};
+let e="2.0.0-rc.8";export{e as version};

package/dist-types/headless.d.ts

@@ -1 +1 @@
-export * from '../../react/dist-types/headless';
+export * from '@c15t/react/headless';

package/dist-types/index.d.ts

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

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

@@ -3,7 +3,7 @@ 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.
+ * Use in `app/layout.tsx` for static routes. Matching prefetched data is
+ * consumed automatically by the runtime during first store initialization.
  */
 export declare function C15tPrefetch({ id, ...options }: C15tPrefetchProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,4 +1,4 @@
-import type { SSRInitialData } from '../../../core/dist-types/index.d.ts';
+import type { SSRInitialData } from 'c15t';
 import type { FetchInitialDataOptions } from '../types';
 /**
  * Fetches initial consent data on the server for SSR hydration.

package/dist-types/types.d.ts

@@ -1,6 +1,6 @@
-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';
+import type { ConsentManagerProviderProps } from '@c15t/react';
+import type { FetchSSRDataOptionsBase } from '@c15t/react/server';
+import type { PrefetchOptions } from 'c15t';
 export type InitialDataPromise = NonNullable<ConsentManagerProviderProps['options']['store']>['ssrData'];
 export interface NextCacheOptions {
     /**

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.0-rc.6";
+export declare const version = "2.0.0-rc.8";

package/docs/building-headless-components.md

@@ -2,15 +2,27 @@
 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.
+Building custom consent UI is easier now because c15t exposes multiple layers of policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
 
-The headless stack is:
+The layering is:
+
+* stock component props for the shortest path
+* `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` for custom structure with policy-aware actions
+* `useHeadlessConsentUI()` for fully manual action rendering and non-standard controls
+
+> ⚠️ **Warning:**
+> Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.
+
+The headless stack underneath that is:
 
 * `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints
+* `@c15t/ui/utils` for the pure policy-action helpers that framework packages build on
 * `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
 
+The split is intentional: `@c15t/ui` owns pure policy-action resolution, while the framework hooks own visibility, consent mutations, and reactive state.
+
 > ℹ️ **Info:**
 > This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
 
@@ -30,6 +42,11 @@ The main win is that your custom UI can stay aligned with policy packs without d
 
 That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.
 
+For most compound-component layouts, start with `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions`. They render stock c15t buttons and translations by default, and `renderAction` is only needed when you want to override the action mapping. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
+
+> ℹ️ **Info:**
+> For custom layouts built from c15t compound components, prefer ConsentBanner.PolicyActions and ConsentWidget.PolicyActions. The examples below intentionally use manual actionGroups mapping to show the fully headless escape hatch.
+
 ## Provider Setup for Local Policy Testing
 
 ```tsx title="components/consent-manager/provider.tsx"
@@ -170,25 +187,29 @@ export function CustomConsentDialog() {
         ))}
       </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 className="mt-4 space-y-2">
+        {dialog.actionGroups.map((group, index) => (
+          <div key={`${group.join('-')}-${index}`} className="flex gap-2">
+            {group.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>
         ))}
       </div>
     </section>
@@ -201,7 +222,7 @@ export function CustomConsentDialog() {
 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
+* `allowedActions`, `actionGroups`, and `primaryActions` instead of hard-coding buttons
 * `primaryActions` for visual emphasis
 * `consentCategories` when deciding which category toggles to render
 * `policyDecision` when you want to debug why a specific UI state was chosen

package/docs/callbacks.md

@@ -2,7 +2,12 @@
 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()`.
+Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider or runtime `callbacks` option, or register them dynamically after initialization.
+
+For analytics SDKs and other change-only integrations, prefer `subscribeToConsentChanges()` or `onConsentChanged`. Use `onConsentSet` when you want the broader lifecycle signal, including initialization, automatic defaults, and replay-aware registration.
+
+> ℹ️ **Info:**
+> subscribeToConsentChanges() is the recommended API for analytics SDKs and consent-mode integrations. It only emits future saves that actually changed persisted preferences.
 
 ## Configuration
 
@@ -23,8 +28,10 @@ export function ConsentManager({ children }: { children: ReactNode }) {
             console.log('Language:', translations.language);
           },
           onConsentSet: ({ preferences }) => {
-            // Fire analytics event
-            analytics.track('consent_updated', { preferences });
+            console.log('Consent lifecycle event:', preferences);
+          },
+          onConsentChanged: ({ allowedCategories, deniedCategories }) => {
+            analytics.syncConsent({ allowedCategories, deniedCategories });
           },
           onError: ({ error }) => {
             errorReporter.captureMessage(error);
@@ -42,6 +49,18 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 }
 ```
 
+## Choose the Right Surface
+
+|Surface|Replays when registered late?|Fires on init / hydration / auto-grants?|Best for|
+|--|--|--|--|
+|`onBannerFetched`|Yes, via `setCallback('onBannerFetched', ...)` after init|Yes|Logging resolved policy, location, and translations|
+|`onConsentSet`|Yes, via `setCallback('onConsentSet', ...)`|Yes|Broad lifecycle hooks, debugging, and integrations that want the latest full state regardless of how it was reached|
+|`onConsentChanged`|No|No|Declarative change-only integrations|
+|`subscribeToConsentChanges()`|No|No|Canonical change-only subscriptions after mount|
+
+> ℹ️ **Info:**
+> Script.onConsentChange is a script-scoped lifecycle hook. It is not the global consent change API for analytics SDKs or other app-wide integrations.
+
 ## Available Callbacks
 
 ### `onBannerFetched`
@@ -58,14 +77,34 @@ onBannerFetched: ({ jurisdiction, location, translations }) => {
 
 ### `onConsentSet`
 
-Called whenever consent preferences are saved - whether by user action (`saveConsents()`), automatic defaults, or on initialization when no jurisdiction is detected.
+Called whenever c15t broadly settles consent state: store initialization, automatic defaults during init, explicit saves, and replay via `setCallback('onConsentSet', ...)`.
 
 ```tsx
 onConsentSet: ({ preferences }) => {
   // preferences: { necessary: true, measurement: true, marketing: false, ... }
-  if (preferences.measurement) {
-    loadAnalytics();
-  }
+  console.log('Latest consent state:', preferences);
+}
+```
+
+### `onConsentChanged`
+
+Called only after an explicit `saveConsents()` or `setConsent()` that actually changes the saved consent state. It never fires on store creation, hydration, automatic grants, unchanged saves, or `setCallback('onConsentChanged', ...)`.
+
+```tsx
+onConsentChanged: ({
+  preferences,
+  previousPreferences,
+  allowedCategories,
+  deniedCategories,
+  previousAllowedCategories,
+  previousDeniedCategories,
+}) => {
+  analytics.syncConsent({
+    allowedCategories,
+    deniedCategories,
+    previousAllowedCategories,
+    previousDeniedCategories,
+  });
 }
 ```
 
@@ -91,7 +130,28 @@ onBeforeConsentRevocationReload: ({ preferences }) => {
 }
 ```
 
-## Dynamic Registration
+## Change-Only Subscriptions
+
+Use `subscribeToConsentChanges()` when you want a stable listener for real preference changes after mount:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@c15t/nextjs';
+
+function ConsentAnalytics() {
+  const { subscribeToConsentChanges } = useConsentManager();
+
+  useEffect(() => {
+    return subscribeToConsentChanges(({ allowedCategories, deniedCategories }) => {
+      analytics.syncConsent({ allowedCategories, deniedCategories });
+    });
+  }, [subscribeToConsentChanges]);
+
+  return null;
+}
+```
+
+## Runtime Callback Registration
 
 Register or update callbacks at runtime using `setCallback()`:
 
@@ -103,11 +163,16 @@ function ConsentAnalytics() {
   const { setCallback } = useConsentManager();
 
   useEffect(() => {
+    setCallback('onBannerFetched', ({ jurisdiction, location }) => {
+      console.log('Resolved init data:', { jurisdiction, location });
+    });
+
     setCallback('onConsentSet', ({ preferences }) => {
-      analytics.track('consent_changed', preferences);
+      console.log('Broad consent lifecycle event:', preferences);
     });
 
     return () => {
+      setCallback('onBannerFetched', undefined);
       setCallback('onConsentSet', undefined);
     };
   }, [setCallback]);
@@ -115,3 +180,5 @@ function ConsentAnalytics() {
   return null;
 }
 ```
+
+`setCallback('onConsentSet', ...)` immediately replays the current consent state. For change-only logic, prefer `subscribeToConsentChanges()` or `onConsentChanged`.

package/docs/components/consent-banner.md

@@ -1,6 +1,6 @@
 ---
 title: ConsentBanner
-description: A pre-built consent banner that appears when user consent is needed. Supports custom layout, button arrangement, and full compound component composition.
+description: A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
 ---
 `ConsentBanner` is a ready-to-use consent banner that appears automatically in **opt-in jurisdictions** (like GDPR) where explicit consent is required before tracking. In opt-out jurisdictions (like CCPA), the banner won't appear — users get an opt-out mechanism instead. It includes reject, accept, and customize buttons with configurable layout.
 
@@ -18,20 +18,6 @@ export function ConsentManager() {
 }
 ```
 
-## Customizing Content
-
-Override the default title, description, and button labels:
-
-```tsx
-<ConsentBanner
-  title="We value your privacy"
-  description="We use cookies to enhance your browsing experience and analyze site traffic."
-  acceptButtonText="Accept all"
-  rejectButtonText="Reject all"
-  customizeButtonText="Manage preferences"
-/>
-```
-
 ## Button Layout
 
 The `layout` prop controls button arrangement. Each item is either a button ID or an array of button IDs (which groups them together):
@@ -86,6 +72,37 @@ Use the provider `theme` prop to control how stock consent actions look:
 
 Policy packs control grouping, ordering, and direction. The theme controls button appearance.
 
+## Styling First
+
+> ℹ️ **Info:**
+> For pure theming, stay inside the pre-built banner. Start with layout props, theme.consentActions, design tokens, and theme.slots before reaching for compound components. See Styling Overview.
+
+The stock banner maps common visual changes to the theme system:
+
+* Card background -> `theme.colors.surface`
+* Footer background -> `theme.colors.surfaceHover`
+* Card, footer, and title tweaks -> `theme.slots.consentBannerCard`, `consentBannerFooter`, and `consentBannerTitle`
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentBannerCard: 'rounded-[28px] shadow-xl',
+        consentBannerFooter: 'border-t border-black/10 px-6',
+        consentBannerTitle: 'tracking-tight',
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
 ### Primary Button
 
 Highlight specific button(s) as the primary action:
@@ -116,9 +133,40 @@ Control which legal links appear in the banner description:
 > ℹ️ **Info:**
 > Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
 
-## Compound Components
+## Customizing Copy
 
-Build fully custom banner layouts using sub-components:
+Prefer provider `i18n` when you want to rename the stock banner content:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    i18n: {
+      locale: 'en',
+      messages: {
+        en: {
+          cookieBanner: {
+            title: 'We value your privacy',
+            description: 'We use cookies to improve the site and measure performance.',
+          },
+          common: {
+            acceptAll: 'Accept all',
+            rejectAll: 'Reject all',
+            customize: 'Manage preferences',
+          },
+        },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Direct text props such as `title`, `description`, and `acceptButtonText` are still supported for one-off overrides, but `i18n` is the preferred path for copy changes.
+
+## Advanced: Compound Components
+
+Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives while keeping policy-driven action grouping and emphasis:
 
 ```tsx
 <ConsentBanner.Root>
@@ -128,13 +176,7 @@ Build fully custom banner layouts using sub-components:
       <ConsentBanner.Title />
       <ConsentBanner.Description />
     </ConsentBanner.Header>
-    <ConsentBanner.Footer>
-      <ConsentBanner.FooterSubGroup>
-        <ConsentBanner.RejectButton />
-        <ConsentBanner.AcceptButton />
-      </ConsentBanner.FooterSubGroup>
-      <ConsentBanner.CustomizeButton />
-    </ConsentBanner.Footer>
+    <ConsentBanner.PolicyActions />
   </ConsentBanner.Card>
 </ConsentBanner.Root>
 ```
@@ -144,6 +186,7 @@ Build fully custom banner layouts using sub-components:
 * `ConsentBanner.Header` — Contains title and description
 * `ConsentBanner.Title` — Heading, defaults to translation `consentBanner.title`
 * `ConsentBanner.Description` — Description text, supports `legalLinks` prop
+* `ConsentBanner.PolicyActions` — Renders policy-aware grouped actions inside the banner footer
 * `ConsentBanner.Footer` — Action buttons container
 * `ConsentBanner.FooterSubGroup` — Groups related buttons together
 * `ConsentBanner.RejectButton` — Rejects all consent
@@ -151,6 +194,86 @@ Build fully custom banner layouts using sub-components:
 * `ConsentBanner.AcceptButton` — Accepts all consent
 * `ConsentBanner.Overlay` — Optional backdrop overlay
 
+For a fixed layout that intentionally ignores policy grouping, render the footer manually:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+      <ConsentBanner.CustomizeButton />
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentBanner.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentBanner.PolicyActions />
+```
+
+`renderAction` is optional. When you want custom mapping but still want the built-in c15t button behavior and copy, return the stock button compounds:
+
+```tsx
+<ConsentBanner.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentBanner.AcceptButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentBanner.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentBanner.CustomizeButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+Use `useTranslations()` only when you are replacing the button markup entirely:
+
+```tsx
+import { ConsentBanner, useTranslations } from '@c15t/react';
+
+export function CustomBannerActions() {
+  const { common } = useTranslations();
+
+  return (
+    <ConsentBanner.PolicyActions
+      renderAction={(action, props) => (
+        <button
+          key={props.key}
+          type="button"
+          className={props.isPrimary ? 'btn-primary' : 'btn-secondary'}
+          style={props.style}
+        >
+          {action === 'accept'
+            ? common.acceptAll
+            : action === 'reject'
+              ? common.rejectAll
+              : common.customize}
+        </button>
+      )}
+    />
+  );
+}
+```
+
+For maximum control, use `useHeadlessConsentUI()` and render `banner.actionGroups` manually.
+
+If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
+
 ## Props
 
 ### ConsentBannerProps
@@ -167,6 +290,7 @@ Build fully custom banner layouts using sub-components:
 |trapFocus|boolean \|undefined|When true, the consent banner will trap focus|true|Optional|
 |disableAnimation|boolean \|undefined|When true, disables the entrance/exit animations|false|Optional|
 |legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|hideBranding|boolean \|undefined|When true, hides the branding tag on the banner.|false|Optional|
 |layout|ConsentBannerLayout \|undefined|Defines the layout of buttons in the footer. Allows reordering and grouping of buttons.|-|Optional|
 |direction|PolicyUiActionDirection \|undefined|Defines how footer button groups flow.|-|Optional|
 |primaryButton|ConsentBannerButton \|undefined|Specifies which button(s) should be highlighted as the primary action.|-|Optional|