@c15t/react 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/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,113 @@
+---
+title: Optimization
+description: Improve c15t startup performance in React with prefetching, proxy rewrites, and rendering tradeoffs.
+lastModified: 2026-03-17
+---
+Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
+
+## 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
+
+## 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|
+
+### 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
+
+## 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 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>
+```

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.

package/docs/quickstart.md

@@ -0,0 +1,152 @@
+---
+title: Quickstart
+description: Add consent management to your React app in under 5 minutes.
+lastModified: 2026-02-10
+availableIn:
+  - framework: 'javascript'
+    url: '/docs/frameworks/javascript/quickstart'
+    title: 'JavaScript'
+  - framework: 'react'
+    url: '/docs/frameworks/react/quickstart'
+    title: 'React'
+  - framework: 'next'
+    url: '/docs/frameworks/next/quickstart'
+    title: 'Next.js'
+---
+## Via CLI
+
+|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`|
+
+## Manual Installation
+
+1. **Install package**
+
+   |Package manager|Command|
+   |:--|:--|
+   |npm|`npm install @c15t/react`|
+   |pnpm|`pnpm add @c15t/react`|
+   |yarn|`yarn add @c15t/react`|
+   |bun|`bun add @c15t/react`|
+
+2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
+
+   ```css
+   @import "@c15t/react/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. src/main.tsx should keep importing ./index.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.
+
+   ```tsx
+   'use client';
+
+   import { type ReactNode } from 'react';
+   import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+
+   export default function ConsentManagerClient({ children }: { children: ReactNode }) {
+     return (
+       <ConsentManagerProvider
+         options={{
+           mode: 'hosted',
+           backendURL: 'https://your-instance.c15t.dev',
+           consentCategories: ['necessary', 'measurement', 'marketing'],
+           // Shows banner during development. Remove for production.
+           overrides: { country: 'DE' },
+         }}
+       >
+         <ConsentBanner />
+         <ConsentDialog />
+         {children}
+       </ConsentManagerProvider>
+     );
+   }
+   ```
+
+   ```tsx
+   import type { ReactNode } from 'react';
+   import ConsentManagerProvider from './provider';
+
+   export function ConsentManager({ children }: { children: ReactNode }) {
+     return <ConsentManagerProvider>{children}</ConsentManagerProvider>;
+   }
+   ```
+
+   > ℹ️ Info:
+   >
+   > 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 existing app tree with ConsentManager so all routes/components can access consent state.
+
+   ```tsx
+   import { ConsentManager } from './components/consent-manager';
+
+   export default function App() {
+     return (
+       <ConsentManager>
+         {/* your existing app */}
+       </ConsentManager>
+     );
+   }
+   ```
+
+5. **Verify it works** Start your development server and confirm:
+
+   A consent banner appears at the bottom of the pageClicking "Customize" opens a dialog with toggles for each consent categoryAfter accepting or rejecting, the banner dismisses and your choice persists across page reloads
+
+## Optional: Add DevTools
+
+Install DevTools only if you want a runtime inspector while building and debugging:
+
+|Package manager|Command|
+|:--|:--|
+|npm|`npm install @c15t/dev-tools`|
+|pnpm|`pnpm add @c15t/dev-tools`|
+|yarn|`yarn add @c15t/dev-tools`|
+|bun|`bun add @c15t/dev-tools`|
+
+Then add it inside your existing provider:
+
+```tsx title="components/consent-manager/provider.tsx"
+import { DevTools } from '@c15t/dev-tools/react';
+
+// ...
+
+<ConsentManagerProvider options={...}>
+  <ConsentBanner />
+  <ConsentDialog />
+  {process.env.NODE_ENV !== 'production' && <DevTools />}
+  {children}
+</ConsentManagerProvider>
+```
+
+> ℹ️ **Info:**
+> Want to understand what's happening under the hood? See Initialization Flow for the lifecycle and Cookie Management for script/cookie behavior and revocation handling.
+
+## Optional: AI Agents
+
+Install c15t agent skills to let AI agents help with styling, i18n, scripts & other configuration.
+
+|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`|
+
+See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
+
+## Next steps