@c15t/react 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/react/components/dev-tools.md

@@ -4,61 +4,227 @@ description: A development tool for inspecting consent state, geolocation,
   loaded scripts, and consent events in real time.
 group: frameworks
 ---
-`DevTools` is a floating panel that shows the internal state of the consent manager. Use it during development to inspect consent values, geolocation results, loaded scripts, and debug consent flows. Also exported as `C15TDevTools` if you need to avoid naming conflicts with other devtools.
+
+`DevTools` is a floating panel for the c15t v3 kernel. Use it during development to inspect consent values, scripts, location, the resolved policy, IAB state, events, and consent actions. The framework adapter reads the kernel from the nearest v3 provider. It never discovers a store through a window global.
 
 > ⚠️ **Warning:**
-> DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
+> Load DevTools only in development. A conditional JSX expression stops it from mounting in production, but a static import can still add DevTools to the production bundle. Use a development-only dynamic import as shown below. The component renders nothing into the React tree and mounts its panel in document.body.
 
 ## Installation
 
-DevTools lives in a separate package to keep it out of production bundles:
-
-```bash
-bun add -D @c15t/dev-tools
-```
+No extra package is required for a framework adapter. The adapter and its
+engine are included with the `c15t` package and the dedicated
+`@c15t/svelte` adapter. Install `@c15t/dev-tools` directly only
+when you need the imperative `createDevTools({ kernel })` API.
 
 ## Usage
 
+This example uses Vite's `import.meta.env.DEV` build-time flag. For another
+bundler, use its development flag instead. For example, webpack projects can
+use a configured `process.env.NODE_ENV === 'development'` replacement;
+`process` is not a browser global.
+
 ```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { DevTools } from '@c15t/dev-tools/react';
+import { lazy, Suspense, type ReactNode } from 'react';
+import { ConsentProvider, hosted } from 'c15t/react';
+
+const DevTools =
+  import.meta.env.DEV
+    ? lazy(() =>
+        import('c15t/react/devtools').then(({ DevTools }) => ({ default: DevTools })),
+      )
+    : () => null;
 
 export function ConsentManager({ children }: { children: ReactNode }) {
   return (
-    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
+    <ConsentProvider options={{ mode: hosted({ url: 'https://your-instance.c15t.dev' }) }}>
       {children}
-      {process.env.NODE_ENV === 'development' && <DevTools />}
-    </ConsentManagerProvider>
+      <Suspense fallback={null}>
+        <DevTools />
+      </Suspense>
+    </ConsentProvider>
   );
 }
 ```
 
+Import the adapter from `c15t/react/devtools` when you use the umbrella package, or `c15t/react/devtools` when you install the React package directly. `@c15t/dev-tools` exports the imperative engine, not the React component.
+
+If the CLI cannot identify your bundler's development flag, it generates
+`const DevTools = false` with a setup comment. Replace `false` with your
+configured build-time development flag to enable the panel. The fallback keeps
+DevTools disabled instead of assuming browser globals or loading it in production.
+
 ## Configuration
 
 ```tsx
 <DevTools
-  position="bottom-right"  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
-  defaultOpen={false}       // Start with panel open
-  namespace="c15tStore"     // Store namespace to connect to
-  disabled={false}          // Disable without removing from tree
+  position="bottom-right"
+  defaultOpen={false}
+  defaultTab="consents"
+  maxEvents={100}
+  disabled={false}
 />
 ```
 
+`position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
+`bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
+to choose that panel. `maxEvents` limits captured kernel and script events.
+Set `disabled` to prevent mounting without removing the component.
+
 ## Panels
 
