@c15t/react 2.0.0-rc.10 → 2.0.0-rc.12

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.10";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.12";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.10";export{e as version};
+let e="2.0.0-rc.12";export{e as version};

package/dist-types/components/consent-dialog/atoms/card.d.ts

@@ -109,4 +109,3 @@ declare const Footer: import("react").ForwardRefExoticComponent<BoxProps & {
     'data-testid'?: string;
 } & import("react").RefAttributes<HTMLDivElement>>;
 export { Card, ConsentCustomizationCard, ConsentDialogCard, ConsentDialogContent, ConsentDialogFooter, ConsentDialogHeader, ConsentDialogHeaderDescription, ConsentDialogHeaderTitle, Content, Footer, Header, HeaderDescription, HeaderTitle, };
-ion, HeaderTitle, };

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.0-rc.10";
+export declare const version = "2.0.0-rc.12";

package/docs/building-headless-components.md

@@ -4,11 +4,11 @@ description: Build policy-aware custom consent components in React using the hea
 ---
 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 layering is:
+Think of customization as a ladder:
 
 * 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
+* `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` when you want custom structure but still want c15t to resolve policy-aware actions
+* `useHeadlessConsentUI()` when you need fully manual action rendering, custom controls, or non-standard flow
 
 > ⚠️ **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.
@@ -26,6 +26,29 @@ The split is intentional: `@c15t/ui` owns pure policy-action resolution, while t
 > ℹ️ **Info:**
 > This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
 
+## Choose the Smallest Layer That Solves the Job
+
+Start with the smallest API surface that still gives you the behavior you need:
+
+* Stay with stock components when you only need theming, spacing, copy, or legal-link changes
+* Use `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions` when you want a custom compound-component layout but still want grouped actions, ordering, and primary emphasis to come from policy
+* Add `renderAction` when the grouping is still correct but you want to remap actions to stock c15t button compounds
+* Reach for `useHeadlessConsentUI()` only when you need custom button elements, need to map `actionGroups` yourself, wire non-button controls, or coordinate the consent UI with a more custom state machine
+
+This order matters because every step down the ladder gives you more control, but also makes it easier for your UI to drift away from the resolved policy if you stop using the provided state.
+
+## Before You Build Headless UI
+
+Do not use headless mode for problems that are still inside the stock component model:
+
+* Use `layout`, `direction`, `primaryButton`, and `legalLinks` before you rebuild banner markup
+* Use `theme.consentActions` before you swap out stock actions
+* Use tokens such as `colors.surface` and `colors.surfaceHover` before raw CSS overrides
+* Use slots such as `consentBannerCard`, `consentBannerFooter`, and `consentDialogCard` before compound components
+* Use `ConsentManagerProvider.options.i18n` before rebuilding UI just to change text
+
+A good rule: if the stock banner or dialog structure is still correct, you probably do not need 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.
@@ -40,9 +63,63 @@ The main win is that your custom UI can stay aligned with policy packs without d
 * UI profile and scroll-lock hints
 * whether the banner or dialog should currently be visible
 
+The hook also gives you the policy-aware action helpers you are expected to call:
+
+* `performBannerAction('accept' | 'reject')`
+* `performDialogAction('accept' | 'reject')`
+* `saveCustomPreferences()` for the dialog `customize` action
+* `openDialog()`, `openBanner()`, and `closeUI()` for surface visibility
+
 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.
+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 which stock compound renders for each action. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
+
+## Policy-Aware Compound Components First
+
+If your goal is "custom layout, same policy behavior", start here before dropping to manual `actionGroups` rendering:
+
+```tsx
+import { ConsentBanner } from '@c15t/react';
+
+export function BannerShell() {
+  return (
+    <ConsentBanner.Root>
+      <ConsentBanner.Card>
+        <ConsentBanner.Header>
+          <ConsentBanner.Title />
+          <ConsentBanner.Description />
+        </ConsentBanner.Header>
+        <ConsentBanner.PolicyActions />
+      </ConsentBanner.Card>
+    </ConsentBanner.Root>
+  );
+}
+```
+
+Use `renderAction` only when you want to remap actions to stock button compounds while keeping the same policy-driven grouping and ordering:
+
+```tsx
+import { ConsentBanner } from '@c15t/react';
+
+export function BannerActionsWithCustomMapping() {
+  return (
+    <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} />;
+        }
+      }}
+    />
+  );
+}
+```
 
 > ℹ️ **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.
