@c15t/nextjs 2.0.0-rc.9 → 2.0.2

package/docs/iab/consent-dialog.md

@@ -2,8 +2,8 @@
 title: IABConsentDialog
 description: An IAB TCF 2.3 compliant preference center with tabbed purpose and vendor management.
 ---
-> ❌ **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.
+> ℹ️ **Info:**
+> c15t's IAB TCF support can be used in production. Use Inth for a hosted, IAB TCF-certified CMP setup with a managed CMP ID, or register your own CMP with IAB Europe and configure your own CMP ID.
 
 `IABConsentDialog` is an IAB TCF 2.3 compliant consent dialog that provides a tabbed interface for managing purpose consent and vendor preferences. It includes purpose grouping via stacks, individual purpose/vendor toggles, special purpose and feature disclosures, and legitimate interest handling.
 
@@ -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/nextjs';
 import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
 
@@ -22,11 +23,12 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        iab: {
-          enabled: true,
-          cmpId: 123,
+        iab: iab({
           vendors: [1, 2, 10, 25],
-        },
+          // cmpId is automatically provided by the backend when using Inth.
+          // Only set this if you have your own CMP registration.
+          // cmpId: 123,
+        }),
       }}
     >
       <IABConsentBanner />

package/docs/iab/overview.md

@@ -15,12 +15,12 @@ When your site participates in the IAB ecosystem (ad exchanges, SSPs, DSPs, DMPs
 
 ## CMP Registration
 
-[consent.io](https://consent.io) is pending validation as an IAB Europe-registered CMP for c15t. Once approved, when you use consent.io as your backend, the correct CMP ID will be automatically provided to your client via the `/init` endpoint — no client-side configuration needed.
+[Inth](https://inth.com), c15t's hosted platform, is IAB TCF certified. When you use Inth as your backend with c15t's prebuilt IAB UI, the correct CMP ID is automatically provided to your client via the `/init` endpoint — no client-side configuration needed.
 
-If you self-host the c15t backend and have your own CMP registration with IAB Europe, you can configure your CMP ID on the backend via `advanced.iab.cmpId` or on the client via the `iab.cmpId` option. A valid (non-zero) CMP ID is required for IAB TCF compliance.
+If you self-host the c15t backend or want to operate as your own CMP, register your own CMP with IAB Europe and configure your CMP ID on the backend via `advanced.iab.cmpId` or on the client via the `iab.cmpId` option. Registering your own CMP may also involve IAB Europe fees, so check IAB Europe's current CMP registration terms and pricing before choosing this route. A valid (non-zero) CMP ID is required for IAB TCF compliance.
 
 > ℹ️ **Info:**
-> If you heavily customize or build your own IAB banner or dialog (rather than using the default IABConsentBanner and IABConsentDialog components), you cannot use consent.io's CMP ID. You must register your own CMP with IAB Europe and use your own CMP ID.
+> If you heavily customize or build your own IAB banner or dialog instead of using the default IABConsentBanner and IABConsentDialog components, you cannot use Inth's CMP ID. You must register your own CMP with IAB Europe and use your own CMP ID.
 
 ## How c15t Implements TCF
 
@@ -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/nextjs';
 import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
 
@@ -54,13 +55,12 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        iab: {
-          enabled: true,
+        iab: iab({
           vendors: [1, 2, 10, 25],  // IAB vendor IDs you work with
-          // cmpId is automatically provided by the backend (consent.io).
+          // 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 consent.io. Only set this if you have your own CMP registration.|
+|`cmpId`|`number`|CMP ID registered with IAB Europe. Automatically provided by the backend when using Inth with the prebuilt IAB UI. 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/next/iab/consent-banner)|TCF-compliant banner with partner disclosure|
 |[IABConsentDialog](/docs/frameworks/next/iab/consent-dialog)|Tabbed preference center for purposes and vendors|
-|[useGVLData](/docs/frameworks/next/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.
-
-Use this hook when building a custom IAB TCF UI instead of the pre-built `IABConsentDialog`.
-
-```tsx
-import { useGVLData } from '@c15t/react/hooks';
-
-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>
-  );
-}
-```
-
 > ℹ️ **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
+> c15t's IAB TCF support can be used in production through Inth or with your own registered CMP ID. useGVLData() is different: it remains an internal hook and is not part of the supported public API.
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
+`useGVLData()` currently powers the built-in `IABConsentDialog`, but it is **not part of the public package surface**.
 
-#### `features` ProcessedFeature
+Older docs showed it as a public hook. That is no longer accurate.
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|number|-|-|✅ Required|
-|name|string|-|-|✅ Required|
-|description|string|-|-|✅ Required|
-|descriptionLegal|string \|undefined|-|-|Optional|
-|illustrations|string\[]|-|-|✅ Required|
-|vendors|ProcessedVendor|-|-|✅ Required|
+If you need supported customization points today:
 
-#### `stacks` ProcessedStack
+* 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
 
-|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
+> ℹ️ **Info:**
+> 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/internationalization.md

@@ -10,7 +10,7 @@ There are two ways c15t can load translations: client-side or server-side.
 
 |Server-side|Client-side|
 |--|--|
-|The best way to reduce bundle size and improve performance. We can detect the user's language based on the browser's language settings, allowing for the most accurate translations. By default, when using a [consent.io](https://consent.io) hosted instance, [these languages](https://github.com/c15t/c15t/tree/main/packages/translations/src/translations) are supported.|Bundled with the application allowing for multiple languages to be supported without the need for a backend. The more translations you have, the larger the bundle size will be, which may impact the performance of your application.|
+|The best way to reduce bundle size and improve performance. We can detect the user's language based on the browser's language settings, allowing for the most accurate translations. By default, when using a [inth.com](https://inth.com) hosted instance, [these languages](https://github.com/c15t/c15t/tree/main/packages/translations/src/translations) are supported.|Bundled with the application allowing for multiple languages to be supported without the need for a backend. The more translations you have, the larger the bundle size will be, which may impact the performance of your application.|
 
 ## Basic Configuration
 

package/docs/optimization.md

@@ -1,10 +1,35 @@
 ---
 title: Optimization
-description: Improve c15t startup performance in Next.js with rewrites, static prefetching, and rendering tradeoffs.
-lastModified: 2026-04-09
+description: Improve c15t startup performance in Next.js with same-origin rewrites, static prefetching, and dynamic-route SSR.
+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|
+|--|--|--|
+|Any production Next.js app|Same-origin `/api/c15t` rewrite|Lowers browser startup overhead and keeps the backend origin out of client config|
+|Static route, but banner speed matters|`C15tPrefetch`|Starts `/init` before hydration without making the route dynamic|
+|Dynamic route, or you want the fastest first banner|`fetchInitialData()`|Starts `/init` on the server and streams the result into the provider|
+|You want the simplest setup|Client-only init|No extra moving parts, but the banner appears later on cold loads|
+
+> ℹ️ **Info:**
+> C15tPrefetch is the only static-route prefetch step you need in @c15t/nextjs. Matching prefetched data is consumed automatically during first initialization.
+>
+> ℹ️ **Info:**
+> Prefetched or SSR data is reused only when the request context still matches at runtime. That includes the backend URL, credentials, overrides, and the browser's ambient GPC signal.
+
+In production benchmarks with a same-origin rewrite, prefetching strategies show measurable improvement over client-only init:
+
+|Strategy|Scripts loaded|Data request starts|Banner visible|
+|--|--|--|--|
+|Client-only (no prefetch)|baseline|baseline|baseline|
+|Browser prefetch|\~1.3x faster|\~2.6x earlier|\~1.25x faster|
+|Server prefetch|\~2x faster|before page loads|\~1.9x faster|
+
 ## 1) Prefer Same-Origin Rewrites
 
 Proxy c15t requests through your Next.js app so the browser calls your own origin instead of a third-party domain.
@@ -39,30 +64,24 @@ Why this helps:
 * You can change backend infrastructure without touching client code
 
 > ℹ️ **Info:**
-> Set NEXT\_PUBLIC\_C15T\_URL in .env to your backend URL, for example https\://your-instance.c15t.dev.
+> Set NEXT\_PUBLIC\_C15T\_URL in .env to your backend URL, for example https\://your-project.inth.app.
 >
 > ℹ️ **Info:**
-> Use rewrites for browser-side calls (ConsentManagerProvider, C15tPrefetch). For server-side fetchInitialData(), prefer a direct backend URL (for example https\://your-instance.c15t.dev) to avoid an extra server proxy hop.
+> Use rewrites for browser-side calls (ConsentManagerProvider, C15tPrefetch). For server-side fetchInitialData(), prefer a direct backend URL (for example https\://your-project.inth.app) to avoid an extra server proxy hop.
 
-## 2) Pick The Right Data Strategy
+## 2) Choose A Startup Strategy
 
-|Goal|Strategy|Tradeoff|
-|--|--|--|
-|Keep routes fully static|`C15tPrefetch`|Still client-side fetch, but starts earlier|
-|Fastest first banner on dynamic routes|`fetchInitialData()` in a Server Component (do not await)|Route becomes dynamic because of `next/headers`|
-|Simplest setup|Client-only init (no prefetch)|Banner appears later on slow networks|
+Start with a same-origin rewrite and the default client-side provider. Add one of the preloading strategies below only when the route behavior or performance target calls for it.
 
-In production benchmarks with a same-origin rewrite, prefetching strategies show measurable improvement over client-only init:
+### Client-Only Init
 
-|Strategy|Scripts loaded|Data request starts|Banner visible|
-|--|--|--|--|
-|Client-only (no prefetch)|baseline|baseline|baseline|
-|Browser prefetch|\~1.3x faster|\~2.6x earlier|\~1.25x faster|
-|Server prefetch|\~2x faster|before page loads|\~1.9x faster|
+Keep the default provider setup when you want the least complexity. This works on both static and dynamic routes, but the banner only appears after the client runtime starts and the initial `/init` request completes.
 
 ### Dynamic Routes: Fetch On The Server And Stream
 
-Use `fetchInitialData()` in a Server Component when you want the fastest first banner and can accept the route becoming dynamic.
+Use `fetchInitialData()` when the route is already dynamic, or when you are willing to make it dynamic in exchange for the fastest first banner.
+
+Because it depends on `next/headers`, this opts the route into dynamic rendering.
 
 ```tsx title="app/layout.tsx"
 import { fetchInitialData } from '@c15t/nextjs';
@@ -106,7 +125,7 @@ export default function ConsentManager({
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        store: { ssrData },
+        ssrData,
       }}
     >
       <ConsentBanner />
@@ -121,11 +140,11 @@ export default function ConsentManager({
 > Do not await fetchInitialData(). Pass the unresolved Promise to the provider so Next.js can stream the route while /init runs in parallel.
 >
 > ℹ️ **Info:**
-> For fetchInitialData(), prefer a direct backend URL such as https\://your-instance.c15t.dev instead of a rewrite to avoid an extra server-side proxy hop. See Server-Side Data Fetching for the full flow.
+> For fetchInitialData(), prefer a direct backend URL such as https\://your-project.inth.app instead of a rewrite to avoid an extra server-side proxy hop. See Server-Side Data Fetching for the full flow.
 
 ### Static Routes: Start Fetch Early In The Browser
 
-Use `C15tPrefetch` in your layout. Matching prefetched data is consumed automatically by the runtime during first store initialization.
+Use `C15tPrefetch` when the route needs to stay static but you still want the `/init` request to start before hydration. Matching prefetched data is consumed automatically by the runtime during first store initialization.
 
 ```tsx title="app/layout.tsx"
 import { C15tPrefetch } from '@c15t/nextjs';
@@ -175,10 +194,10 @@ export default function ConsentManagerClient({ children }: { children: React.Rea
 ```
 
 > ℹ️ **Info:**
-> C15tPrefetch uses Next.js beforeInteractive script loading, so the /init request can start before hydration. In App Router streaming output, this may appear as Next.js script bootstrap data (for example self.\_\_next\_s.push(...)) instead of a literal \<head>\<script> tag.
+> C15tPrefetch uses Next.js beforeInteractive script loading, so the /init request can start before hydration.
 >
 > ℹ️ **Info:**
-> If overrides.gpc conflicts with the browser's ambient GPC signal, the prefetched entry is not reused and c15t falls back to a normal client /init.
+> If the request context changes between prefetch time and runtime, c15t falls back to a normal client /init. A common example is overrides.gpc conflicting with the browser's ambient GPC signal.
 
 ## Keep The Provider Mounted Across Navigation
 
@@ -210,6 +229,6 @@ If you must use a cross-origin backend URL, add preconnect so the browser starts
 
 ```tsx title="app/layout.tsx"
 <head>
-  <link rel="preconnect" href="https://your-instance.c15t.dev" crossOrigin="" />
+  <link rel="preconnect" href="https://your-project.inth.app" crossOrigin="" />
 </head>
 ```

package/docs/policy-packs.md

@@ -13,7 +13,7 @@ When a backend isn't available — local development, static previews, Storybook
 
 ## Hosted Mode (Recommended)
 
-When using consent.io or a self-hosted backend, the provider connects automatically. No policy configuration is needed on the frontend:
+When using inth.com or a self-hosted backend, the provider connects automatically. No policy configuration is needed on the frontend:
 
 ```tsx
 <ConsentManagerProvider

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
 
@@ -39,7 +39,7 @@ availableIn:
    @import "@c15t/nextjs/styles.css";
    ```
 
-   Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.
+   Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.With Tailwind v4, keep c15t at the end of the top-level @import block so Fumadocs, tw-animate-css, and other preset imports do not override c15t theme tokens.
 
    > ℹ️ Info:
    >
@@ -151,10 +151,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/docs/server-side.md

@@ -1,8 +1,10 @@
 ---
 title: Server-Side Data Fetching
-description: Pre-fetch consent data in Server Components with fetchInitialData — eliminate the loading flash and enable streaming.
+description: Pre-fetch consent data in Server Components with fetchInitialData for dynamic Next.js routes.
 ---
-The `@c15t/nextjs` package provides `fetchInitialData`, a server-side function that fetches consent data before rendering. This enables SSR hydration — consent state is available immediately on page load without a client-side fetch, eliminating the consent banner flash.
+The `@c15t/nextjs` package provides `fetchInitialData`, a server-side function that fetches consent data before rendering. Use it when the route is already dynamic, or when you want the fastest first banner and are okay opting the route into dynamic rendering. If you need to keep a route fully static, use `C15tPrefetch` instead.
+
+Because `fetchInitialData()` resolves request headers from `next/headers`, using it opts the route into dynamic rendering.
 
 > ℹ️ **Info:**
 > SSR hydration is part of the initialization flow. When SSR data is available, the client skips the API fetch entirely.
@@ -20,7 +22,7 @@ import { fetchInitialData } from '@c15t/nextjs';
 
 // In a Server Component — do NOT await
 const ssrData = fetchInitialData({
-  backendURL: '/api/c15t',
+  backendURL: 'https://your-instance.c15t.dev',
   debug: process.env.NODE_ENV === 'development',
 });
 ```
@@ -29,6 +31,9 @@ const ssrData = fetchInitialData({
 > Do not await fetchInitialData() in Server Components. Pass the Promise directly to your client component so Next.js can stream the page while the consent data loads in parallel.
 >
 > ℹ️ **Info:**
+> For fetchInitialData(), prefer a direct backend URL such as https\://your-instance.c15t.dev. For browser-side calls from the provider, C15tPrefetch, and other client runtime work, prefer a same-origin /api/c15t rewrite. See Optimization for the full decision guide.
+>
+> ℹ️ **Info:**
 > Need fully static routes? Use C15tPrefetch in your layout. Matching prefetched data is consumed automatically by the runtime instead of using fetchInitialData(). See Optimization.
 
 ### How Streaming Works
@@ -94,7 +99,7 @@ export default function ConsentManager({
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        store: { ssrData },
+        ssrData,
       }}
     >
       <ConsentBanner />
@@ -111,7 +116,7 @@ import ConsentManager from '@/components/consent-manager';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   const ssrData = fetchInitialData({
-    backendURL: '/api/c15t',
+    backendURL: 'https://your-instance.c15t.dev',
   });
 
   return (

package/docs/styling/color-scheme.md

@@ -65,7 +65,7 @@ function ThemeToggle() {
 
 ## How Dark Mode Works
 
-When dark mode is active, c15t applies the `dark` token values as CSS variable overrides. Only tokens specified in `dark` are overridden - unset tokens fall back to the `colors` values.
+When dark mode is active, c15t applies the `dark` token values as CSS variable overrides. Only tokens specified in `dark` are overridden - unset tokens fall back to the `colors` values. This also applies to `textOnPrimary`: if you omit it, c15t derives a readable foreground from the active `primary` color in that scheme.
 
 ```tsx
 const theme = {

package/docs/styling/css-variables.md

@@ -18,7 +18,7 @@ Every theme token is converted to a `--c15t-*` CSS custom property at runtime. Y
 |--c15t-border-hover|string \|undefined|\`colors.borderHover\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
 |--c15t-text|string \|undefined|\`colors.text\` (default: \`hsl(0, 0%, 10%)\`)|-|Optional|
 |--c15t-text-muted|string \|undefined|\`colors.textMuted\` (default: \`hsl(0, 0%, 40%)\`)|-|Optional|
-|--c15t-text-on-primary|string \|undefined|\`colors.textOnPrimary\` (default: \`hsl(0, 0%, 100%)\`)|-|Optional|
+|--c15t-text-on-primary|string \|undefined|\`colors.textOnPrimary\` (auto-derived from \`colors.primary\` when omitted)|-|Optional|
 |--c15t-overlay|string \|undefined|\`colors.overlay\` (default: \`hsla(0, 0%, 0%, 0.5)\`)|-|Optional|
 |--c15t-switch-track|string \|undefined|\`colors.switchTrack\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
 |--c15t-switch-track-active|string \|undefined|\`colors.switchTrackActive\` (default: \`hsl(228, 100%, 60%)\`)|-|Optional|

package/docs/styling/overview.md

@@ -99,6 +99,7 @@ Use tokens first when the change is semantic:
 * Banner card background -> `theme.colors.surface`
 * Banner footer background -> `theme.colors.surfaceHover`
 * Shared copy color -> `theme.colors.text` and `theme.colors.textMuted`
+* Primary-filled surfaces such as stock branding tags and filled actions -> `theme.colors.primary` with `theme.colors.textOnPrimary` as the matching foreground override
 
 ```tsx
 options={{
@@ -111,6 +112,8 @@ options={{
 }}
 ```
 
+If you set `theme.colors.primary` but omit `theme.colors.textOnPrimary`, c15t derives a readable foreground automatically. Add `textOnPrimary` only when you need to force a specific branded foreground color.
+
 ### 3. Component slots
 
 Target specific component parts via the `slots` object:
@@ -314,7 +317,7 @@ Color palette for light mode.
 |borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
 |text|string \|undefined|Primary text color for headings and body.|-|Optional|
 |textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
-|textOnPrimary|string \|undefined|Text color for content on primary background.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background. Auto-derived from \`primary\` when omitted.|-|Optional|
 |overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
 |switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
 |switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
@@ -334,7 +337,7 @@ Dark mode color overrides.
 |borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
 |text|string \|undefined|Primary text color for headings and body.|-|Optional|
 |textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
-|textOnPrimary|string \|undefined|Text color for content on primary background.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background. Auto-derived from \`primary\` when omitted.|-|Optional|
 |overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
 |switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
 |switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
@@ -420,6 +423,7 @@ Component-specific style overrides.
 |consentBannerDescription|SlotStyle \|undefined|Banner description text element.|-|Optional|
 |consentBannerFooter|SlotStyle \|undefined|Footer container for banner action buttons.|-|Optional|
 |consentBannerFooterSubGroup|SlotStyle \|undefined|Nested button group inside the banner footer.|-|Optional|
+|consentBannerTag|SlotStyle \|undefined|Branding tag rendered above the consent banner card.|-|Optional|
 |consentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the banner when enabled.|-|Optional|
 |consentDialog|SlotStyle \|undefined|Root wrapper for the consent dialog modal.|-|Optional|
 |consentDialogCard|SlotStyle \|undefined|Main dialog card container.|-|Optional|
@@ -427,22 +431,25 @@ Component-specific style overrides.
 |consentDialogTitle|SlotStyle \|undefined|Dialog title text element.|-|Optional|
 |consentDialogDescription|SlotStyle \|undefined|Dialog description text element.|-|Optional|
 |consentDialogContent|SlotStyle \|undefined|Dialog content region (typically holds ConsentWidget).|-|Optional|
-|consentDialogFooter|SlotStyle \|undefined|Dialog footer container with actions/branding.|-|Optional|
+|consentDialogFooter|SlotStyle \|undefined|Footer container used by compound dialog layouts.|-|Optional|
+|consentDialogTag|SlotStyle \|undefined|Branding tag rendered below the stock consent dialog card.|-|Optional|
 |consentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the dialog.|-|Optional|
 |consentWidget|SlotStyle \|undefined|Root wrapper for the consent widget/preferences panel.|-|Optional|
 |consentWidgetAccordion|SlotStyle \|undefined|Accordion region listing consent categories.|-|Optional|
 |consentWidgetFooter|SlotStyle \|undefined|Footer area for widget actions and links.|-|Optional|
-|consentWidgetBranding|SlotStyle \|undefined|Branding element rendered in the widget footer.|-|Optional|
+|consentWidgetTag|SlotStyle \|undefined|Branding tag rendered below the standalone consent widget.|-|Optional|
 |frame|SlotStyle \|undefined|Frame wrapper used by blocking placeholders (e.g., iframe blocking).|-|Optional|
 |iabConsentBanner|SlotStyle \|undefined|Root wrapper for the IAB consent banner.|-|Optional|
 |iabConsentBannerCard|SlotStyle \|undefined|Main card container for IAB banner content.|-|Optional|
 |iabConsentBannerHeader|SlotStyle \|undefined|Header region for IAB banner title/description.|-|Optional|
 |iabConsentBannerFooter|SlotStyle \|undefined|Footer container for IAB banner actions.|-|Optional|
+|iabConsentBannerTag|SlotStyle \|undefined|Branding tag rendered above the IAB banner card.|-|Optional|
 |iabConsentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB banner.|-|Optional|
 |iabConsentDialog|SlotStyle \|undefined|Root wrapper for the IAB consent dialog.|-|Optional|
 |iabConsentDialogCard|SlotStyle \|undefined|Main card container for IAB dialog content.|-|Optional|
 |iabConsentDialogHeader|SlotStyle \|undefined|Header region for IAB dialog title/description.|-|Optional|
 |iabConsentDialogFooter|SlotStyle \|undefined|Footer container for IAB dialog actions.|-|Optional|
+|iabConsentDialogTag|SlotStyle \|undefined|Branding tag rendered below the IAB dialog card.|-|Optional|
 |iabConsentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB dialog.|-|Optional|
 |buttonPrimary|SlotStyle \|undefined|Shared primary button style used across consent components.|-|Optional|
 |buttonSecondary|SlotStyle \|undefined|Shared secondary button style used across consent components.|-|Optional|