-|Panel|What it shows|
-|--|--|
-|**Consents**|Current consent state for all categories|
-|**Location**|Detected jurisdiction, country, region, and consent model|
-|**Scripts**|Configured scripts and their load status|
-|**IAB**|IAB TCF state (when enabled) - TC string, vendor consents, purposes|
-|**Events**|Timeline of consent events and state changes|
-|**Actions**|Buttons to trigger consent actions (accept all, reject all, reset)|
+Accept and reject apply only to categories displayed by the provider, leaving
+hidden consent values unchanged. `necessary` always remains enabled. Svelte
+and Vue adapters use their provider's displayed categories; the kernel and
+React adapter use the current policy categories by default.
+
+For an imperative integration with a narrower UI, pass
+`getConsentCategories: () => ['necessary', 'measurement']` to
+`createDevTools`. The getter is read again when an action runs. Headless UI
+actions can use `kernel.commands.save('all', { categories: displayed })` or
+`kernel.commands.save('none', { categories: displayed })`. These scoped bulk
+saves use a `custom` transport action when they cover only part of the policy.
+Actions covering the whole policy retain `all` or `necessary`. Without an
+explicit scope or policy categories, bulk saves cover all known categories.
+
+| Panel        | What it shows                                                                                |
+| ------------ | -------------------------------------------------------------------------------------------- |
+| **Consents** | Inspect and save categories, accept all, or reject optional categories                       |
+| **Scripts**  | Configured scripts, loading status, search, and external page resources                      |
+| **Location** | Detected jurisdiction, country, region, and consent model                                    |
+| **Policy**   | Resolved policy and UI configuration                                                         |
+| **IAB**      | Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings |
+| **Events**   | Timeline of consent changes, kernel events, and script lifecycle events                      |
+| **Actions**  | Show the banner, open preferences, hide consent UI, or refresh consent data                  |
+
+### Script inspection
+
+Set `defaultTab="scripts"` to open script inspection first. It reads all script
+loaders attached to the current provider's kernel, including loaders created
+before DevTools mounts. Search by script ID, category, URL, or status, then
+expand a script to inspect its configuration and latest lifecycle event.
+
+`loading` means an external script was inserted; `loaded` means its browser
+load event fired, or an inline script or callback-only integration mounted.
+`error` reports a loader error. `blocked` means consent requirements were not
+met, and `pending` means an eligible script has not mounted. `present` means
+the loader reused an element without a confirmed load result. `retained`
+means consent was revoked but `persistAfterConsentRevoked` kept the element.
+Retained scripts still receive `onConsentChange` with `hasConsent: false`, so
+their integrations can send the vendor's consent-revocation command.
+`alwaysLoad` bypasses the loading gate, not consent: callbacks receive the
+actual consent state and updates across categories for integrations such as
+Google Consent Mode.
+
+Script details distinguish `allowedToLoad` from `consentGranted`. An
+`alwaysLoad` integration can be allowed to load while its consent is denied.
+Diagnostics expose these as `eligible` and `hasConsent`, respectively.
+
+Lifecycle diagnostics work even when legacy debug forwarding is disabled.
+The page scan lists external scripts and iframes present in the
+DOM; it does not prove that they loaded successfully or were consent-gated.
+
+For custom inspection tools, import `getScriptDiagnostics(kernel)` and
+`subscribeScriptDiagnostics(kernel, listener)` from
+`c15t/modules/script-loader`. The subscription reports loader
+registration, updates, disposal, and lifecycle events. Read a fresh snapshot
+after changes and call the returned unsubscribe function during cleanup.
+
+### IAB editing
+
+Under an IAB policy, the Consents tab is read-only. Edit and save vendors
+and purposes in the IAB tab so the derived categories and TC string stay
+consistent.
+
+The IAB panel connects to the existing `@c15t/iab` module attached to the
+provider's kernel. It does not create a second CMP or replace `__tcfapi`.
+Controls become available after initialization, when the current policy uses
+IAB and the vendor list is loaded.
+
+Choose Vendors, Purposes, or Special features, then search by name or ID.
+Vendors include the provider's custom vendors. Long lists show 20 entries per
+page. Legitimate-interest controls appear for declared legitimate interests.
+Search only filters the view; Accept all IAB and Reject all IAB apply to the
+configured choices, including custom vendors.
+
+Toggles update live IAB state and script gating immediately. Use Save IAB
+consent to generate a fresh TC string and run the configured save transport.
+The panel displays the last generated string; unsaved edits are not represented
+in it. Copy TC string confirms success or reports clipboard failures. Raw IAB
+data remains available in an expandable section.
+
+IAB saves normally write the TC string to its standard cookie and localStorage.
+For an in-memory playground, set `persistence: false` in the IAB module options
+as well as disabling the provider's core persistence. The IAB option prevents
+TC-string storage writes; it does not disable the configured save transport
+or remove previously stored values.
+
+Save and refresh actions show pending, success, and failure feedback. Controls
+are disabled while a request is pending. A failed save does not roll back the
+live choices; retry to record them.
+
+For custom inspection tools, `getIABControls(kernel)` and
+`subscribeIABControls(kernel, listener)` are exported from `c15t`.
+The getter returns undefined before module initialization and after disposal.
+A snapshot without an attached IAB module is read-only in DevTools.
+
+## Vue and Svelte
+
+Vue imports `ConsentDevTools` from `c15t/vue/devtools`.
+Render it in the app where the c15t plugin provides
+the kernel. In Nuxt, the configured c15t module provides that context.
+
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue';
+
+const DevTools = import.meta.env.DEV
+  ? defineAsyncComponent(() => import('c15t/vue/devtools'))
+  : null;
+</script>
+
+<template>
+  <DevTools v-if="DevTools" position="bottom-right" />
+</template>
+```
+
+In Nuxt, use `import.meta.dev` instead of `import.meta.env.DEV`.
+Svelte imports the adapter from `@c15t/svelte/devtools` and renders it
+inside `ConsentManagerProvider`.
+
+```svelte
+<script lang="ts">
+  import { ConsentManagerProvider, offline } from '@c15t/svelte';
+
+  const devTools = import.meta.env.DEV
+    ? import('@c15t/svelte/devtools')
+    : null;
+</script>
+
+<ConsentManagerProvider options={{ mode: offline() }}>
+  {#if devTools}
+    {#await devTools then { ConsentDevTools }}
+      <ConsentDevTools position="bottom-right" />
+    {/await}
+  {/if}
+</ConsentManagerProvider>
+```
+
+Both adapters accept `position`, `defaultOpen`, `defaultTab`, `maxEvents`,
+`shadow` (`false` renders into the page instead of a shadow root),
+and `getConsentCategories`. Changing these presentation options recreates
+the panel and clears its event history. They do not accept React's `disabled`
+prop; conditionally render them instead. Unmounting removes the panel and
+subscriptions without changing consent.
 
 ## TanStack Devtools
 
-`@c15t/dev-tools/tanstack` exposes a panel component and plugin factory that match TanStack Devtools' plugin API, so c15t can sit beside Query and Router without a custom mount adapter:
+Each embedded panel owns its event history and subscriptions. Unmounting it
+destroys the instance; remounting starts a new history. If you need to capture
+events while switching plugins, keep the c15t panel mounted. This differs from
+the old globally shared DevTools store.
+
+The React v3 DevTools adapter exports a panel component and plugin factory that match TanStack Devtools' plugin API:
 
 ```tsx
 import * as React from 'react';
@@ -66,7 +232,7 @@ import { useRouter } from '@tanstack/react-router';
 import { TanStackDevtools } from '@tanstack/react-devtools';
 import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
 import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
-import { c15tDevtools } from '@c15t/dev-tools/tanstack';
+import { c15tDevtools } from 'c15t/react/devtools';
 
 export function AppDevtools() {
   const router = useRouter();
@@ -89,11 +255,10 @@ export function AppDevtools() {
 }
 ```
 
-## Props
+In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`C15TDevToolsProps\`|
-|Source Path|\`./packages/dev-tools/src/react.ts\`|
+## Props
 
-\*ExtractedTypeTable: Could not extract "C15TDevToolsProps" from "./packages/dev-tools/src/react.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+| Property | Type                | Description                                 | Default | Required |
+| :------- | :------------------ | :------------------------------------------ | :------ | :------: |
+| disabled | boolean \|undefined | Prevents the DevTools engine from mounting. | false   | Optional |

package/docs/frameworks/react/components/frame.md

@@ -1,72 +1,150 @@
 ---
 title: Frame
-description: A consent-gated content wrapper - children only mount when the
-  required consent category is granted.
+description: Gate a YouTube or map iframe behind consent with Frame in React,
+  showing a placeholder that opens the preference center until the category is
+  allowed.
 group: frameworks
 ---
-`Frame` conditionally renders its children based on consent state. When consent for the specified category is not granted, a placeholder is shown instead. Children are not mounted at all until consent is given, preventing any network requests or script execution.
 
-## Basic Usage
+## Gate an embed behind consent
 
-```tsx
-import { Frame } from '@c15t/react';
+`Frame` mounts its children only while the effective permission for one
+consent category is granted, and shows a placeholder otherwise. Wrap any
+iframe or third-party widget that would set cookies or contact a vendor on
+load. Render it anywhere inside the `ConsentProvider` from your
+[quickstart](../quickstart.md), which also mounts the `ConsentDialog` the
+placeholder button opens.
+
+```tsx title="src/product-video.tsx"
+import { Frame } from 'c15t/react';
 
-function YouTubeEmbed() {
+export function ProductVideo() {
   return (
-    <Frame category="marketing">
+    <Frame category="marketing" className="video-frame">
       <iframe
-        src="https://www.youtube.com/embed/dQw4w9WgXcQ"
-        width="560"
-        height="315"
+        src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
+        title="Product tour"
+        loading="lazy"
         allowFullScreen
+        style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
       />
     </Frame>
   );
 }
 ```
 
-## Custom Placeholder
+`marketing` must be in your policy scope. If you set a non-empty
+`options.consentCategories` list on `ConsentProvider`, include `marketing`
+there too so the preference center can display and save it. `Frame` does
+not add categories to that list.
+
+The placeholder names the category using its title from your translations. Set `className` or `style`
+on `Frame` to reserve the embed's space, so the page does not shift when the
+placeholder is replaced.
+
+## Props
+
+| Prop          | Type              | Default              | Description                                                                                                                                                                                                                              |
+| ------------- | ----------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `category`    | `AllConsentNames` | required             | The consent category whose effective permission gates the children, for example `'marketing'` or `'functionality'`.                                                                                                                      |
+| `children`    | `ReactNode`       | required             | The embed. It is not mounted until the category is allowed, so it makes no requests before permission.                                                                                                                                   |
+| `placeholder` | `ReactNode`       | built-in placeholder | Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content. |
+
+Other `div` attributes such as `className`, `style` and `ref` apply to the
+wrapper element that stays in the page in both states. `FrameProps` also
+declares `noStyle` and `theme`, but the component does not apply them yet;
+style the wrapper with `className` and theme the placeholder through the
+provider `theme` option.
+
+## Behavior
+
+`Frame` renders a `div` wrapper. Inside it, when the effective permission for
+`category` is granted, it renders the children; otherwise it renders the
+placeholder. Permission is the same value `useConsent(category)` returns,
+so it can be granted under an opt-out rule before the visitor records a
+choice, and a recorded grant can be overridden by a privacy signal.
+
+While effective permission is denied, the children are absent from the DOM,
+so an iframe or a third-party widget inside `Frame` sends no requests. When the visitor later revokes it, the
+children unmount and the embed disappears. `Frame` does not depend on the
+network blocker or the iframe blocker modules; use those for markup you
+cannot wrap in a component.
+
+The built-in placeholder shows the title `frame.title`, "Accept {category}
+consent to view this content.", with `{category}` replaced by
+`consentTypes.<category>.title`, and a button labelled `frame.actionButton`,
+"Enable {category} consent". The button opens the preference center; it
+does not grant the category by itself, because the visitor still has to
+save. Mount a `ConsentDialog` in the same provider so the button has
+something to open.
+
+Under a policy with `scopeMode: 'strict'`, a category outside the rule's
+scope cannot be granted. The built-in placeholder then shows `frame.policyBlocked`,
+"This content is unavailable under your region's consent policy.", without
+the button, and a stored grant for that category stays blocked.
 
-Replace the default placeholder:
+When the provider starts from a snapshot prefetched on the server, the
+server renders the children or placeholder according to effective permission.
+A grant in the request cookie allows the embed only when policy and privacy
+signals permit it. Browser privacy signals detected during hydration can
+withdraw that permission. In a browser-only setup the
+provider has no permission until it resolves policy on the client, so
+`Frame` shows the placeholder first and swaps in the embed after resolution
+when the category is already granted.
+
+`Frame` is one component on this page; the per-vendor embed guides for
+[YouTube](../../../integrations/youtube.md) and
+[Google Maps](../../../integrations/google-maps.md) show a complete embed
+configuration with sizing, titles and the same `Frame` usage across
+frameworks.
+
+To read the same permission in your own components, use `useConsent` from
+`c15t/react`; the `useIframeBlocker` and `useNetworkBlocker` module hooks
+also import from there.
+
+## Composition
+
+The placeholder parts are available as `Frame.Root`, `Frame.Title` and
+`Frame.Button` for a custom placeholder that keeps the built-in copy and
+behavior. `Frame.Title` and `Frame.Button` accept `category` and fill in the
+translated text; pass children to either to replace it.
 
 ```tsx
 <Frame
-  category="experience"
+  category="marketing"
   placeholder={
-    <div className="rounded-lg border p-8 text-center">
-      <p>This content requires experience cookies.</p>
-      <p>Please enable them in your privacy settings.</p>
-    </div>
+    <Frame.Root>
+      <Frame.Title category="marketing" />
+      <p>The video is also available on our channel.</p>
+      <Frame.Button category="marketing">Choose cookies</Frame.Button>
+    </Frame.Root>
   }
 >
-  <InteractiveWidget />
+  <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
 </Frame>
 ```
 
-## Compound Components
+The built-in placeholder carries `data-testid="frame-placeholder"` and its
+button `data-testid="frame-open-dialog"`.
 
-Build fully custom placeholder layouts:
+## Accessibility
 
-```tsx
-<Frame.Root category="marketing">
-  <Frame.Title category="marketing" />
-  <Frame.Button category="marketing" />
-</Frame.Root>
-```
-
-* `Frame.Root` - Container with default placeholder styling
-* `Frame.Title` - Displays a consent-request message with the category name
-* `Frame.Button` - Button that opens the consent dialog for the specified category
-
-## Automatic Category Registration
-
-When `Frame` mounts, it automatically adds its `category` to the active `consentCategories` list. This means you don't need to explicitly list the category in your provider's `consentCategories` option - if a `Frame` component uses it, it will be registered.
-
-## Props
+The placeholder is plain text and a `button`, so it is readable and
+operable without the embed. Give the iframe a descriptive `title`, and keep a
+transcript, address or link outside the `Frame` for visitors who decline
+the category. A denied category may be fixed by policy, so opening the
+preference center does not guarantee that the visitor can grant it.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`FrameProps\`|
-|Source Path|\`./packages/react/src/components/frame/types.ts\`|
+## Verify
 
-\*ExtractedTypeTable: Could not extract "FrameProps" from "./packages/react/src/components/frame/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Use an optional in-scope category that is available in the preference
+center and is not restricted by policy or privacy signals such as GPC.
+Load the page with the category denied. The placeholder text names the
+category and the network panel shows no request to the embed's host. With a
+prefetched snapshot, the server HTML contains the placeholder for a denied
+category or the embed for a granted category. Browser-only initialization
+shows the placeholder before policy resolves, then replaces it with the
+embed if the category is granted. After policy resolves, activate the
+placeholder button: the preference center opens. Turn the category on and
+Save: the placeholder is replaced by the embed and its requests start. Reject the
+category again from the preference center: the embed disappears.

package/docs/frameworks/react/concepts/consent-categories.md

@@ -1,98 +1,33 @@
 ---
-title: Consent Categories
-description: How c15t organizes tracking technologies into five consent categories.
+title: Consent categories
+description: Assign optional features to categories and understand how policy
+  scope affects permission.
 group: frameworks
 ---
-c15t organizes tracking technologies into five consent categories that align with GDPR and ePrivacy Directive requirements. Rather than asking users to approve or deny individual cookies or scripts, each category groups related tracking purposes together so users can make meaningful, informed choices about how their data is used.
 
-> ℹ️ **Info:**
-> Why categories, not cookie lists? Many consent banners list individual cookie names like \_ga, \_gid, or \_fbp. This is counterproductive:Technical names are meaningless to users — nobody knows what \_gid does by reading its name.Information overload drives "accept all" — a wall of cookie names pushes users toward dismissing the banner as fast as possible, which is the opposite of informed consent.Purpose is what matters — privacy regulations (GDPR, ePrivacy) require clear information about the purposes of data processing, not a cookie-by-cookie inventory.Cookie lists go stale — third-party scripts change their cookie names across versions, creating a maintenance burden that provides no real transparency.c15t's category-based approach — "measurement", "marketing", "experience" — communicates purpose directly. Users understand why data is collected, not how it is stored.
+## Choose categories by purpose
 
-Configure which categories your app supports in the provider:
+| Category        | Purpose                                        |
+| --------------- | ---------------------------------------------- |
+| `necessary`     | Functionality required for the site to operate |
+| `functionality` | Optional features such as support widgets      |
+| `measurement`   | Analytics and usage measurement                |
+| `experience`    | Optional personalization                       |
+| `marketing`     | Advertising and marketing                      |
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
+`necessary` is always permitted. Assign categories based on what an integration
+does in your application; renaming analytics to necessary does not change its
+purpose. The provider's displayed categories and the resolved policy scope must
+agree.
 
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
+## Respect policy scope
 
-## The Five Categories
+A strict scope denies categories outside the rule. A permissive scope can allow
+out-of-scope categories unless another restriction applies. When a rule selects
+only some optional categories, set `scopeMode` explicitly. An omitted scope,
+`['*']`, or a list containing only `necessary` expands to the default optional
+categories; a necessary-only list is not a shortcut for disabling all tracking.
 
-|Category|Default|Toggleable|Description|
-|--|--|--|--|
-|`necessary`|`true`|No|Strictly necessary to operate or deliver the service|
-|`functionality`|`false`|Yes|Basic interactions and functionalities|
-|`experience`|`false`|Yes|Improve quality of user experience|
-|`measurement`|`false`|Yes|Measure traffic and analyze behavior|
-|`marketing`|`false`|Yes|Deliver personalized ads or marketing content|
-
-The `necessary` category has `disabled: true` set internally, which prevents the user from toggling it off in the consent UI. All other categories can be freely toggled by the user.
-
-Note that all categories except `necessary` have `display: false` by default. A category appears in the consent UI only if you include it in `consentCategories`. Categories not listed are hidden from the UI, but they still exist in consent state and may be affected by model-level behavior (for example, auto-grant in `opt-out` or `null` model flows).
-
-Check if a specific category has consent using the `has()` method:
-
-```tsx
-import { useConsentManager } from '@c15t/react';
-
-function AnalyticsLoader() {
-  const { has } = useConsentManager();
-
-  if (has('measurement')) {
-    // Safe to load analytics scripts
-  }
-
-  return null;
-}
-```
-
-## Configuring Categories
-
-The `consentCategories` array controls which consent categories are presented to the user in the consent UI. Only categories you list in this array will appear as toggleable options in the consent banner or modal.
-
-The `necessary` category is always implicitly included even if you do not add it to the array. You never need to worry about accidentally omitting it -- c15t ensures it is always present and always enabled.
-
-For example, if you set:
-
-```
-consentCategories: ['necessary', 'measurement', 'marketing']
-```
-
-then only those three categories will show toggles in the consent UI. The `functionality` and `experience` categories will not appear as user-configurable toggles.
-
-In `opt-in`/`iab` flows, hidden categories usually remain `false` unless you explicitly set them. In `opt-out`/`null` flows, categories may be auto-granted even when hidden.
-
-This gives you precise control over which consent choices to present to your users. A simple blog that only runs an analytics script might only need `measurement`. A media site with ad integrations would include `marketing`. A SaaS application with personalization features might add `experience` and `functionality` as well. You choose what is relevant to your site and c15t handles the rest - storing consent state, exposing it through hooks, and ensuring the right categories are active based on the user's choices.
-
-You can dynamically update which categories are active:
-
-```tsx
-import { useConsentManager } from '@c15t/react';
-
-function CategoryManager() {
-  const { consentCategories, setConsentCategories } = useConsentManager();
-
-  const addExperienceCategory = () => {
-    setConsentCategories([...consentCategories, 'experience']);
-  };
-
-  return (
-    <button onClick={addExperienceCategory}>
-      Enable experience features
-    </button>
-  );
-}
-```
+Use effective permissions to gate work and explicit choices to inspect what the
+visitor confirmed. Read [consent state](../../../guides/consent-state.md) for that
+distinction and [migration](../../../upgrade-v3.md) for v3 policy configuration.