@c15t/nextjs 2.0.0-rc.7 → 2.0.0-rc.9

package/docs/integrations/posthog.md

@@ -1,7 +1,7 @@
 ---
 title: PostHog
 description: PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
-lastModified: 2025-09-19
+lastModified: 2026-04-08
 
 icon: posthog
 ---
@@ -25,7 +25,7 @@ This is the recommended approach if you're using the Posthog JS SDK, this is com
    posthog.opt_out_capturing() // Avoids accidental tracking without consent till c15t has loaded
    ```
 
-2. **Adding the SDK callback to c15t** The PostHog SDK approach uses callbacks.onConsentSet instead of scripts. This lets you toggle PostHog's opt-in/opt-out based on the user's consent choice.
+2. **Sync settled consent once, then subscribe to real changes** The recommended PostHog SDK approach uses two phases: run one initial sync after c15t has finished resolving consent, then subscribe to future real preference changes with subscribeToConsentChanges().
 
    > ℹ️ Info:
    >
@@ -35,20 +35,38 @@ This is the recommended approach if you're using the Posthog JS SDK, this is com
    import { getOrCreateConsentRuntime } from 'c15t';
    import { posthog } from 'posthog-js';
 
-   getOrCreateConsentRuntime({
+   function syncPostHogMeasurementConsent(hasMeasurementConsent: boolean) {
+     if (hasMeasurementConsent) {
+       posthog.opt_in_capturing();
+     } else {
+       posthog.opt_out_capturing();
+     }
+   }
+
+   const runtime = getOrCreateConsentRuntime({
      mode: 'hosted',
      callbacks: {
-       onConsentSet({ preferences }) {
-         if (preferences.measurement) {
-           posthog.opt_in_capturing();
-         } else {
-           posthog.opt_out_capturing();
-         }
-       }
-     }
+       onBannerFetched() {
+         syncPostHogMeasurementConsent(
+           runtime.consentStore.getState().has('measurement')
+         );
+       },
+     },
    });
+
+   runtime.consentStore
+     .getState()
+     .subscribeToConsentChanges(({ allowedCategories }) => {
+       syncPostHogMeasurementConsent(
+         allowedCategories.includes('measurement')
+       );
+     });
    ```
 
+   > ℹ️ Info:
+   >
+   > Avoid using onConsentSet plus manual deduplication for PostHog. subscribeToConsentChanges() already gives you the exact change-only semantics most analytics SDKs need.
+
 ## PostHog Script Implementation
 
 If you want to load posthog via a script tag it's recommended to use this approach.