@@ -86,9 +163,20 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 import { useHeadlessConsentUI, useTranslations } from '@c15t/react/headless';
 
 export function CustomConsentBanner() {
-  const { banner, openDialog, performAction } = useHeadlessConsentUI();
+  const { banner, openDialog, performBannerAction } = useHeadlessConsentUI();
   const translations = useTranslations();
 
+  function getActionLabel(action: (typeof banner.allowedActions)[number]) {
+    switch (action) {
+      case 'accept':
+        return translations.common.acceptAll;
+      case 'reject':
+        return translations.common.rejectAll;
+      case 'customize':
+        return translations.common.customize;
+    }
+  }
+
   if (!banner.isVisible) return null;
 
   return (
@@ -111,14 +199,10 @@ export function CustomConsentBanner() {
                     openDialog();
                     return;
                   }
-                  void performAction(action, { surface: 'banner' });
+                  void performBannerAction(action);
                 }}
               >
-                {action === 'accept'
-                  ? translations.common.acceptAll
-                  : action === 'reject'
-                    ? translations.common.rejectAll
-                    : translations.common.customize}
+                {getActionLabel(action)}
               </button>
             ))}
           </div>
@@ -149,6 +233,17 @@ export function CustomConsentDialog() {
   } = useConsentManager();
   const translations = useTranslations();
 
+  function getActionLabel(action: (typeof dialog.allowedActions)[number]) {
+    switch (action) {
+      case 'accept':
+        return translations.common.acceptAll;
+      case 'reject':
+        return translations.common.rejectAll;
+      case 'customize':
+        return translations.common.save;
+    }
+  }
+
   if (!dialog.isVisible) return null;
 
   const displayedTypes = consentTypes.filter(
@@ -197,11 +292,7 @@ export function CustomConsentDialog() {
                   void performDialogAction(action);
                 }}
               >
-                {action === 'accept'
-                  ? translations.common.acceptAll
-                  : action === 'reject'
-                    ? translations.common.rejectAll
-                    : translations.common.save}
+                {getActionLabel(action)}
               </button>
             ))}
           </div>
@@ -212,6 +303,17 @@ export function CustomConsentDialog() {
 }
 ```
 
+## What Headless Is Not For
+
+Headless mode is not the recommended path for:
+
+* changing the banner footer background
+* rounding the stock banner card
+* restyling stock banner or dialog buttons
+* changing consent copy
+
+Those should stay in the pre-built stack with tokens, slots, `theme.consentActions`, and provider `i18n`.
+
 ## What a Policy-Aware Headless Component Should Respect
 
 When you build custom banner or dialog components, make sure they use:

package/docs/components/consent-banner.md

@@ -241,36 +241,7 @@ renderAction={(action, props) => {
 />
 ```
 
-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.
+`renderAction` is still meant for stock button compounds. If you want completely custom button elements and click handling, use `useHeadlessConsentUI()` and render `banner.actionGroups` manually instead of `ConsentBanner.PolicyActions`.
 
 If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
 

package/docs/components/consent-widget.md

@@ -117,34 +117,7 @@ renderAction={(action, props) => {
 />
 ```
 
-Use `useTranslations()` only when you are replacing the button markup entirely:
-
-```tsx
-import { ConsentWidget, useTranslations } from '@c15t/react';
-
-export function CustomWidgetActions() {
-  const { common } = useTranslations();
-
-  return (
-    <ConsentWidget.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.save}
-        </button>
-      )}
-    />
-  );
-}
-```
+`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`.
 

package/docs/hooks/use-consent-manager/overview.md

@@ -360,7 +360,7 @@ function LoginForm() {
 ```
 
 > ℹ️ **Info:**
