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

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/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        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/react';
+
+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,147 @@
+---
+title: Optimization
+description: Improve c15t startup performance in React with prefetching, proxy rewrites, and rendering tradeoffs.
+lastModified: 2026-04-14
+---
+Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
+
+## Start Here
+
+Apply the optimizations in this order:
+
+|Situation|Use|Why|Tradeoff|
+|--|--|--|--|
+|Any production app using hosted mode|Same-origin `/api/c15t` proxy|Lowers browser startup overhead and keeps the backend origin out of client config|Requires framework or platform proxy setup|
+|Banner speed matters on cold loads|`buildPrefetchScript()`|Starts `/init` before your app hydrates|Still a browser-side fetch, not SSR|
+|Your app navigates client-side|Keep the provider mounted at the app root|Avoids remounting and re-running init work|Requires provider placement discipline|
+|You cannot proxy and must stay cross-origin|`<link rel="preconnect">`|Starts DNS/TLS work earlier|Smaller gain than same-origin proxying|
+|You are using Next.js and want SSR or static-route-specific guidance|Next.js optimization docs|Covers `C15tPrefetch`, `fetchInitialData()`, and rendering tradeoffs|Next-specific|
+
+> ℹ️ **Info:**
+> Treat same-origin proxying as the baseline optimization. The others are situational layers you add when startup timing or route behavior justifies them.
+
+## 1) Prefer Same-Origin Proxy
+
+Proxy c15t requests through your app server so the browser calls your own origin instead of a third-party domain.
+
+How you configure this depends on your framework — Vite has `server.proxy`, Remix has resource routes, and most deployment platforms support rewrite rules.
+
+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
+
+If you can only do one optimization, do this one first.
+
+## 2) Prefetch Init Data Early
+
+Use `buildPrefetchScript()` from the `c15t` core package to start the `/init` request before your app hydrates. Inject the script as early as possible in your HTML `<head>`.
+
+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|
+
+Use this when:
+
+* The app is client-rendered
+* You want a faster first banner without introducing SSR complexity
+* You control the HTML template or document `<head>`
+
+### Inline Script Prefetch
+
+```tsx
+import { buildPrefetchScript } from 'c15t';
+
+const prefetchScript = buildPrefetchScript({
+  backendURL: '/api/c15t',
+});
+
+// In your HTML template or root component:
+<head>
+  <script dangerouslySetInnerHTML={{ __html: prefetchScript }} />
+</head>
+```
+
+Then initialize your provider normally. Matching prefetched data is consumed automatically by the runtime during first store initialization:
+
+```tsx
+import {
+  ConsentManagerProvider,
+  ConsentBanner,
+  ConsentDialog,
+} from '@c15t/react';
+
+export default function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **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.
+
+## 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
+
+Mount `ConsentManagerProvider` as high in the tree as possible so route transitions do not recreate it.
+
+## Animation Performance
+
+The default motion tokens are tuned for speed-first product UI:
+
+|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/react/styling/overview).
+
+## Reduce Network Overhead
+
+If your browser must call a cross-origin backend URL directly, add `preconnect` so the browser can warm up the connection earlier. This is a fallback optimization when same-origin proxying is not possible.
+
+If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
+
+```tsx
+<head>
+  <link rel="preconnect" href="https://your-instance.c15t.dev" crossOrigin="" />
+</head>
+```
+
+## Next.js-Specific SSR And Static Routes
+
+This page is intentionally React-generic. If you are using Next.js and need SSR or static-route-specific guidance:
+
+* See [Next.js Optimization](/docs/frameworks/next/optimization) for the static-vs-dynamic decision guide
+* See [Next.js Server-Side Data Fetching](/docs/frameworks/next/server-side) for `fetchInitialData()`

package/docs/policy-packs.md

@@ -0,0 +1,240 @@
+---
+title: Policy Packs
+description: Configure regional consent policies in React — 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|
+
+## React Example (Hosted)
+
+Point the provider at your backend — policy resolution happens server-side:
+
+```tsx
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentManagerProvider,
+} from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        backendURL: 'https://your-instance.c15t.dev',
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Offline / Fallback
+
+For local development, previews, automated tests, or when the backend is temporarily unreachable, pass policies directly:
+
+```tsx
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentManagerProvider,
+  policyPackPresets,
+} from '@c15t/react';
+
+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.