@c15t/nextjs 2.0.0-rc.0 → 2.0.0-rc.10

package/docs/network-blocker.md

@@ -0,0 +1,178 @@
+---
+title: Network Blocker
+description: Block outgoing network requests to third-party domains until the user grants consent for the appropriate category.
+---
+The network blocker intercepts outgoing `fetch` and `XMLHttpRequest` calls and blocks them based on consent state and domain rules. This catches tracking requests that happen outside of script loading - for example, beacon calls, API requests to analytics endpoints, or pixel fires from already-loaded scripts.
+
+## Configuration
+
+Add `networkBlocker` to your provider options:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        networkBlocker: {
+          rules: [
+            {
+              id: 'google-analytics',
+              domain: 'google-analytics.com',
+              category: 'measurement',
+            },
+            {
+              id: 'facebook-pixel',
+              domain: 'facebook.com',
+              pathIncludes: '/tr',
+              category: 'marketing',
+            },
+            {
+              id: 'analytics-post',
+              domain: 'analytics.example.com',
+              methods: ['POST'],
+              category: 'measurement',
+            },
+          ],
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Rule Matching
+
+Rules match requests using three criteria:
+
+### Domain matching
+
+The `domain` field matches the request hostname. Subdomains are automatically included - a rule for `google-analytics.com` also matches `www.google-analytics.com` and `stats.google-analytics.com`.
+
+### Path matching
+
+The optional `pathIncludes` field requires the request URL path to contain the specified substring. This lets you target specific endpoints without blocking the entire domain.
+
+### Method matching
+
+The optional `methods` array restricts the rule to specific HTTP methods. If omitted, the rule applies to all methods.
+
+## Consent Conditions
+
+Like the script loader, `category` accepts a `HasCondition`:
+
+```tsx
+// Simple
+{ category: 'measurement' }
+
+// Must have both
+{ category: { and: ['measurement', 'marketing'] } }
+
+// Must have either
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+## Monitoring Blocked Requests
+
+### Console logging
+
+Blocked requests are logged to the console by default. Disable with `logBlockedRequests: false`.
+
+### Callback
+
+Use `onRequestBlocked` to handle blocked requests programmatically:
+
+```tsx
+networkBlocker: {
+  rules: [...],
+  onRequestBlocked: ({ method, url, rule }) => {
+    console.log(`Blocked ${method} ${url} (rule: ${rule?.id})`);
+  },
+}
+```
+
+## Runtime Updates
+
+Update the network blocker configuration at runtime:
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function NetworkBlockerManager() {
+  const { setNetworkBlocker } = useConsentManager();
+
+  const addRule = () => {
+    setNetworkBlocker({
+      rules: [
+        {
+          id: 'new-tracker',
+          domain: 'tracker.example.com',
+          category: 'marketing',
+        },
+      ],
+    });
+  };
+}
+```
+
+## API Reference
+
+### NetworkBlockerRule
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string \|undefined|Optional identifier for the rule. Useful for debugging and logging.|-|Optional|
+|domain|string|Domain that this rule applies to.|-|✅ Required|
+|pathIncludes|string \|undefined|Optional path substring that must be present in the request path for the rule to apply.|-|Optional|
+|methods|string\[] \|undefined|Optional list of HTTP methods that this rule applies to. If omitted, the rule applies to all methods.|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent condition that must be satisfied to allow the request. When this condition is not satisfied, matching requests will be blocked.|-|✅ Required|
+
+### NetworkBlockerConfig
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|Object \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+#### `initialConsents` ConsentState
+
+The consent state snapshot that is currently used for blocking logic.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `onRequestBlocked`
+
+Callback invoked whenever a request is blocked.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|method|string|The HTTP method of the blocked request (e.g. GET, POST).|-|✅ Required|
+|url|string|The URL of the blocked request.|-|✅ Required|
+|rule|NetworkBlockerRule \|undefined|The rule that caused the request to be blocked, if available. Can be undefined when the blocker configuration changed between evaluation and logging.|-|Optional|
+
+#### `rules` NetworkBlockerRule
+
+Domain rules that determine which requests should be blocked.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string \|undefined|Optional identifier for the rule. Useful for debugging and logging.|-|Optional|
+|domain|string|Domain that this rule applies to.|-|✅ Required|
+|pathIncludes|string \|undefined|Optional path substring that must be present in the request path for the rule to apply.|-|Optional|
+|methods|string\[] \|undefined|Optional list of HTTP methods that this rule applies to. If omitted, the rule applies to all methods.|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent condition that must be satisfied to allow the request. When this condition is not satisfied, matching requests will be blocked.|-|✅ Required|

package/docs/optimization.md

@@ -0,0 +1,234 @@
+---
+title: Optimization
+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.
+
+```ts title="next.config.ts"
+import type { NextConfig } from 'next';
+
+const config: NextConfig = {
+  async rewrites() {
+    return [
+      {
+        source: '/api/c15t/:path*',
+        destination: `${process.env.NEXT_PUBLIC_C15T_URL}/:path*`,
+      },
+    ];
+  },
+};
+
+export default config;
+```
+
+Then use:
+
+```tsx
+<ConsentManagerProvider options={{ backendURL: '/api/c15t', mode: 'hosted' }}>
+```
+
+Why this helps:
+
+* Same-origin requests avoid extra DNS/TLS setup in many deployments
+* Ad blockers are less likely to block your init endpoint
+* 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-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-project.inth.app) to avoid an extra server proxy hop.
+
+## 2) Choose A Startup Strategy
+
+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.
+
+### Client-Only Init
+
+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()` 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';
+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',
+        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-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` 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';
+import { ConsentManager } from '@/components/consent-manager';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <C15tPrefetch
+          backendURL="/api/c15t"
+          overrides={{ country: 'DE', region: 'BE', language: 'de' }}
+        />
+      </head>
+      <body>
+        <ConsentManager>{children}</ConsentManager>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx title="components/consent-manager/provider.tsx"
+'use client';
+
+import {
+  ConsentManagerProvider,
+  ConsentBanner,
+  ConsentDialog,
+} from '@c15t/nextjs';
+
+export default function ConsentManagerClient({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        overrides: { country: 'DE', region: 'BE', language: 'de' },
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> C15tPrefetch uses Next.js beforeInteractive script loading, so the /init request can start before hydration.
+>
+> ℹ️ **Info:**
+> 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
+
+Mount the consent provider at the app root so route transitions do not remount it.
+
+Why this helps:
+
+* Avoids re-running init work on client-side navigation
+* Prevents extra callback churn from remount cycles
+* Keeps banner/dialog state stable between route transitions
+
+## Animation Performance
+
+The default motion tokens are tuned for speed-first product UI:
+
+|Token|Duration|Used for|
+|--|--|--|
+|`fast`|80ms|Banner slide + overlay, card scale, button hover, widget entry/exit|
+|`normal`|150ms|Accordion, switch toggle|
+|`slow`|200ms|Dialog trigger snap, tab indicator|
+
+These defaults follow the principle that product UI should be fast and purposeful — animations exist for spatial continuity, not decoration. In benchmarks, animation duration contributes a constant floor to "data fetched → banner visible" timing. The default tokens sit at the lower end of standard UI ranges (80-200ms) to minimize that floor.
+
+To customize motion durations and easing, see [Styling](/docs/frameworks/next/styling/overview).
+
+## Reduce Network Overhead
+
+If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
+
+```tsx title="app/layout.tsx"
+<head>
+  <link rel="preconnect" href="https://your-project.inth.app" crossOrigin="" />
+</head>
+```

package/docs/policy-packs.md

@@ -0,0 +1,246 @@
+---
+title: Policy Packs
+description: Configure regional consent policies in Next.js — hosted mode, presets, and offline fallback.
+---
+Policy packs configure how c15t handles regional consent — which model (opt-in, opt-out, none), which categories, and what UI to show. The backend resolves the right policy automatically based on the visitor's location.
+
+**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, 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.
+
+## Hosted Mode (Recommended)
+
+When using inth.com or a self-hosted backend, the provider connects automatically. No policy configuration is needed on the frontend:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+  <ConsentBanner />
+  <ConsentDialog />
+  {children}
+</ConsentManagerProvider>
+```
+
+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 (Development and Fallback)
+
+Use offline presets mainly for local development, Storybook, deterministic tests, or temporary backend outages:
+
+```tsx
+import { policyPackPresets } from '@c15t/react';
+
+offlinePolicy: {
+  i18n: {
+    defaultProfile: 'default',
+    messages: {
+      default: {
+        translations: {
+          en: { cookieBanner: { title: 'Privacy choices' } },
+        },
+      },
+      eu: {
+        fallbackLanguage: 'en',
+        translations: {
+          en: { cookieBanner: { title: 'EU GDPR Consent' } },
+          fr: { cookieBanner: { title: 'Consentement RGPD' } },
+          de: { cookieBanner: { title: 'GDPR-Einwilligung' } },
+        },
+      },
+    },
+  },
+  policyPacks: [
+    {
+      ...policyPackPresets.europeOptIn(),
+      i18n: { messageProfile: 'eu' },
+    },
+    policyPackPresets.californiaOptOut(),
+    policyPackPresets.worldNoBanner(),
+  ],
+}
+```
+
+Available presets:
+
+|Preset|Model|Matches|
+|--|--|--|
+|`europeOptIn()`|`opt-in`|EEA + UK countries + geo fallback|
+|`europeIab()`|`iab`|EEA + UK countries + geo fallback (TCF 2.3)|
+|`californiaOptOut()`|`opt-out`|US-CA region|
+|`quebecOptIn()`|`opt-in`|CA-QC region|
+|`worldNoBanner()`|`none`|default fallback|
+
+## Next.js Example (Hosted)
+
+Point the provider at your backend — policy resolution happens server-side:
+
+```tsx title="components/consent-manager/provider.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentManagerProvider,
+} from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        backendURL: 'https://your-instance.c15t.dev',
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+For production Next.js apps, you can optionally hydrate the first `/init` response with the [server-side utilities](/docs/frameworks/next/server-side).
+
+## Offline / Fallback
+
+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';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentManagerProvider,
+  policyPackPresets,
+} from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'offline',
+        offlinePolicy: {
+          policyPacks: [
+            policyPackPresets.europeOptIn(),
+            policyPackPresets.californiaOptOut(),
+            policyPackPresets.worldNoBanner(),
+          ],
+        },
+        overrides: {
+          country: 'DE', // Preview as a German visitor
+        },
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Provider Shape
+
+Configure packs through `offlinePolicy.policyPacks`. Add `offlinePolicy.i18n`
+when you want local previews or fallback behavior to mirror hosted policy-profile language behavior:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+    offlinePolicy: {
+      i18n: {
+        defaultProfile: 'default',
+        messages: {
+          default: {
+            translations: {
+              en: { cookieBanner: { title: 'Privacy choices' } },
+            },
+          },
+          qc: {
+            fallbackLanguage: 'fr',
+            translations: {
+              en: { cookieBanner: { title: 'Quebec Privacy Settings' } },
+              fr: { cookieBanner: { title: 'Paramètres de confidentialité du Québec' } },
+            },
+          },
+        },
+      },
+      policyPacks: [
+        {
+          id: 'qc_opt_in',
+          match: { regions: [{ country: 'CA', region: 'QC' }] },
+          i18n: { messageProfile: 'qc' },
+          consent: { model: 'opt-in', expiryDays: 365 },
+          ui: { mode: 'banner' },
+        },
+        {
+          id: 'default',
+          match: { isDefault: true },
+          consent: { model: 'none' },
+          ui: { mode: 'none' },
+        },
+      ],
+    },
+    overrides: { country: 'CA', region: 'QC' },
+  }}
+>
+```
+
+With that setup, offline mode resolves language the same way as hosted mode:
+
+* the active policy profile defines the allowed language set
+* each profile can define its own `fallbackLanguage`
+* built-in translations only fill missing keys for the selected language
+
+## Fallback Behavior
+
+|Configuration|Result|
+|--|--|
+|`offlinePolicy.policyPacks` omitted|Synthetic opt-in fallback banner (also used for hosted network fallback)|
+|`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 deterministic preview or fallback behavior exactly as configured.
+
+## QA and Debugging
+
+The best way to test regional consent behavior is with the [c15t DevTools](/docs/frameworks/react/dev-tools). The DevTools Policy panel lets you simulate different countries, regions, and GPC signals against your real backend — no code changes needed.
+
+For deeper inspection:
+
+* Read `policy` and `policyDecision` from `useConsentManager()` to see the resolved config
+* 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 during testing or preview work (for example, in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
+
+```tsx
+options={{
+  mode: 'offline',
+  offlinePolicy: {
+    policyPacks: [
+      policyPackPresets.europeOptIn(),
+      policyPackPresets.californiaOptOut(),
+      policyPackPresets.worldNoBanner(),
+    ],
+  },
+  overrides: {
+    country: 'US',
+    region: 'CA',
+    language: 'en-US',
+    gpc: true, // Simulate Global Privacy Control
+  },
+}}
+```
+
+> ℹ️ **Info:**
+> For the full concept model (matchers, scope modes, re-prompting), see Policy Packs concepts. For backend setup, see the self-host guide.