-> identifyUser sends the user data to the c15t backend. It only works in 'c15t' mode — in 'offline' mode the call is a no-op.
+> identifyUser sends the user data to the c15t backend. It works in hosted mode, including the legacy alias mode: 'c15t'. In mode: 'offline', the call is a no-op.
 
 ## Key Types
 

package/docs/iab/consent-banner.md

@@ -19,6 +19,7 @@ Use this component instead of `ConsentBanner` when you need IAB TCF compliance f
 
 ```tsx
 import { type ReactNode } from 'react';
+import { iab } from '@c15t/iab';
 import { ConsentManagerProvider } from '@c15t/react';
 import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
 
@@ -28,11 +29,12 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: 'https://your-instance.c15t.dev',
-        iab: {
-          enabled: true,
-          cmpId: 123,
+        iab: iab({
           vendors: [1, 2, 10, 25],
-        },
+          // cmpId is automatically provided by the backend when using consent.io.
+          // Only set this if you have your own CMP registration.
+          // cmpId: 123,
+        }),
       }}
     >
       <IABConsentBanner />

package/docs/iab/consent-dialog.md

@@ -13,6 +13,7 @@ Pair it with `IABConsentBanner` inside the provider:
 
 ```tsx
 import { type ReactNode } from 'react';
+import { iab } from '@c15t/iab';
 import { ConsentManagerProvider } from '@c15t/react';
 import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
 
@@ -22,11 +23,12 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: 'https://your-instance.c15t.dev',
-        iab: {
-          enabled: true,
-          cmpId: 123,
+        iab: iab({
           vendors: [1, 2, 10, 25],
-        },
+          // cmpId is automatically provided by the backend when using consent.io.
+          // Only set this if you have your own CMP registration.
+          // cmpId: 123,
+        }),
       }}
     >
       <IABConsentBanner />

package/docs/iab/overview.md

@@ -45,6 +45,7 @@ If you use the prebuilt styled IAB UI, import the IAB stylesheet alongside the b
 
 ```tsx
 import { type ReactNode } from 'react';
+import { iab } from '@c15t/iab';
 import { ConsentManagerProvider } from '@c15t/react';
 import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
 
@@ -54,13 +55,12 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: 'https://your-instance.c15t.dev',
-        iab: {
-          enabled: true,
+        iab: iab({
           vendors: [1, 2, 10, 25],  // IAB vendor IDs you work with
           // cmpId is automatically provided by the backend (inth.com).
           // Only set this if you have your own CMP registration with IAB Europe.
           // cmpId: 123,
-        },
+        }),
       }}
     >
       <IABConsentBanner />
@@ -73,14 +73,13 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
 
 ## IAB Configuration Options
 
-The `iab` option on the provider accepts:
+Configure IAB mode with `iab({ ... })` from `@c15t/iab`. The factory enables the addon and injects the runtime module automatically. The user-facing options are:
 
 |Option|Type|Description|
 |--|--|--|
-|`enabled`|`boolean`|Enable IAB TCF mode|
 |`cmpId`|`number`|CMP ID registered with IAB Europe. Automatically provided by the backend when using inth.com. Only set this if you have your own CMP registration.|
 |`vendors`|`number[]`|IAB vendor IDs that your site works with|
-|`nonIABVendors`|`NonIABVendor[]`|Custom vendors not in the IAB registry|
+|`customVendors`|`NonIABVendor[]`|Custom vendors not in the IAB registry|
 
 ## Key Concepts
 
@@ -122,4 +121,6 @@ Each vendor in the GVL declares which purposes it uses, whether via consent or l
 |--|--|
 |[IABConsentBanner](/docs/frameworks/react/iab/consent-banner)|TCF-compliant banner with partner disclosure|
 |[IABConsentDialog](/docs/frameworks/react/iab/consent-dialog)|Tabbed preference center for purposes and vendors|
-|[useGVLData](/docs/frameworks/react/iab/use-gvl-data)|Hook for building custom IAB UI|
+
+> ℹ️ **Info:**
+> For lower-level custom IAB flows, use useHeadlessIABConsentUI() from @c15t/react/iab. useGVLData() is currently internal and is not part of the public package surface.

package/docs/iab/use-gvl-data.md

@@ -1,208 +1,20 @@
 ---
-title: useGVLData
-description: Hook to access processed Global Vendor List (GVL) data for building custom IAB TCF UI components.
+title: useGVLData (Internal)
+description: Status note for the internal GVL hook used by the built-in IAB dialog.
 ---
 > ❌ **Error:**
 > c15t is not yet IAB certified. The IAB TCF components are under active development and should not be used in production. APIs and behavior may change before certification is achieved.
 
-`useGVLData()` processes the raw IAB Global Vendor List (GVL) into a UI-friendly format. It handles purpose grouping into stacks, vendor mapping, special purpose/feature extraction, and loading state.
+`useGVLData()` currently powers the built-in `IABConsentDialog`, but it is **not part of the public package surface**.
 
-Use this hook when building a custom IAB TCF UI instead of the pre-built `IABConsentDialog`.
+Older docs showed it as a public hook. That is no longer accurate.
 
-```tsx
-import { useGVLData } from '@c15t/react/hooks';
+If you need supported customization points today:
 