@@ -80,8 +98,13 @@ By default c15t will always load the script regardless of consent. This is becau
    posthog({
      id: 'phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      apiHost: 'https://eu.i.posthog.com',
-     defaults: '2025-05-24',
-     options: { person_profiles: 'identified_only' }
+     scriptUrl: 'https://eu-assets.i.posthog.com/static/array.js',
+     initOptions: {
+       api_host: 'https://eu.i.posthog.com',
+       ui_host: 'https://eu.i.posthog.com',
+       autocapture: false,
+       person_profiles: 'identified_only',
+     }
    })
    ```
 
@@ -92,10 +115,9 @@ By default c15t will always load the script regardless of consent. This is becau
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |id|string|Your posthog id, begins with 'phc\_'.|-|✅ Required|
-|apiHost|string|Your posthog api host.|'https\://eu.i.posthog.com'|✅ Required|
-|defaults|string|The defaults for the posthog script.|-|✅ Required|
-|options|Record\<string, unknown>|Other optional options for the posthog script.|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'posthog-consent'; \`category\`: 'measurement'|-|Optional|
+|apiHost|string \|undefined|Your posthog api host.|'https\://eu.i.posthog.com'|Optional|
+|scriptUrl|string \|undefined|The PostHog array loader URL.|-|Optional|
+|initOptions|Record\<string, unknown> \|undefined|PostHog init options passed to \`posthog.init(...)\`.|-|Optional|
 
 ### Script
 

package/docs/integrations/tiktok-pixel.md

@@ -31,7 +31,7 @@ tiktokPixel({
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |pixelId|string|Your TikTok Pixel ID|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'tiktok-pixel'; \`src\`: \`https\://analytics.tiktok.com/i18n/pixel/events.js\`; \`category\`: 'marketing'|-|Optional|
+|scriptSrc|string \|undefined|TikTok Pixel loader base URL.|-|Optional|
 
 ### Script
 

package/docs/integrations/x-pixel.md

@@ -37,7 +37,7 @@ xPixelEvent('tw-xxxx-xxxx', { value: 10.00, currency: 'USD' });
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |pixelId|string|Your X Pixel ID|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'x-pixel'; \`src\`: \`https\://static.ads-twitter.com/uwt.js\`; \`category\`: 'marketing'|-|Optional|
+|scriptSrc|string \|undefined|X Pixel loader URL.|-|Optional|
 
 ### Script
 

package/docs/optimization.md

@@ -1,7 +1,7 @@
 ---
 title: Optimization
 description: Improve c15t startup performance in Next.js with rewrites, static prefetching, and rendering tradeoffs.
-lastModified: 2026-03-17
+lastModified: 2026-04-09
 ---
 Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
 
@@ -48,7 +48,7 @@ Why this helps:
 
 |Goal|Strategy|Tradeoff|
 |--|--|--|
-|Keep routes fully static|`C15tPrefetch` + `getPrefetchedInitialData()`|Still client-side fetch, but starts earlier|
+|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|
 
@@ -60,9 +60,72 @@ 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|
 
+### 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.
+
+```tsx title="app/layout.tsx"
+import { fetchInitialData } from '@c15t/nextjs';
+import ConsentManager from '@/components/consent-manager';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const ssrData = fetchInitialData({
+    backendURL: process.env.NEXT_PUBLIC_C15T_URL!,
+  });
+
+  return (
+    <html lang="en">
+      <body>
+        <ConsentManager ssrData={ssrData}>{children}</ConsentManager>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx title="components/consent-manager/provider.tsx"
+'use client';
+
+import { type ReactNode } from 'react';
+import {
+  ConsentManagerProvider,
+  ConsentBanner,
+  ConsentDialog,
+  type InitialDataPromise,
+} from '@c15t/nextjs';
+
+export default function ConsentManager({
+  children,
+  ssrData,
+}: {
+  children: ReactNode;
+  ssrData?: InitialDataPromise;
+}) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        store: { ssrData },
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> 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.
+
 ### Static Routes: Start Fetch Early In The Browser
 
-Use `C15tPrefetch` in your layout and consume the same Promise in the provider.
+Use `C15tPrefetch` in your layout. Matching prefetched data is consumed automatically by the runtime during first store initialization.
 
 ```tsx title="app/layout.tsx"
 import { C15tPrefetch } from '@c15t/nextjs';
@@ -92,7 +155,6 @@ import {
   ConsentManagerProvider,
   ConsentBanner,
   ConsentDialog,
-  getPrefetchedInitialData,
 } from '@c15t/nextjs';
 
 export default function ConsentManagerClient({ children }: { children: React.ReactNode }) {
@@ -101,10 +163,7 @@ export default function ConsentManagerClient({ children }: { children: React.Rea
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        ssrData: getPrefetchedInitialData({
-          backendURL: '/api/c15t',
-          overrides: { country: 'DE', region: 'BE', language: 'de' },
-        }),
+        overrides: { country: 'DE', region: 'BE', language: 'de' },
       }}
     >
       <ConsentBanner />
@@ -119,7 +178,7 @@ export default function ConsentManagerClient({ children }: { children: React.Rea
 > 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.
 >
 > ℹ️ **Info:**
-> If you use overrides or custom credentials in C15tPrefetch, pass the same values to getPrefetchedInitialData(...) so it resolves the matching prefetched request.
+> 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.
 
 ## Keep The Provider Mounted Across Navigation
 

package/docs/policy-packs.md

@@ -6,7 +6,7 @@ Policy packs configure how c15t handles regional consent — which model (opt-in
 
 **For most apps, you just need a `ConsentManagerProvider` pointing at your backend with presets configured there.** The frontend receives the resolved policy via the `/init` response — no client-side policy config required.
 
-When a backend isn't available — local development, static previews, Storybook, or as a resilience fallback — you can pass policies directly to the provider via `offlinePolicy.policyPacks` and c15t resolves them locally.
+When a backend isn't available — local development, static previews, Storybook, automated tests, or as a resilience fallback during a temporary outage — you can pass policies directly to the provider via `offlinePolicy.policyPacks` and c15t resolves them locally.
 
 > ℹ️ **Info:**
 > For QA and testing, use the c15t DevTools to simulate different regions and policy responses against your real backend, rather than switching to offline mode.
@@ -29,9 +29,9 @@ When using consent.io or a self-hosted backend, the provider connects automatica
 
 The backend resolves the correct policy based on the visitor's geo data and returns it in the `/init` response. Configure your presets on the backend side.
 
-## Offline Presets (Fallback)
+## Offline Presets (Development and Fallback)
 
-When no backend is available, pass presets directly to the provider:
+Use offline presets mainly for local development, Storybook, deterministic tests, or temporary backend outages:
 
 ```tsx
 import { policyPackPresets } from '@c15t/react';
@@ -109,7 +109,7 @@ For production Next.js apps, you can optionally hydrate the first `/init` respon
 
 ## Offline / Fallback
 
-For local development, static sites, or when the backend is unreachable, pass policies directly:
+For local development, previews, automated tests, or when the backend is temporarily unreachable, pass policies directly:
 
 ```tsx title="components/consent-manager/provider.tsx"
 'use client';
@@ -150,7 +150,7 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 ## Provider Shape
 
 Configure packs through `offlinePolicy.policyPacks`. Add `offlinePolicy.i18n`
-when you want offline mode to mirror hosted policy-profile language behavior:
+when you want local previews or fallback behavior to mirror hosted policy-profile language behavior:
 
 ```tsx
 <ConsentManagerProvider
@@ -209,7 +209,7 @@ With that setup, offline mode resolves language the same way as hosted mode:
 |`offlinePolicy: { policyPacks: [] }`|Explicit no-banner mode|
 |Non-empty pack, no match, no default|Explicit no-banner mode|
 
-Omitting the option gives you a safe opt-in default for local development and outage scenarios. Providing it tells c15t you want policy-driven behavior exactly as configured.
+Omitting the option gives you a safe opt-in default for local development and outage scenarios. Providing it tells c15t you want deterministic preview or fallback behavior exactly as configured.
 
 ## QA and Debugging
 
@@ -221,7 +221,7 @@ For deeper inspection:
 * Open the DevTools Policy panel to inspect matcher resolution and fingerprints
 * Compare your frontend preview with the backend `/init` response before shipping
 
-If you need fully deterministic resolution without a backend (e.g., in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
+If you need fully deterministic resolution without a backend during testing or preview work (for example, in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
 
 ```tsx
 options={{

package/docs/quickstart.md

@@ -33,15 +33,17 @@ availableIn:
    |yarn|`yarn add @c15t/nextjs`|
    |bun|`bun add @c15t/nextjs`|
 
-2. **Import styles** Import the prebuilt component stylesheet in your root layout. This is required for styled components to render correctly.
+2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
 
-   ```tsx
-   import '@c15t/nextjs/styles.css';
+   ```css
+   @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.
+
    > ℹ️ Info:
    >
-   > If you are using the headless API or fully custom styling, you can skip this import.
+   > If you are using the headless API or fully custom styling, you can skip this import. Your root layout should continue importing ./globals.css as usual.
 
 3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
 
@@ -85,7 +87,11 @@ availableIn:
 
    > ℹ️ Info:
    >
-   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but review the browser-only storage consequences before choosing it for production.
+   > Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.
+   >
+   > ℹ️ Info:
+   >
+   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.
 
 4. **Mount ConsentManager at the app root** Wrap your app tree with ConsentManager so all routes/components can access consent state.
 

package/docs/script-loader.md

@@ -4,7 +4,7 @@ description: Gate third-party scripts behind consent - load Google Analytics, Me
 ---
 The script loader manages third-party scripts based on consent state. Scripts are defined in the provider's `scripts` option and are automatically loaded when their required consent category is granted, and unloaded when consent is revoked.
 
-c15t has a collection of premade scripts available on the @c15t/scripts package. It's recomended to check if a pre-built integration exists before manually creating a script, see the [integrations overview](/docs/integrations/overview).
+c15t has a collection of premade scripts available in `@c15t/scripts`. Check the [integrations overview](/docs/integrations/overview) first before manually building a script.
 
 |Package manager|Command|
 |:--|:--|
@@ -15,6 +15,12 @@ c15t has a collection of premade scripts available on the @c15t/scripts package.
 
 > ℹ️ **Info:**
 > We recommend using the pre-built integrations when possible.
+>
+> ℹ️ **Info:**
+> If you need a vendor we do not ship yet, see the custom integration guide. It covers both one-off Script objects and reusable manifest-backed integrations.
+>
+> ℹ️ **Info:**
+> For app-specific scripts, use a plain Script object. For reusable integrations, prefer a manifest-backed helper so startup phases, consent signaling, and future server-side loading support stay structured.
 
 ## Basic Usage
 
@@ -47,6 +53,21 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 }
 ```
 
+## Choose the Right Approach
+
+* Use a plain `Script` for one-off app code.
+* Use a manifest-backed helper in `@c15t/scripts` for reusable integrations, contributions, or anything that needs structured startup behavior.
+
+If you are building something reusable, start with the [custom integration guide](/docs/integrations/building-integrations) before using raw callbacks.
+
+## Reusable Integrations
+
+For app-specific use, raw `Script` objects are usually enough.
+
+For reusable integrations, c15t uses a manifest-backed model in `@c15t/scripts`. That keeps startup phases, consent signaling, and vendor-specific boot logic structured instead of hidden inside large callback bodies.
+
+If you are building an integration for multiple apps or contributing upstream, use the [custom integration guide](/docs/integrations/building-integrations).
+
 ## Script Types
 
 ### Standard Scripts

package/docs/server-side.md

@@ -29,7 +29,7 @@ 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:**
-> Need fully static routes? Use C15tPrefetch in your layout and getPrefetchedInitialData() in your client provider instead of fetchInitialData(). See Optimization.
+> 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
 

package/docs/styling/tailwind.md

@@ -6,41 +6,47 @@ c15t works with Tailwind CSS out of the box. Use the `slots` theme option to app
 
 ## Setup
 
-Import the standard c15t stylesheet once at the root of your app:
+Import the standard c15t stylesheet once in your app-level CSS entrypoint:
 
-```tsx
-// React
-import '@c15t/react/styles.css';
+```css
+/* React: src/index.css */
+@import "@c15t/react/styles.css";
 
-// Next.js
-import '@c15t/nextjs/styles.css';
+/* Next.js: app/globals.css */
+@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.
+
 ### Tailwind v4
 
-Tailwind v4 automatically scans your source files. Import Tailwind normally. c15t component styles join Tailwind's `components` layer automatically, so no extra c15t-specific layer declaration is needed:
+Tailwind v4 automatically scans your source files. Import Tailwind normally, then place the c15t stylesheet immediately after it. c15t component styles join Tailwind's `components` layer automatically, so no extra c15t-specific layer declaration is needed:
 
-```css
+```css title="src/index.css"
 @import "tailwindcss";
+@import "@c15t/react/styles.css";
 ```
 
-### Tailwind v3
+```css title="app/globals.css"
+@import "tailwindcss";
+@import "@c15t/nextjs/styles.css";
+```
 
-Import the Tailwind 3-compatible c15t stylesheet before your app Tailwind globals, then keep your standard Tailwind directives in the app stylesheet:
+### Tailwind v3
 
-```tsx title="app/layout.tsx"
-import '@c15t/react/styles.tw3.css';
-import './globals.css';
-```
+Import the Tailwind 3-compatible c15t stylesheet after `@tailwind components;` and before `@tailwind utilities;`:
 
-```tsx title="app/layout.tsx"
-import '@c15t/nextjs/styles.tw3.css';
-import './globals.css';
+```css title="src/index.css"
+@tailwind base;
+@tailwind components;
+@import "@c15t/react/styles.tw3.css";
+@tailwind utilities;
 ```
 
 ```css title="app/globals.css"
 @tailwind base;
 @tailwind components;
+@import "@c15t/nextjs/styles.tw3.css";
 @tailwind utilities;
 ```
 

package/iab/styles.css

@@ -0,0 +1 @@
+@import "../dist/iab/styles.css";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/nextjs",
-	"version": "2.0.0-rc.7",
+	"version": "2.0.0-rc.9",
 	"description": "Developer-first CMP for Next.js: cookie banner, consent manager, preferences centre. GDPR ready with minimal setup and rich customization.",
 	"keywords": [
 		"nextjs",
@@ -33,9 +33,9 @@
 	"type": "module",
 	"exports": {
 		"./styles.css": "./dist/styles.css",
-		"./styles.tw3.css": "./src/styles.tw3.css",
+		"./styles.tw3.css": "./dist/styles.tw3.css",
 		"./iab/styles.css": "./dist/iab/styles.css",
-		"./iab/styles.tw3.css": "./src/iab/styles.tw3.css",
+		"./iab/styles.tw3.css": "./dist/iab/styles.tw3.css",
 		"./headless": {
 			"types": "./dist-types/headless.d.ts",
 			"import": "./dist/headless.js",
@@ -60,6 +60,8 @@
 		"docs",
 		"dist-types",
 		"client",
+		"styles.css",
+		"iab",
 		"src/styles.css",
 		"src/styles.tw3.css",
 		"src/iab/styles.css",
@@ -67,10 +69,10 @@
 	],
 	"scripts": {
 		"prebuild": "genversion --esm --semi src/version.ts",
-		"build": "bun prebuild && rslib build && bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
+		"build": "bun prebuild && rslib build && bun ../../scripts/normalize-dist-types.mjs && bun scripts/generate-distribution-css.ts && bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
 		"build:agent-docs": "bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
 		"check-types": "bun prebuild && tsc --noEmit",
-		"dev": "bun prebuild && rslib build",
+		"dev": "bun prebuild && rslib build && bun ../../scripts/normalize-dist-types.mjs && bun scripts/generate-distribution-css.ts",
 		"fmt": "bun biome format --write . && bun biome check --formatter-enabled=false --linter-enabled=false --write",
 		"lint": "bun biome lint ./src",
 		"prepack": "cd ../.. && bunx turbo run build --filter=@c15t/nextjs",
@@ -78,9 +80,9 @@
 		"test:watch": "bun prebuild && vitest --passWithNoTests"
 	},
 	"dependencies": {
-		"@c15t/react": "2.0.0-rc.7",
-		"@c15t/translations": "2.0.0-rc.5",
-		"c15t": "2.0.0-rc.6"
+		"@c15t/react": "2.0.0-rc.9",
+		"@c15t/translations": "2.0.0-rc.8",
+		"c15t": "2.0.0-rc.8"
 	},
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1-beta.1",

package/readme.json

@@ -21,6 +21,10 @@
 		"",
 		"```bash\npnpm add @c15t/nextjs\n```",
 		"",
+		"Then add the prebuilt stylesheet to your app-level CSS entrypoint:",
+		"",
+		"```css\n/* app/globals.css */\n@import \"@c15t/nextjs/styles.css\";\n```",
+		"",
 		"To manually install, follow the guide in our [docs – manual setup](https://c15t.com/docs/frameworks/nextjs/quickstart#manual-setup)."
 	],
 	"usage": [

package/src/iab/styles.css

@@ -1,10 +1,12 @@
 /**
  * @c15t/nextjs — IAB TCF component styles.
  *
- * Import this stylesheet when using IAB consent components in Next.js.
- * Self-contained — includes shared primitives, no need for base 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:
- *   import '@c15t/nextjs/iab/styles.css';
+ * Usage (app/globals.css):
+ *   @import "@c15t/nextjs/styles.css";
+ *   @import "@c15t/nextjs/iab/styles.css";
  */
 @import "@c15t/react/iab/styles.css";

package/src/iab/styles.tw3.css

@@ -1,10 +1,14 @@
 /**
  * @c15t/nextjs/iab — Tailwind 3-compatible IAB component styles.
  *
- * Import this stylesheet before your app Tailwind globals so utility classes
- * can come after the c15t base rules.
+ * Add this stylesheet to the same global CSS entrypoint as your base c15t styles.
+ * Do not import either stylesheet from JS/TSX files.
  *
- * Usage:
- *   import '@c15t/nextjs/iab/styles.tw3.css';
+ * 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/src/styles.css

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

package/src/styles.tw3.css

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

package/styles.css

@@ -0,0 +1 @@
+@import "./dist/styles.css";