@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/react/styling/tokens.md

@@ -0,0 +1,155 @@
+---
+title: Tokens
+description: Reference page for tokens.
+group: reference
+---
+## Color Tokens
+
+Color tokens define the palette for all consent components. Set `colors` for light mode and `dark` for dark mode overrides.
+
+When `textOnPrimary` is omitted, c15t derives it automatically from `primary` to keep text readable on primary-filled surfaces such as stock branding tags and buttons. Set `textOnPrimary` explicitly when you need a specific foreground color.
+
+```tsx
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+    surface: '#ffffff',
+    surfaceHover: '#f9fafb',
+    border: '#e5e7eb',
+    borderHover: '#d1d5db',
+    text: '#1f2937',
+    textMuted: '#6b7280',
+    textOnPrimary: '#ffffff',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+    switchTrack: '#d1d5db',
+    switchTrackActive: '#6366f1',
+    switchThumb: '#ffffff',
+  },
+  dark: {
+    primary: '#818cf8',
+    surface: '#1f2937',
+    text: '#f9fafb',
+    textMuted: '#9ca3af',
+    border: '#374151',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ColorTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ColorTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Typography Tokens
+
+Control font family, sizes, weights, and line heights.
+
+```tsx
+const theme = {
+  typography: {
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSize: { sm: '0.875rem', base: '1rem', lg: '1.125rem' },
+    fontWeight: { normal: 400, medium: 500, semibold: 600 },
+    lineHeight: { tight: '1.25', normal: '1.5', relaxed: '1.75' },
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`TypographyTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "TypographyTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Spacing Tokens
+
+Five-step scale for internal padding, margins, and gaps.
+
+```tsx
+const theme = {
+  spacing: {
+    xs: '0.25rem',  // 4px
+    sm: '0.5rem',   // 8px
+    md: '1rem',     // 16px
+    lg: '1.5rem',   // 24px
+    xl: '2rem',     // 32px
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SpacingTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SpacingTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Radius Tokens
+
+Border radius scale for rounded corners.
+
+```tsx
+const theme = {
+  radius: {
+    sm: '0.25rem',  // 4px
+    md: '0.5rem',   // 8px
+    lg: '0.75rem',  // 12px
+    full: '9999px', // Pill shape
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`RadiusTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "RadiusTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Shadow Tokens
+
+Box shadow scale for depth and elevation.
+
+```tsx
+const theme = {
+  shadows: {
+    sm: '0 1px 2px hsla(0, 0%, 0%, 0.05)',
+    md: '0 4px 12px hsla(0, 0%, 0%, 0.08)',
+    lg: '0 8px 24px hsla(0, 0%, 0%, 0.12)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ShadowTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ShadowTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Motion Tokens
+
+Animation duration and easing presets.
+
+```tsx
+const theme = {
+  motion: {
+    duration: { fast: '100ms', normal: '200ms', slow: '300ms' },
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    easingOut: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
+    easingInOut: 'cubic-bezier(0.645, 0.045, 0.355, 1)',
+    easingSpring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`MotionTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "MotionTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/troubleshooting.md

@@ -0,0 +1,82 @@
+---
+title: Troubleshooting
+description: Reference page for troubleshooting.
+group: reference
+---
+## "Provider not found" Error
+
+**Symptom:** `useConsentManager must be used within a ConsentManagerProvider` error.
+
+**Fix:** Ensure the component calling `useConsentManager()` (or any c15t hook) is rendered inside a `ConsentManagerProvider`:
+
+```tsx
+// Wrong — hook is outside the provider
+function App() {
+  const { consents } = useConsentManager(); // throws
+  return <ConsentManagerProvider options={...}>...</ConsentManagerProvider>;
+}
+
+// Correct — hook is inside the provider
+function App() {
+  return (
+    <ConsentManagerProvider options={...}>
+      <MyComponent /> {/* useConsentManager works here */}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Banner Doesn't Show
+
+**Possible causes:**
+
+1. **Opt-out jurisdiction** — In CCPA/opt-out regions, the banner is not shown because tracking is allowed by default. Check `model` from `useConsentManager()` — if it's `'opt-out'`, the banner is intentionally hidden.
+
+2. **Consent already given** — If the user has already made a consent choice, the banner won't reappear. Clear cookies or use `resetConsents()` to test again.
+
+3. **`activeUI` is `'none'`** — Something is explicitly setting `activeUI` to `'none'`. Check the DevTools panel for the current consent state.
+
+4. **Backend not responding** — In `'c15t'` mode, the banner waits for the backend `/init` response. Check the Network tab for failed requests to your `backendURL`.
+
+```tsx
+// Debug: check what the consent manager sees
+const { activeUI, model, isLoadingConsentInfo } = useConsentManager();
+console.log({ activeUI, model, isLoadingConsentInfo });
+```
+
+## Consent Not Persisting
+
+**Symptom:** Consent is lost after page reload.
+
+**Possible causes:**
+
+1. **Incognito/private mode** — Some browsers restrict cookie storage in private browsing.
+
+2. **Cookie settings** — In `'offline'` mode, consent is stored in cookies. Ensure cookies are not being blocked by browser settings or extensions.
+
+3. **Different domains** — Cookies are domain-scoped. If your dev server uses a different domain than production, consent won't carry over.
+
+4. **Backend errors** — In `'c15t'` mode, check that the backend is saving consent successfully. Enable `debug: true` in provider options to see detailed logs.
+
+## Scripts Not Loading
+
+**Symptom:** Third-party scripts configured in the `scripts` option don't load after consent is granted.
+
+**Checklist:**
+
+1. **Wrong category name** — The `category` on the script must match one of the `consentCategories` names. For example, `'measurement'` not `'analytics'`.
+
+2. **Consent condition not met** — Use `has('measurement')` to verify the category is actually consented.
+
+3. **Script error** — Check the browser DevTools Console for script loading errors. The `onError` callback can help debug:
+
+```tsx
+{
+  id: 'analytics',
+  src: 'https://...',
+  category: 'measurement',
+  onError: ({ error }) => console.error('Script failed:', error),
+}
+```
+
+4. **Ad blocker** — Browser extensions may block the script regardless of consent. The `anonymizeId` option (default: `true`) helps avoid pattern-based blocking.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@c15t/nextjs",
-	"version": "2.1.0",
-	"description": "Headless cookie banner, consent manager & preference center for Next.js. App Router & Pages Router, RSC, GDPR/CCPA/LGPD/TCF compliant.",
+	"version": "2.2.1",
+	"description": "Next.js cookie banner and consent management platform for App Router, Pages Router, SSR, IAB TCF, and Consent Mode.",
 	"keywords": [
 		"nextjs",
 		"next",
@@ -31,7 +31,10 @@
 		"rsc",
 		"ssr",
 		"server-side-rendering",
-		"tracking-consent"
+		"tracking-consent",
+		"google-consent-mode",
+		"consent-mode-v2",
+		"nextjs-cmp"
 	],
 	"homepage": "https://c15t.com/docs/frameworks/next/quickstart",
 	"bugs": {
@@ -62,6 +65,11 @@
 			"import": "./client/components/consent-dialog-link.js",
 			"require": "./dist/index.cjs"
 		},
+		"./components/integrations": {
+			"types": "./dist-types/components/integrations/index.d.ts",
+			"import": "./client/components/integrations.js",
+			"require": "./dist/components/integrations/index.cjs"
+		},
 		".": {
 			"types": "./dist-types/index.d.ts",
 			"import": "./dist/index.js",
@@ -73,8 +81,9 @@
 	"types": "./dist-types/index.d.ts",
 	"files": [
 		"dist",
-		"docs",
 		"dist-types",
+		"AGENTS.md",
+		"docs",
 		"client",
 		"styles.css",
 		"styles.tw3.css",
@@ -86,8 +95,8 @@
 	],
 	"scripts": {
 		"prebuild": "genversion --esm --semi src/version.ts",
-		"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",
+		"build": "bun prebuild && rslib build && bun ../../scripts/normalize-dist-types.mjs && bun scripts/generate-distribution-css.ts && bun ../../scripts/generate-package-docs.ts @c15t/nextjs",
+		"build:docs": "bun ../../scripts/generate-package-docs.ts @c15t/nextjs",
 		"check-types": "bun prebuild && tsc --noEmit",
 		"dev": "sh -c 'bun prebuild && rslib build --no-dts --no-clean && bun scripts/generate-distribution-css.ts && rslib build --watch --no-dts --no-clean'",
 		"fmt": "bun biome format --write . && bun biome check --formatter-enabled=false --linter-enabled=false --write",
@@ -97,15 +106,15 @@
 		"test:watch": "bun prebuild && vitest --passWithNoTests"
 	},
 	"dependencies": {
-		"@c15t/react": "2.1.0",
-		"@c15t/translations": "2.1.0",
-		"c15t": "2.1.0"
+		"@c15t/react": "2.2.1",
+		"@c15t/translations": "2.2.1",
+		"c15t": "2.2.1"
 	},
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1",
 		"@c15t/vitest-config": "1.0.0",
 		"genversion": "3.2.0",
-		"typescript": "6.0.2"
+		"typescript": "7.0.1-rc"
 	},
 	"peerDependencies": {
 		"next": "^16.0.0 || ^15.0.0 || ^14.0.0 || ^13.0.0",

package/readme.json

@@ -1,21 +1,23 @@
 {
 	"title": "@c15t/nextjs: Next.js Integration",
-	"description": "Headless cookie banner, consent manager & preference center for Next.js. App Router & Pages Router, RSC, GDPR/CCPA/LGPD/TCF compliant.",
+	"description": "Next.js cookie banner and consent management platform for App Router, Pages Router, SSR, and headless consent flows.",
 	"features": [
-		"Works with Next.js 15, 14, and 13",
+		"Works with Next.js 16, 15, 14, and 13",
 		"Full 'use client' support for React Server Components",
 		"Server-side rendering support for both app and pages routers",
-		"Automatic GDPR compliance",
+		"Prebuilt and customizable cookie banner, consent dialog, and preference center UI",
+		"Headless hooks for custom consent flows",
 		"Minimal configuration with TypeScript-first design",
-		"Headless, customisable UI components (Cookie Banner, Consent Dialog, etc.)",
-		"Built-in internationalisation support",
+		"IAB TCF 2.3 UI and hooks through the @c15t/react/iab subpath",
+		"Google Tag Manager, Google Consent Mode v2, Meta Pixel, and analytics integrations through @c15t/scripts",
+		"Built-in internationalization support",
 		"Seamless consent storage and tracking"
 	],
 	"prerequisites": [
 		"Next.js 13.5.4 or later",
 		"React 18 or later",
 		"Node.js 18.17.0 or later",
-		"A hosted [c15t instance](https://inth.com) (free sign-up) or [self-hosted deployment](https://c15t.com/docs/self-host/v2)"
+		"A hosted [c15t instance](https://inth.com) (free sign-up), [self-hosted deployment](https://c15t.com/docs/self-host/quickstart), or offline mode for local-only storage"
 	],
 	"manualInstallation": [
 		"",
@@ -30,11 +32,15 @@
 	"usage": [
 		"Import `ConsentManagerProvider` in your app's root layout",
 		"Add `ConsentBanner` and `ConsentDialog` components",
-		"Customise styling and behaviour to fit your app",
+		"Customize styling and behavior to fit your app",
 		"For full implementation details, see the [Next.js quickstart docs](https://c15t.com/docs/frameworks/next/quickstart)",
 		"```tsx\n// app/layout.tsx\nimport {\n  ConsentManagerProvider,\n  ConsentBanner,\n  ConsentDialog,\n} from '@c15t/nextjs'\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang=\"en\">\n      <body>\n        <ConsentManagerProvider>\n          {children}\n          <ConsentBanner />\n          <ConsentDialog />\n        </ConsentManagerProvider>\n      </body>\n    </html>\n  )\n}\n```"
 	],
 	"docsLink": "https://c15t.com/docs/frameworks/next/quickstart",
 	"quickStartLink": "https://c15t.com/docs/frameworks/next/quickstart",
-	"showCLIGeneration": true
+	"showCLIGeneration": true,
+	"customSections": {
+		"Deployment Modes": "- **Hosted on inth.com**: Hosted c15t backend for policy storage, audit history, and hosted infrastructure\n- **Self-hosted backend**: Use @c15t/backend with your own database and infrastructure\n- **Offline mode**: Browser-only consent storage for local development, demos, previews, static sites, or fallback scenarios",
+		"Popular Integrations": "- Google Tag Manager with Google Consent Mode v2\n- Google Analytics 4 and Google Ads through gtag.js\n- Meta Pixel, TikTok Pixel, LinkedIn Insights, Microsoft UET, X Pixel, Reddit Pixel, and Snapchat Pixel\n- PostHog, Segment, Mixpanel, Microsoft Clarity, Hotjar, Plausible, Fathom, Matomo, Umami, and Vercel Analytics\n- Intercom and Crisp chat widgets"
+	}
 }

package/docs/ai-agents.md

@@ -1,111 +0,0 @@
----
-title: AI Agents
-description: Integrate c15t with AI coding assistants using the docs bundled in each package and c15t agent skills. Give agents version-matched local docs for consent management, banners, script loading, callbacks, and integrations.
-lastModified: 2026-03-24
----
-## Bundled Docs
-
-Every supported c15t package now ships docs inside the installed package itself.
-
-### Where to find them
-
-* `node_modules/c15t/docs/README.md`
-* `node_modules/@c15t/react/docs/README.md`
-* `node_modules/@c15t/nextjs/docs/README.md`
-* `node_modules/@c15t/backend/docs/README.md`
-
-Start with the package `README.md`, then follow its linked pages for the relevant workflow.
-
-These docs are version-matched to the exact c15t package version in your project, including generated reference content like prop and type tables.
-
-### Why use them
-
-If your app uses multiple c15t packages, use the docs from each relevant installed package instead of relying on stale model knowledge.
-
-### Agent philosophy
-
-When an AI tool is helping with c15t behavior, it should read the installed c15t docs first and use model knowledge second. That keeps consent flows, script gating, banner behavior, and integrations aligned with the exact version you have installed.
-
-### Customization ladder for agents
-
-When an agent is working on consent UI, it should choose the lowest-power tool that solves the task:
-
-1. Start with the pre-built component and its existing props or provider options
-2. Use `theme` tokens for semantic visual changes
-3. Use `theme.slots` for targeted styling of specific parts
-4. Use CSS variables or className-level overrides only when integrating with external styles
-5. Use compound components only when the markup order must change
-6. Use `noStyle` only when c15t structure is still correct but all styling must be replaced
-7. Use headless hooks only when markup and behavior both need to be rebuilt
-
-For common tasks:
-
-* Banner footer background -> `theme.colors.surfaceHover`
-* Banner card background -> `theme.colors.surface`
-* Banner card/footer/title tweaks -> banner slots
-* Stock action styling -> `theme.consentActions`
-* Copy changes -> `ConsentManagerProvider.options.i18n`
-
-If a token appears not to work, the agent should verify the token-to-component mapping before suggesting CSS overrides, `!important`, `noStyle`, or headless mode.
-
-***
-
-## Agent Skills
-
-c15t publishes agent skills that give AI coding assistants deep knowledge of c15t's APIs, components, and configuration. Skills are reusable workflows and tool-specific guidance, not version-matched local docs.
-
-### Installation
-
-Via the c15t CLI:
-
-|Package manager|Command|
-|:--|:--|
-|npm|`npx @c15t/cli install-skills`|
-|pnpm|`pnpm dlx @c15t/cli install-skills`|
-|yarn|`yarn dlx @c15t/cli install-skills`|
-|bun|`bunx @c15t/cli install-skills`|
-
-Or directly:
-
-|Package manager|Command|
-|:--|:--|
-|npm|`npx skills add c15t/skills`|
-|pnpm|`pnpm dlx skills add c15t/skills`|
-|yarn|`yarn dlx skills add c15t/skills`|
-|bun|`bunx skills add c15t/skills`|
-
-### What skills provide
-
-* **Styling customization** — strict escalation guidance across props, tokens, slots, CSS variables, compound components, `noStyle`, and headless
-* **Internationalization** — translation setup, locale routing integration
-* **Script management** — configuring third-party scripts with consent categories
-* **Component setup** — ConsentBanner, ConsentDialog, provider configuration
-
-### Supported tools
-
-* Claude Code
-* Cursor
-* GitHub Copilot (via `.github/skills`)
-* Any agent that supports the skills format
-
-***
-
-## When to use which
-
-Use bundled docs when:
-
-* Your agent can read files in the local project
-* You want version-matched docs from the installed c15t packages
-* You want a package-local README that tells the agent which detailed docs to read first
-* You want concrete guidance for consent management, cookie banners, consent dialogs, preference centers, script loading, callbacks, and integrations
-
-Use agent skills when:
-
-* Your tool supports the skills ecosystem
-* You want reusable workflows and tool-specific guidance that can point back to the installed package README files
-
-Use both when:
-
-* Your tool supports both local file context and skills
-* You want local package docs plus reusable setup and configuration help
-* You want the bundled package docs as the source of truth plus a reusable decision tree for customization

package/docs/components/consent-dialog-trigger.md

@@ -1,103 +0,0 @@
----
-title: ConsentDialogTrigger
-description: A floating, draggable button that lets users re-open the consent dialog at any time.
----
-`ConsentDialogTrigger` is a floating button that opens the consent dialog when clicked. Users can drag it to any corner of the screen, and the position persists across sessions. Use it to give users a persistent way to manage their privacy settings.
-
-## Basic Usage
-
-Use standalone or via the `showTrigger` prop on `ConsentDialog`:
-
-```tsx
-import { ConsentDialogTrigger } from '@c15t/nextjs';
-
-// Standalone
-<ConsentDialogTrigger />
-
-// Via ConsentDialog
-<ConsentDialog showTrigger />
-```
-
-For inline footer links (instead of a floating button), use [`ConsentDialogLink`](/docs/frameworks/next/components/consent-dialog-link).
-
-## Icon Options
-
-```tsx
-{/* Built-in icons */}
-<ConsentDialogTrigger icon="branding" />    {/* c15t logo (default) */}
-<ConsentDialogTrigger icon="fingerprint" /> {/* Privacy icon */}
-<ConsentDialogTrigger icon="settings" />    {/* Gear icon */}
-
-{/* Custom icon */}
-<ConsentDialogTrigger icon={<MyCustomIcon />} />
-```
-
-## Visibility
-
-Control when the trigger is visible:
-
-```tsx
-{/* Always visible (default) */}
-<ConsentDialogTrigger showWhen="always" />
-
-{/* Only after user has made a consent choice */}
-<ConsentDialogTrigger showWhen="after-consent" />
-
-{/* Hidden (control visibility programmatically) */}
-<ConsentDialogTrigger showWhen="never" />
-```
-
-## Position
-
-Set the default corner and control persistence:
-
-```tsx
-<ConsentDialogTrigger
-  defaultPosition="bottom-left"
-  persistPosition={true} // Remembers user's drag position
-  onPositionChange={(position) => console.log('Moved to:', position)}
-/>
-```
-
-## Size
-
-```tsx
-<ConsentDialogTrigger size="sm" /> {/* Small */}
-<ConsentDialogTrigger size="md" /> {/* Medium (default) */}
-<ConsentDialogTrigger size="lg" /> {/* Large */}
-```
-
-## Compound Components
-
-Build fully custom trigger layouts using sub-components:
-
-```tsx
-<ConsentDialogTrigger.Root defaultPosition="bottom-right">
-  <ConsentDialogTrigger.Button size="md">
-    <ConsentDialogTrigger.Icon icon="settings" />
-    <ConsentDialogTrigger.Text>Privacy</ConsentDialogTrigger.Text>
-  </ConsentDialogTrigger.Button>
-</ConsentDialogTrigger.Root>
-```
-
-* `ConsentDialogTrigger.Root` — Portal wrapper with drag handling and position persistence
-* `ConsentDialogTrigger.Button` — Draggable button element with size variants
-* `ConsentDialogTrigger.Icon` — Icon display (branding, fingerprint, settings, or custom)
-* `ConsentDialogTrigger.Text` — Optional text label
-
-## Props
-
-### ConsentDialogTriggerProps
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|icon|TriggerIcon|Icon to display in the trigger button.|'branding'|Optional|
-|defaultPosition|CornerPosition \|undefined|Default corner position for the trigger. User can drag to any corner and the position will be remembered.|'bottom-right'|Optional|
-|persistPosition|boolean \|undefined|Whether to persist the user's position preference in localStorage.|true|Optional|
-|ariaLabel|string \|undefined|Accessible label for the trigger button.|'Open privacy settings'|Optional|
-|className|string \|undefined|Additional CSS class names.|-|Optional|
-|noStyle|boolean \|undefined|When true, removes default styling.|false|Optional|
-|showWhen|TriggerVisibility \|undefined|Controls when the trigger is visible.|'always'|Optional|
-|size|TriggerSize \|undefined|Size of the trigger button.|'md'|Optional|
-|onClick|(() => void) \|undefined|Callback fired when the trigger is clicked (before opening dialog).|-|Optional|
-|onPositionChange|((position: CornerPosition) => void) \|undefined|Callback fired when the corner position changes.|-|Optional|