-function CustomIABPreferences() {
-  const { purposes, stacks, standalonePurposes, totalVendors, isLoading } = useGVLData();
-
-  if (isLoading) return <p>Loading vendor data...</p>;
-
-  return (
-    <div>
-      <p>{totalVendors} partners</p>
-      {standalonePurposes.map((purpose) => (
-        <div key={purpose.id}>
-          <h3>{purpose.name}</h3>
-          <p>{purpose.description}</p>
-          <p>{purpose.vendors.length} vendors</p>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
+* Use `IABConsentBanner` and `IABConsentDialog` from `@c15t/react/iab` for the supported prebuilt UI
+* Use `useHeadlessIABConsentUI()` from `@c15t/react/iab` when you need lower-level control over banner/dialog state and actions
 
 > ℹ️ **Info:**
-> Must be used within a ConsentManagerProvider with IAB mode enabled. Returns empty data if IAB is not configured.
-
-## Return Value
-
-The hook returns a `GVLData` object:
-
-### GVLData
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|purposes|ProcessedPurpose|-|-|✅ Required|
-|specialPurposes|ProcessedPurpose|-|-|✅ Required|
-|specialFeatures|ProcessedSpecialFeature|-|-|✅ Required|
-|features|ProcessedFeature|-|-|✅ Required|
-|stacks|ProcessedStack|-|-|✅ Required|
-|standalonePurposes|ProcessedPurpose|-|-|✅ Required|
-|totalVendors|number|-|-|✅ Required|
-|isLoading|boolean|-|-|✅ Required|
-
-#### `purposes` ProcessedPurpose
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-|isSpecialPurpose|boolean \|undefined|-|-|Optional|
-
-#### `specialPurposes` ProcessedPurpose
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-|isSpecialPurpose|boolean \|undefined|-|-|Optional|
-
-#### `specialFeatures` ProcessedSpecialFeature
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-
-#### `features` ProcessedFeature
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-
-#### `stacks` ProcessedStack
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|purposes|ProcessedPurpose|-|-|✅ Required|
-
-#### `standalonePurposes` ProcessedPurpose
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-|isSpecialPurpose|boolean \|undefined|-|-|Optional|
-
-## Types
-
-### ProcessedPurpose
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
-|isSpecialPurpose|boolean \|undefined|-|-|Optional|
-
-#### `vendors` ProcessedVendor
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|VendorId|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|policyUrl|string|-|-|✅ Required|
-|usesNonCookieAccess|boolean|-|-|✅ Required|
-|deviceStorageDisclosureUrl|string \|null|-|-|✅ Required|
-|usesCookies|boolean|-|-|✅ Required|
-|cookieMaxAgeSeconds|number \|null|-|-|✅ Required|
-|cookieRefresh|boolean \|undefined|-|-|Optional|
-|specialPurposes|number\[]|-|-|✅ Required|
-|specialFeatures|number\[]|-|-|✅ Required|
-|features|number\[]|-|-|✅ Required|
-|purposes|number\[]|-|-|✅ Required|
-|legIntPurposes|number\[]|-|-|✅ Required|
-|legitimateInterestUrl|string \|null \|undefined|-|-|Optional|
-|isCustom|boolean \|undefined|-|-|Optional|
-|usesLegitimateInterest|boolean \|undefined|-|-|Optional|
-|dataRetention|Object \|undefined|-|-|Optional|
-|dataDeclaration|number\[] \|undefined|-|-|Optional|
-
-### ProcessedVendor
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|VendorId|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|policyUrl|string|-|-|✅ Required|
-|usesNonCookieAccess|boolean|-|-|✅ Required|
-|deviceStorageDisclosureUrl|string \|null|-|-|✅ Required|
-|usesCookies|boolean|-|-|✅ Required|
-|cookieMaxAgeSeconds|number \|null|-|-|✅ Required|
-|cookieRefresh|boolean \|undefined|-|-|Optional|
-|specialPurposes|number\[]|-|-|✅ Required|
-|specialFeatures|number\[]|-|-|✅ Required|
-|features|number\[]|-|-|✅ Required|
-|purposes|number\[]|-|-|✅ Required|
-|legIntPurposes|number\[]|-|-|✅ Required|
-|legitimateInterestUrl|string \|null \|undefined|-|-|Optional|
-|isCustom|boolean \|undefined|-|-|Optional|
-|usesLegitimateInterest|boolean \|undefined|-|-|Optional|
-|dataRetention|Object \|undefined|-|-|Optional|
-|dataDeclaration|number\[] \|undefined|-|-|Optional|
-
-#### `dataRetention`
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|purposes|Record\<number, number> \|undefined|-|-|Optional|
-|specialPurposes|Record\<number, number> \|undefined|-|-|Optional|
-|stdRetention|number \|undefined|-|-|Optional|
-
-### ProcessedStack
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|purposes|ProcessedPurpose|-|-|✅ Required|
-
-### ProcessedSpecialFeature
+> Until useGVLData() is exported as public API, avoid importing it from deep internal paths. Those paths are not covered by semver guarantees and can change without notice.
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
+When a public GVL-focused hook becomes part of the supported API, this page should document that public surface instead of the internal dialog hook.

package/docs/optimization.md

@@ -1,10 +1,25 @@
 ---
 title: Optimization
 description: Improve c15t startup performance in React with prefetching, proxy rewrites, and rendering tradeoffs.
-lastModified: 2026-03-17
+lastModified: 2026-04-14
 ---
 Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
 
+## Start Here
+
+Apply the optimizations in this order:
+
+|Situation|Use|Why|Tradeoff|
+|--|--|--|--|
+|Any production app using hosted mode|Same-origin `/api/c15t` proxy|Lowers browser startup overhead and keeps the backend origin out of client config|Requires framework or platform proxy setup|
+|Banner speed matters on cold loads|`buildPrefetchScript()`|Starts `/init` before your app hydrates|Still a browser-side fetch, not SSR|
+|Your app navigates client-side|Keep the provider mounted at the app root|Avoids remounting and re-running init work|Requires provider placement discipline|
+|You cannot proxy and must stay cross-origin|`<link rel="preconnect">`|Starts DNS/TLS work earlier|Smaller gain than same-origin proxying|
+|You are using Next.js and want SSR or static-route-specific guidance|Next.js optimization docs|Covers `C15tPrefetch`, `fetchInitialData()`, and rendering tradeoffs|Next-specific|
+
+> ℹ️ **Info:**
+> Treat same-origin proxying as the baseline optimization. The others are situational layers you add when startup timing or route behavior justifies them.
+
 ## 1) Prefer Same-Origin Proxy
 
 Proxy c15t requests through your app server so the browser calls your own origin instead of a third-party domain.
@@ -23,6 +38,8 @@ Why this helps:
 * Ad blockers are less likely to block your init endpoint
 * You can change backend infrastructure without touching client code
 
+If you can only do one optimization, do this one first.
+
 ## 2) Prefetch Init Data Early
 
 Use `buildPrefetchScript()` from the `c15t` core package to start the `/init` request before your app hydrates. Inject the script as early as possible in your HTML `<head>`.
@@ -35,6 +52,12 @@ In production benchmarks with a same-origin rewrite, prefetching strategies show
 |Browser prefetch|\~1.3x faster|\~2.6x earlier|\~1.25x faster|
 |Server prefetch|\~2x faster|before page loads|\~1.9x faster|
 
+Use this when:
+
+* The app is client-rendered
+* You want a faster first banner without introducing SSR complexity
+* You control the HTML template or document `<head>`
+
 ### Inline Script Prefetch
 
 ```tsx
@@ -88,6 +111,8 @@ Why this helps:
 * Prevents extra callback churn from remount cycles
 * Keeps banner/dialog state stable between route transitions
 
+Mount `ConsentManagerProvider` as high in the tree as possible so route transitions do not recreate it.
+
 ## Animation Performance
 
 The default motion tokens are tuned for speed-first product UI:
@@ -104,6 +129,8 @@ To customize motion durations and easing, see [Styling](/docs/frameworks/react/s
 
 ## Reduce Network Overhead
 
+If your browser must call a cross-origin backend URL directly, add `preconnect` so the browser can warm up the connection earlier. This is a fallback optimization when same-origin proxying is not possible.
+
 If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
 
 ```tsx
@@ -111,3 +138,10 @@ If you must use a cross-origin backend URL, add preconnect so the browser starts
   <link rel="preconnect" href="https://your-instance.c15t.dev" crossOrigin="" />
 </head>
 ```
+
+## Next.js-Specific SSR And Static Routes
+
+This page is intentionally React-generic. If you are using Next.js and need SSR or static-route-specific guidance:
+
+* See [Next.js Optimization](/docs/frameworks/next/optimization) for the static-vs-dynamic decision guide
+* See [Next.js Server-Side Data Fetching](/docs/frameworks/next/server-side) for `fetchInitialData()`

package/docs/quickstart.md

@@ -17,10 +17,10 @@ availableIn:
 
 |Package manager|Command|
 |:--|:--|
-|npm|`npx @c15t/cli@rc`|
-|pnpm|`pnpm dlx @c15t/cli@rc`|
-|yarn|`yarn dlx @c15t/cli@rc`|
-|bun|`bunx @c15t/cli@rc`|
+|npm|`npx @c15t/cli`|
+|pnpm|`pnpm dlx @c15t/cli`|
+|yarn|`yarn dlx @c15t/cli`|
+|bun|`bunx @c15t/cli`|
 
 ## Manual Installation
 
@@ -107,6 +107,9 @@ availableIn:
 
    A consent banner appears at the bottom of the pageClicking "Customize" opens a dialog with toggles for each consent categoryAfter accepting or rejecting, the banner dismisses and your choice persists across page reloads
 
+> ℹ️ **Info:**
+> Want to improve startup performance? See Optimization for the decision guide, prefetch setup, and network tuning.
+
 ## Optional: Add DevTools
 
 Install DevTools only if you want a runtime inspector while building and debugging:
@@ -142,10 +145,10 @@ Install c15t agent skills to let AI agents help with styling, i18n, scripts & ot
 
 |Package manager|Command|
 |:--|:--|
-|npm|`npx @c15t/cli@rc skills`|
-|pnpm|`pnpm dlx @c15t/cli@rc skills`|
-|yarn|`yarn dlx @c15t/cli@rc skills`|
-|bun|`bunx @c15t/cli@rc skills`|
+|npm|`npx @c15t/cli skills`|
+|pnpm|`pnpm dlx @c15t/cli skills`|
+|yarn|`yarn dlx @c15t/cli skills`|
+|bun|`bunx @c15t/cli skills`|
 
 See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/react",
-	"version": "2.0.0-rc.10",
+	"version": "2.0.0-rc.12",
 	"description": "Developer-first CMP for React: cookie banner, consent manager, preferences centre. GDPR ready with minimal setup and rich customization",
 	"keywords": [
 		"react",
@@ -164,7 +164,7 @@
 		"not op_mini all"
 	],
 	"dependencies": {
-		"@c15t/ui": "2.0.0-rc.10",
+		"@c15t/ui": "2.0.0-rc.11",
 		"c15t": "2.0.0-rc.10"
 	},
 	"devDependencies": {