@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

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

@@ -1,72 +1,167 @@
 ---
 title: Frame
-description: A consent-gated content wrapper - children only mount when the
-  required consent category is granted.
+description: Consent-gate an iframe in Next.js with Frame inside ConsentRoot;
+  with server prefetch the placeholder or embed is decided in the server HTML.
 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/nextjs';
+`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. It is a Client Component; render it from any route under the layout
+that mounts the `ConsentRoot` from your
+[App Router](../app-router.md) or
+[Pages Router](../pages-router.md) setup, which also mounts
+the `ConsentDialog` the placeholder button opens.
+
+```tsx title="components/product-video.tsx"
+'use client';
 
-function YouTubeEmbed() {
+import { Frame } from 'c15t/next';
+
+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
+Import `ProductVideo` into any page or Server Component; only this file needs
+`'use client'`. `marketing` must be in your policy scope. If you set a
+non-empty `options.consentCategories` list on `ConsentRoot`, 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.
+
+With the awaited `resolveConsent` from the App Router guide, the
+server decides between placeholder and embed from the resolved rule and the
+request cookie. Pages Router works the same way when `getServerSideProps`
+awaits `resolveConsent` from `c15t/next/pages` and passes the result
+through `state` to `ConsentRoot`, as in the
+[Pages Router guide](../pages-router.md). Hydration keeps that choice as long as
+the browser's privacy signals agree with the request: a `navigator.globalPrivacyControl`
+that the request did not carry as `Sec-GPC` is re-detected on hydration and
+can withdraw a category. Under an opt-in rule a new
+visitor gets the placeholder and a returning visitor who allowed `marketing`
+gets the iframe; under an opt-out rule a new visitor already has effective
+permission, so the iframe renders until they opt out.
+
+## 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.
 
-Replace the default placeholder:
+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.
+
+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 Client Components, use `useConsent`
+from `c15t/next`; 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
-
-Build fully custom placeholder layouts:
-
-```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
+The built-in placeholder carries `data-testid="frame-placeholder"` and its
+button `data-testid="frame-open-dialog"`.
 
-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.
+## Accessibility
 
-## 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/next/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/nextjs';
+`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: '/api/c15t',
-        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/nextjs';
-
-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/nextjs';
-
-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.

package/docs/frameworks/next/concepts/policy-presets.md

@@ -0,0 +1,142 @@
+---
+title: Policy presets
+description: Understand how policy rules affect Next.js prompts, permissions and
+  persistent privacy controls.
+group: frameworks
+---
+
+## What the policy controls
+
+A policy rule selects the permission model, categories, prompt and persistent
+privacy controls for a visitor. Your app reads the resolved rule and effective
+permissions. It should not choose a different rule just to hide a banner.
+
+| Policy setting        | What your app should expect                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `model: 'opt-in'`     | Optional categories in scope wait for consent.                                                                                       |
+| `model: 'opt-out'`    | Categories in scope can be allowed before a choice. Saved refusals and privacy signals can restrict them.                            |
+| `model: 'none'`       | Categories in scope are allowed without an initial prompt. Stock consent controls stay hidden unless the rule grants privacy rights. |
+| `prompt: 'choice'`    | The banner asks for a choice when the current state requires one.                                                                    |
+| `prompt: 'notice'`    | Dismissing the notice records an acknowledgement, not a consent grant.                                                               |
+| `prompt: 'none'`      | No automatic prompt. The rule can still require a way to open preferences.                                                           |
+| `scopeMode: 'strict'` | Optional categories outside the rule's scope stay denied.                                                                            |
+
+Keep a persistent preferences entry point wherever the policy provides that
+right. A visitor who dismissed a notice or rejected tracking still needs a way
+to revisit their choice. Stock components read the rule's rights; custom UI
+must do the same.
+
+Use `effectivePermissions` to gate a script or embed. A `true` value under an
+opt-out rule does not mean the visitor clicked Accept. Read `explicitChoice`
+when you need the visitor's recorded decision. See
+[consent state](../../../guides/consent-state.md) for these distinctions.
+
+## Where to change the rules
+
+For Inth, configure policy rules on your hosted project. The app receives those
+rules through the configured [data-fetching path](../../../guides/data-fetching.md). Importing
+`recommendedPolicyRules()` or changing browser styling does not override the
+hosted policy.
+
+For a backend you operate, use the
+[policy packs guide](https://c15t.com/docs/self-host/guides/policy-packs). It covers
+`manifest.policyRules`, preset selection and custom matchers. Browser-only
+setups own their rules locally; see
+[deployment modes](../../../guides/deployment-modes.md).
+
+Presets are starting configurations. Select them for your actual processing,
+and review their assumptions before allowing optional categories by default.
+A country match does not establish a legal basis for a vendor's data use.
+
+## Why the banner may be absent
+
+A missing banner can be an expected policy outcome or an initialization problem.
+Check `resolution.status` before interpreting the active model.
+
+| State                                                   | What to check                                                                                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| A policy matched and `promptRequirement.kind` is `none` | The rule does not ask for an initial prompt, or the stored records already satisfy it. Check persistent preferences separately.       |
+| A policy matched but a category is denied               | Inspect `effectivePermissions`, `explicitChoice`, `privacySignals` and `restrictions`. A saved refusal or GPC can keep it denied.     |
+| No policy has matched                                   | Check backend connectivity, location inputs and policy configuration. Optional categories stay denied while resolution is unresolved. |
+
+Do not treat `policyRule` alone as proof that a policy resolved. The snapshot
+also carries a safe rule for evaluation while resolution is pending or failed.
+Use `resolution.policy` only after checking for `status: 'matched'`.
+
+The local `recommendedPolicyRules()` pack uses opt-in rules for Europe and
+Québec, opt-out for its supported US privacy states, and a no-prompt `none`
+default for other known locations. An unknown country uses its strict opt-in
+fallback. A US country with a missing state gets the US opt-out fallback.
+These are the local pack's defaults, not a promise about your Inth project.
+Browser-only mode does not discover a visitor's country from their IP address.
+
+## Keep Next.js server and browser state aligned
+
+Keep the prepared configuration from your
+[App Router](../app-router.md) or
+[Pages Router](../pages-router.md) setup intact when passing it
+to the consent boundary. That configuration includes the resolved policy,
+stored records and evaluation time. Replacing it with a separately selected
+browser preset can change the first render's permissions or prompt.
+
+Use the request's location and privacy signals when resolving policy. Do not
+cache a visitor's resolved configuration as shared policy data. A public
+manifest can be shared; the decision made from it belongs to the request.
+Use [data fetching](../data-fetching.md) to choose between a
+shared manifest, request-time `/init` and local policy resolution.
+For a deployment without a Next.js server, follow
+[static export](../static-export.md).
+
+## Inspect the active policy
+
+Place this diagnostic component inside your existing consent
+boundary. It reads state without recording a choice.
+
+```tsx title="app/consent-policy-debug.tsx"
+'use client';
+
+import { useSnapshot } from 'c15t/next';
+
+export function ConsentPolicyDebug() {
+  const snapshot = useSnapshot();
+  const resolution = snapshot.resolution;
+
+  return (
+    <pre>
+      {JSON.stringify(
+        {
+          status: resolution.status,
+          policy: resolution.status === 'matched' ? resolution.policy.id : null,
+          prompt: snapshot.promptRequirement,
+          permissions: snapshot.effectivePermissions,
+          location: snapshot.location,
+          privacySignals: snapshot.privacySignals,
+        },
+        null,
+        2,
+      )}
+    </pre>
+  );
+}
+```
+
+The diagnostic subscribes to consent changes. Remove it after verification.
+For a production feature gate, use `useConsent('marketing')` or the category
+your feature needs instead of subscribing to the whole snapshot.
+
+## Change appearance without changing policy
+
+Keep one banner and one dialog in your existing
+boundary. Use
+[styling](../styling/overview.md) to change their appearance,
+or [headless UI](../headless.md) for custom markup.
+Presentation settings change layout and emphasis; policy rules decide which
+actions and privacy rights the app must expose.
+
+## Verify policy behavior
+
+Use a fresh browser profile to check the intended location, then repeat with a
+saved rejection and GPC enabled. Confirm that the expected prompt and
+preferences controls appear, and that denied scripts and embeds make no
+requests. Test missing location inputs too. Follow
+[verify consent](../../../guides/verify-consent.md) for the full flow.

package/docs/frameworks/next/content-security-policy.md

@@ -0,0 +1,189 @@
+---
+title: Content Security Policy
+description: Pass a per-request CSP nonce to ConsentRoot in Next.js and allow
+  the consent backend in connect-src.
+group: frameworks
+---
+
+## Pass the request nonce to ConsentRoot
+
+Read the nonce from the `x-nonce` request header in the root layout and pass it
+as `options={{ nonce }}` on `ConsentRoot`. This is the standard Next.js
+nonce pattern: your `proxy.ts` (Next.js 16) or `middleware.ts` (Next.js 15)
+generates a nonce per request, sets the `Content-Security-Policy` response
+header with `'nonce-<value>'` in `script-src` and `style-src`, and forwards the
+same value on the request as `x-nonce`. See the
+[Next.js CSP guide](https://nextjs.org/docs/app/guides/content-security-policy)
+for the header-generating proxy.
+
+If you also run [`c15tProxy`](./geography-headers.md), set
+both `x-nonce` and the generated `Content-Security-Policy` header on
+`request.headers` before calling it, and set the policy on the returned
+response as well. Next.js reads the nonce for its own bootstrap and page
+scripts from the request-side policy header, so forwarding only `x-nonce`
+leaves the framework scripts without a nonce and the browser blocks hydration.
+`c15tProxy` copies the incoming request headers into the forwarded request, so
+both headers travel with the geography headers.
+
+Add a `nonce` prop to the `Consent` wrapper from the
+[App Router guide](./app-router.md):
+
+```tsx title="components/consent.tsx (partial)"
+'use client';
+
+import type { ReactNode } from 'react';
+import { ConsentRoot } from 'c15t/next';
+import type { ConsentRootProps } from 'c15t/next';
+import { consentConfig } from '../c15t.config';
+import { scripts } from '../lib/scripts';
+
+export function Consent({
+  children,
+  state,
+  nonce,
+}: {
+  children: ReactNode;
+  state: ConsentRootProps['state'];
+  nonce?: string;
+}) {
+  return (
+    <ConsentRoot
+      state={state}
+      config={consentConfig}
+      options={{ nonce }}
+      scripts={scripts}
+    >
+      {children}
+      {/* banner, dialog and footer as in the App Router guide */}
+    </ConsentRoot>
+  );
+}
+```
+
+Then read the header in the async consent component from the App Router guide
+and pass it through:
+
+```tsx title="app/layout.tsx"
+import { Suspense } from 'react';
+import type { ReactNode } from 'react';
+import { headers } from 'next/headers';
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import { Consent } from '../components/consent';
+import './globals.css';
+
+async function ResolvedConsent({ children }: { children: ReactNode }) {
+  const nonce = (await headers()).get('x-nonce') ?? undefined;
+  const state = await resolveConsent({ config: consentConfig });
+
+  return (
+    <Consent state={state} nonce={nonce}>
+      {children}
+    </Consent>
+  );
+}
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Suspense fallback={null}>
+          <ResolvedConsent>{children}</ResolvedConsent>
+        </Suspense>
+      </body>
+    </html>
+  );
+}
+```
+
+Reading `headers()` keeps the route dynamic, which a per-request nonce requires
+anyway. Do not combine a nonce-based policy with `cacheComponents: true`
+(Partial Prerendering): the static shell is rendered once at build time, so its
+scripts cannot carry a per-request nonce and the browser blocks them. Next.js
+documents this limitation in its CSP guide. For a prerendered shell use the
+hash-based policy that guide describes; a host-only `script-src` such as
+`'self'` does not authorize Next.js's inline bootstrap scripts and would need
+`'unsafe-inline'`, which defeats the policy. Otherwise keep the route fully
+dynamic and use the nonce.
+
+`options.nonce` is read when `ConsentRoot` mounts. The provider keeps the latest
+value in a ref, but the script loader is created once per runtime, so a nonce
+that changes during client-side navigation is not applied to scripts already
+created. Each full page load gets the fresh nonce from its own request.
+
+## What the nonce applies to
+
+c15t stamps `options.nonce` on two kinds of DOM nodes:
+
+* Every `<script>` element the script loader creates for a `scripts` entry,
+  both `src` and inline `textContent` scripts. A `nonce` set on an individual
+  `scripts` entry takes precedence over `options.nonce` for that element.
+* The `<style id="c15t-theme">` element the provider injects with the theme's
+  `--c15t-*` custom properties.
+
+It does not apply to anything else:
+
+* Scripts that a vendor script loads itself, such as a tag manager injecting
+  its tags, do not receive the nonce. Add `'strict-dynamic'` to `script-src` so
+  scripts loaded by a nonced script are allowed, or list those vendor hosts
+  explicitly.
+* The prebuilt stylesheet `c15t/next/styles.css` is a regular stylesheet from
+  your own origin. It is covered by `style-src 'self'`, not by the nonce.
+* Inline `style` attributes on rendered components. A nonce cannot authorize
+  style attributes, and browsers ignore `'unsafe-inline'` in a `style-src` list
+  that also contains a nonce or hash. Allow them with a separate
+  `style-src-attr 'unsafe-inline'` directive, or with `'unsafe-hashes'` plus
+  the matching `'sha256-...'` values; hashes only work for static values, not
+  for the animated collapse heights. The IAB TCF dialog, the consent dialog
+  trigger toolbar and the animated collapse used inside the dialogs render
+  inline `style` attributes. Check the
+  browser console with your policy enforced to see whether your setup triggers
+  a `style-src` violation.
+* Iframes, images or requests made by vendor scripts. Allow those hosts in
+  `frame-src`, `img-src` and `connect-src` according to each vendor.
+
+## Allow the consent backend in connect-src
+
+The browser sends consent submissions to `${backendURL}/subjects`, and, when
+the browser initializes or retries after a failed server prefetch, requests to
+`${backendURL}/init` or the manifest URL. Add the backend origin to
+`connect-src`, and the manifest origin too when `manifestURL` is an absolute
+URL on a different host such as a CDN:
+
+```txt title="Content-Security-Policy (partial)"
+connect-src 'self' https://<your-backend-host> https://<your-manifest-host>;
+```
+
+Use the endpoint host supplied by your Inth project or your self-hosted backend.
+When you use the same-origin rewrite from
+[Optimization](./optimization.md), `backendURL` is `/api/c15t`
+and `'self'` already covers the browser requests; the Next.js server connects to
+the backend outside the browser's CSP. A local manifest route at
+`/api/c15t/manifest` is also same-origin.
+
+IAB TCF policies can fetch the Global Vendor List from the URL the policy
+provides; allow that host in `connect-src` if you use the
+[IAB TCF add-on](./iab/overview.md). Server-side prefetch runs
+in Next.js and is not subject to the browser's CSP.
+
+## Verify
+
+Load a page with the policy enforced, not in report-only mode, and open the
+browser console. The banner should render with its theme colors and no CSP
+violation should mention `c15t-theme`. Grant a category that gates one of your
+`scripts` entries, then check:
+
+* The injected `<script>` element carries the request's nonce. Browsers hide
+  the value from `getAttribute('nonce')`; read the element's `nonce` property
+  in the console or inspect it in the Elements panel.
+* The `<style id="c15t-theme">` element carries the same nonce and the
+  `--c15t-*` variables are applied to the banner.
+* No `Refused to load the script` or `Refused to apply inline style` errors
+  mention a c15t element. A refused vendor dependency points to a missing
+  `'strict-dynamic'` or vendor host.
+* The consent submission to `/subjects` succeeds. A `connect-src` violation
+  here means the backend origin is missing.
+
+Reload with a different nonce and confirm the elements update. A stale nonce
+after a full page load usually means a cached HTML response; nonce-based pages
+must not be served from a shared cache.