@c15t/react 3.0.0-alpha.2 → 3.0.0-alpha.3

package/docs/customization/tokens.md

@@ -11,10 +11,53 @@ React, Next.js and Svelte provide `styles.css`. Import the adapter's stylesheet
 at the app's global entry point. Vue includes styles in its components; Astro
 adds styles through its integration.
 
+The stylesheet blocks rendering, so it carries only what a first paint can
+show: the default tokens, every c15t CSS variable, and the rules for the
+banner, `ConsentDialogTrigger` and the `ConsentGate` placeholder. The consent
+dialog and preference widget bring their own rules. Each rule reaches the page
+once.
+
 ```tsx
 import 'c15t/react/styles.css';
 ```
 
+| File                             | Holds                                                                  | Loaded by                                                         |
+| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `styles.css` or `styles.tw3.css` | Default tokens, all variables, banner, trigger and `ConsentGate` rules | Your app, once                                                    |
+| `@c15t/ui/styles/dialog.css`     | Dialog and preference widget rules                                     | The dialog component, with its lazy chunk                         |
+| `@c15t/ui/styles/primitives.css` | Rules for the `@c15t/ui/styles/primitives` class maps                  | Svelte's `styles.css`, or your app if it renders those class maps |
+| `iab/styles.css`                 | IAB TCF banner and dialog rules and variables                          | Your app, after `styles.css`                                      |
+
+In React, Next.js and TanStack Start, the dialog's module imports
+`@c15t/ui/styles/dialog.css`. The bundler emits it with the dialog's chunk and
+loads it before that chunk runs, so the dialog never renders unstyled. The
+chunk loads after first paint, by the time the dialog first opens. Do not
+import `dialog.css` yourself. The `@c15t/react/components/consent-dialog`,
+`/components/consent-widget`, `/primitives`, `/primitives/*` and `/iab` entry
+points import it as soon as you import them, because they render dialog parts
+outside the lazy chunk.
+
+These modules import the stylesheet through `@c15t/ui/styles/dialog`. Under
+the `node` export condition that module imports nothing, so server code that
+loads `@c15t/react` with plain Node, such as the Pages Router or an SSR build
+that keeps dependencies external, does not fail on the `.css` file. In your
+own components, import `@c15t/ui/styles/dialog` rather than the `.css` file
+if the module can run on the server.
+
+Svelte loads its dialog with the page, so `c15t/svelte/styles.css` also
+imports the dialog and primitive rules. Astro injects the banner rules; the
+React and Svelte dialog islands import the rest, and Astro links those
+stylesheets on every page, so in Astro the dialog rules still block rendering.
+Vue components import their own stylesheets.
+
+The dialog rules sit in `@layer components` and declare no variables, so
+tokens from `theme`, variables you override in your own CSS, and Tailwind 4
+utilities still win over them even though they load later. If you import
+`styles.css` into a named layer, such as `@import 'c15t/react/styles.css'
+layer(c15t)`, the dialog rules still join the top-level `components` layer.
+List `components` in your layer order statement, for example
+`@layer c15t, components, app;`, so it does not land after your own layers.
+
 The standard stylesheet places rules in `@layer components`. For Tailwind 3,
 use the `styles.tw3.css` entry instead of the standard stylesheet, between the
 components and utilities directives in your Tailwind entry:
@@ -26,6 +69,18 @@ components and utilities directives in your Tailwind entry:
 @tailwind utilities;
 ```
 
+Tailwind 3 also processes the dialog stylesheet the bundler loads, and it
+rejects a stylesheet that uses `@layer components` without its own
+`@tailwind components` directive. Add the c15t plugin before `tailwindcss` in
+your PostCSS config. It removes the layer wrapper from c15t's stylesheets so
+Tailwind 3 accepts them and its preflight does not override them:
+
+```js title="postcss.config.mjs"
+export default {
+  plugins: ['@c15t/ui/postcss-tailwind3', 'tailwindcss', 'autoprefixer'],
+};
+```
+
 Do not load both c15t stylesheet variants. For Tailwind 4 or unlayered CSS,
 inspect layer order before reaching for `!important`.
 
@@ -48,9 +103,17 @@ export const theme = defineTheme({
 });
 ```
 
-Install `@c15t/ui` if importing its theme helper directly. Pass `theme` in your
-provider options. `consentActions` selects styling by action role. A per-action
-entry overrides `primary`, which overrides `default`.
+Install `@c15t/ui` if importing its theme helper directly. The browser does
+not turn tokens into CSS. In React and Next.js, render
+`<ConsentTheme theme={theme} />` where the app renders on the server, and pass
+`theme` in your provider options for `consentActions`. Elsewhere, call
+`generateThemeCSS(theme)` from `@c15t/ui/theme` on the server or at build time
+and put the result in a `<style>` element or your stylesheet. See
+[React styling](../frameworks/react/styling/overview.md) and
+[Next.js styling](https://c15t.com/docs/frameworks/next/styling/overview).
+
+`consentActions` selects styling by action role. A per-action entry overrides
+`primary`, which overrides `default`.
 
 ## Target a prompt with CSS
 

package/docs/frameworks/react/components/consent-dialog.md

@@ -97,14 +97,44 @@ it is `dialog`. These set that surface:
 * `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
   from `useHeadlessConsentUI()` on the headless subpath.
 
-The component code is split into its own chunk. It downloads when the
-dialog first opens or when a visitor hovers or focuses a Customize button,
-and renders nothing until that chunk is ready. Passing `open={true}` or
-`showTrigger` loads it on mount.
+The component code is split into its own chunk, so it is not part of the
+first page load. It renders nothing until that chunk is ready, and the
+chunk downloads at the first of these:
+
+* The browser's first idle period after the page's `load` event, while the
+  banner is shown or a `ConsentDialogLink`, `ConsentDialogTrigger`,
+  `ConsentGate` button or other button that opens the dialog is mounted.
+  This covers a visitor who taps or presses Enter with no hover or focus
+  first. Browsers without `requestIdleCallback`, such as Safari, wait
+  200 ms after `load` instead.
+* Hover or focus on a button that opens the dialog.
+* The dialog opening.
+
+Passing `open={true}` or `showTrigger` loads it on mount. A visit with
+saved consent and nothing on the page that opens the dialog never
+downloads it.
+
+Idle loading is skipped when the visitor has Save-Data on
+(`navigator.connection.saveData`), on a `2g` or `slow-2g` connection, and
+while offline; hover and focus still load it. To load the chunk only on
+hover, focus or open, set `preloadDialog: 'intent'` in the provider
+options. The default is `'idle'`. With Next.js, pass it through
+`ConsentRoot`'s `options` prop.
+
+If a preload fails, for example because the visitor is offline, nothing is
+cached: the next hover, focus or open tries the download again.
+
+The dialog's CSS travels in the same chunk and is applied before the dialog
+renders, so your app's `styles.css` import stays small.
 
 Without an `open` prop, Escape closes the dialog. Save, Accept all and
-Reject all close it after the save succeeds; a save that fails keeps it
-open. With `open={true}`, these actions leave the dialog visible; the
+Reject all close it as soon as the choice is recorded in the browser, in
+the same task as the click; the exit animation still plays. The request to
+the backend runs afterwards and never reopens the dialog: a failed request
+keeps the choice, reports through `onError` and is retried later. See
+[when a choice is saved](../../../guides/consent-state.md#when-a-choice-is-saved)
+for the order of events. A draft that went stale because the policy changed keeps the dialog open
+for review. With `open={true}`, these actions leave the dialog visible; the
 parent must set `open={false}` to close it. Clicking the backdrop does not
 close it. Closing discards toggles that were not saved: the next open starts
 from the recorded choice again. After a save from an uncontrolled dialog,
@@ -186,6 +216,15 @@ for the stock structure are `dialog.root`, `dialog.container`,
 `dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
 `dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.
 
+`ConsentDialog` from the package root and from the
+`c15t/react/consent-dialog` subpath is the deferred component described
+under Behavior, and each `ConsentDialog.<Part>` loads with the same chunk.
+`c15t/react/components/consent-dialog` exports the dialog without the
+deferral, plus each part as a named export (`Card`, `Header`, `Overlay`,
+`Root` and the rest). Importing from that path puts the dialog's code in
+the bundle of every page that imports it, so the first open needs no
+download but every visitor downloads the dialog.
+
 The compound parts import from `c15t/react` as properties of `ConsentDialog`,
 and `ConsentWidget` from the same module. See
 [Styling](../styling/overview.md) for slots and tokens.

package/docs/frameworks/react/components/consent-gate.md

@@ -84,9 +84,11 @@ scope cannot be granted. The built-in placeholder then shows `frame.policyBlocke
 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
+server renders the placeholder for a denied category. For a granted
+category it renders the empty wrapper, and the children mount once
+hydration completes, so an iframe loads once even when the page streams
+inside a `Suspense` boundary. 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
 `ConsentGate` shows the placeholder first and swaps in the embed after resolution
@@ -142,7 +144,9 @@ 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
+category and neither placeholder nor embed for a granted category; the
+embed appears after hydration and the network panel shows one request for
+its document. 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

package/docs/frameworks/react/components/consent-manager-provider.md

@@ -35,16 +35,18 @@ subscriptions. Keep it mounted across client navigation. Its initial mode and
 prefetch configuration belong to the runtime's creation, not a per-render
 mechanism for switching visitors or backends.
 
-| Option                | Purpose                                                         |
-| --------------------- | --------------------------------------------------------------- |
-| `mode`                | Hosted, offline or custom transport factory                     |
-| `scripts`             | Consent-managed script configurations                           |
-| `callbacks`           | Choice, permission and error events                             |
-| `theme`, `components` | Theme tokens and component slot attributes                      |
-| `presentation`        | Prompt and preferences layout behavior                          |
-| `i18n`                | Languages and message overrides                                 |
-| `storageConfig`       | Browser record storage configuration                            |
-| `enabled`             | Set false only when intentionally bypassing consent enforcement |
+| Option                   | Purpose                                                                                                                               |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                   | Hosted, offline or custom transport factory                                                                                           |
+| `scripts`                | Consent-managed script configurations                                                                                                 |
+| `callbacks`              | Choice, permission and error events                                                                                                   |
+| `theme`, `components`    | Consent-action styles, theme slots and component slot attributes. Tokens render through `ConsentTheme`                                |
+| `presentation`           | Prompt and preferences layout behavior                                                                                                |
+| `preloadDialog`          | When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](./consent-dialog.md#behavior) |
+| `i18n`                   | Languages and message overrides                                                                                                       |
+| `storageConfig`          | Browser record storage configuration                                                                                                  |
+| `enabled`                | Set false only when intentionally bypassing consent enforcement                                                                       |
+| `reloadOnConsentRevoked` | Reload the page after the visitor turns off a granted category or vendor; defaults to `true`                                          |
 
 `enabled: false` grants categories and allows gated loading while suppressing
 consent UI. It is not a way to fix failed initialization or hide a banner in
@@ -58,13 +60,31 @@ signals. Hydration and notice dismissal do not become explicit choices.
 
 An externally owned runtime can be passed through `runtime`. Its owner must
 start and dispose it. A provider borrowing that runtime must not initialize or
-dispose a second copy. Keep the runtime stable for the provider's lifetime and
-unmount the borrowing provider when disposing the runtime. IAB actions taken
-before its handle is ready wait for that handle. If the provider unmounts first,
-a pending `save()` rejects with an `AbortError` instead of waiting indefinitely.
+dispose a second copy. Passing a different `runtime` moves the provider and its
+hooks to the new runtime's kernel and unsubscribes them from the previous one.
+The previous runtime keeps running until its owner disposes it. Switch the
+provider to another runtime, or unmount it, before disposing the runtime it
+renders. Changing between a borrowed runtime and a provider-created one still
+requires remounting the provider. IAB actions taken before its handle is ready
+wait for that handle. If the provider unmounts or switches runtimes first, a
+pending `save()` rejects with an `AbortError` instead of waiting indefinitely.
 See [consent state](../../../guides/consent-state.md) and
 [deployment modes](../../../guides/deployment-modes.md).
 
+## Reload after revocation
+
+Removing a script cannot stop code that already ran. A vendor's listeners,
+timers and widgets keep working until the page unloads. When an accept, reject
+or save turns off a category or vendor that was granted, the provider reloads
+the page once the save request settles, so the next page runs only permitted
+code. `onBeforeConsentRevocationReload` runs just before the reload. With a
+[`consentSource`](../../../guides/shared-consent-controls.md), any withdrawal the
+external CMP reports reloads the same way, including expiry.
+
+Otherwise, expiry, policy changes and privacy signals do not reload the page. Set
+`reloadOnConsentRevoked: false` only when every gated vendor stops itself on
+revocation, for example through its own opt-out API.
+
 ## Clear data when consent is denied
 
 Set `options.clearOnRevocation` to declare cookies, localStorage keys, and

package/docs/frameworks/react/components/consent-widget.md

@@ -93,6 +93,9 @@ styled like a category row: the vendor's name and a switch on the header,
 and its description and privacy policy link behind the card's own expand
 control. Cards start collapsed, so a long list stays one line per vendor,
 and the category list scrolls inside the dialog rather than growing it.
+A collapsed category or card renders its content element empty and mounts
+the content the first time it opens, then keeps it mounted, so a long
+vendor list costs nothing until a visitor expands its category.
 Vendor switches edit the same draft as the category
 switches and record on Save. Saving with one vendor off denies that vendor
 only; the category stays granted and its other vendors keep loading. While
@@ -191,6 +194,12 @@ Provider component slots for the stock structure are `manager.root`,
 `vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
 `vendor-list.control` and `tag.manager`.
 
+`ConsentWidget` from the package root and from the
+`c15t/react/consent-widget` subpath loads its code in a separate chunk the
+first time it renders, so a page that never renders it does not download
+it. `c15t/react/components/consent-widget` exports the widget without that
+deferral, plus each part as a named export.
+
 The compound parts import from `c15t/react` as properties of `ConsentWidget`.
 See [Styling](../styling/overview.md) for slots and tokens.
 

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

@@ -53,7 +53,14 @@ Analytics.
 Hidden optional categories do not need a choice to dismiss the banner. Their
 permissions still follow the backend policy, so hidden opt-in categories remain
 denied without a valid grant. React providers enable DOM iframe blocking and
-discovery by default; set `iframeBlocker: false` to disable it, or
+discovery by default. The blocker loads when the first iframe with
+`data-category` or `data-vendor` is on the page, so pages without one never
+download it; until it runs, such an iframe that arrives with a `src` consent
+does not allow is paused. Write gated iframes with `data-src`, not `src`. The
+browser requests a `src` as soon as the iframe is in the document, before the
+blocker can pause it, whether the iframe comes from the server HTML or a
+client render. Set
+`iframeBlocker: false` to disable it, or
 `iframeBlocker: { disableAutomaticBlocking: true }` to scan manually with
 `useIframeBlocker({ disableAutomaticBlocking: true }).processAllIframes()`.
 

package/docs/frameworks/react/hooks/{use-consent-manager/overview.md → overview.md}

@@ -51,8 +51,10 @@ This is an isolated action example, not a complete policy-aware banner. Use the
 stock UI or headless surface actions for a complete prompt. Do not call save on
 mount to persist a state derived from permissions.
 
-`useConsentManager` remains available for the combined UI API, including draft
-management. Prefer focused hooks for simple feature gates and use the headless
-UI hook when implementing a complete custom prompt. Read
-[consent state](../../../../guides/consent-state.md) before treating a callback as evidence
-of a choice.
+Use focused hooks for feature gates. For a complete custom prompt or preference
+center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
+for staged choices, inside one `ConsentDraftProvider` so the save commits the
+same draft. v3 has no `useConsentManager()`; the
+[upgrade guide](../../../upgrade-v3.md#replace-useconsentmanager) maps each of its
+fields to a hook. Read [consent state](../../../guides/consent-state.md) before
+treating a callback as evidence of a choice.

package/docs/frameworks/react/iab/overview.md

@@ -16,7 +16,9 @@ components inside an existing consent provider connected to Inth.
 
 Import the components from `c15t/react/iab` and render them inside your
 existing `ConsentProvider` from `c15t/react`. Import `c15t/react/iab/styles.css`
-at your global stylesheet entry.
+at your global stylesheet entry, after `c15t/react/styles.css`: the IAB
+stylesheet holds only the IAB rules and uses the tokens from the base
+stylesheet.
 
 ```tsx title="src/iab-consent.tsx"
 import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
@@ -51,3 +53,121 @@ Test category choices alongside vendor, purpose, legitimate-interest and special
 feature controls used by your integration. Confirm the TC String and `__tcfapi`
 reflect the saved state, and verify the vendor's actual requests. A category-only
 banner test does not establish that the IAB flow works.
+
+## Restrict how vendors use a purpose
+
+Publisher restrictions override a vendor's declared use of one purpose. Pass
+them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
+placeholders; use vendors from your list whose declarations allow each
+restriction.
+
+```tsx title="src/iab-consent.tsx"
+import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
+
+const publisherRestrictions = [
+  // Vendors 10 and 755 may not use purpose 4.
+  { purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
+  // Vendor 755 must use legitimate interest for purpose 7.
+  { purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
+];
+
+export function IABConsent({ cmpId }: { cmpId: number }) {
+  return (
+    <IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
+      <IABConsentBanner />
+      <IABConsentDialog />
+    </IABProvider>
+  );
+}
+```
+
+Each restriction type has a requirement that depends on the vendor list:
+
+| `restrictionType` | Meaning                                | Allowed when the vendor                                                         |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `0`               | Purpose not allowed on any legal basis | declares the purpose for consent or legitimate interest                         |
+| `1`               | Consent required                       | declares the purpose for legitimate interest and lists it in `flexiblePurposes` |
+| `2`               | Legitimate interest required           | declares the purpose for consent and lists it in `flexiblePurposes`             |
+
+Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
+only with consent. Restrictions also require a service-specific CMP, the
+default. Setting `isServiceSpecific: false` with restrictions is an error.
+c15t copies the restrictions when the CMP starts, so changing your array
+afterwards has no effect.
+
+c15t checks restrictions when the vendor list loads and again before each TC
+String is encoded. Unsupported restrictions include type `3`, which the spec
+reserves, a vendor or purpose missing from the list, and a vendor with two
+restriction types for one purpose. They are never dropped. Loading IAB
+settings, saving and generating a TC String all reject with a
+`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
+these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
+written and no consent is recorded. Retrying `whenReady()` does not fetch
+another vendor list. The error lasts until a new vendor list is set up: with an
+explicit `gvl` option that never happens, so saving keeps failing even if the
+kernel later holds a different list. When the CMP follows the kernel's list
+instead, a replacement list is checked again and saving works once it accepts
+the restrictions. When a replacement vendor list makes a restriction
+unsupported, c15t also clears the TC authority confirmed under the previous
+list, so gated scripts stop until the configuration is fixed. Whenever c15t
+withdraws the authority it confirmed, it also removes the TC String from the
+`euconsent-v2` cookie and localStorage entry. Because the check reads the
+current vendor list, a vendor that stops declaring a purpose or its flexibility
+makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
+together.
+
+Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
+`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
+purpose ID, then vendor ID. A stored TC String whose restrictions differ from
+the current configuration is not restored. If the visitor's stored choice is
+otherwise current, the banner opens again, as it does after a policy change,
+and closes once the visitor saves. IAB gates that depend on the TC String stay
+denied until then. c15t also removes the superseded TC String from the
+`euconsent-v2` cookie and localStorage entry, so vendors reading standard
+storage do not pick it up. An unchanged configuration restores the stored TC
+String without asking.
+When reading a string written under TCF policy version 2 or 3, c15t accepts
+type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
+writes always follow the current policy.
+
+The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
+vendor under the legal basis the restrictions leave it. A vendor whose purpose
+now requires legitimate interest gets an objection control instead of a
+consent toggle, and a prohibited purpose no longer lists the vendor. A
+purpose whose vendors all use legitimate interest has no consent switch,
+because turning one off would change nothing the vendors rely on; its
+objection control is the opt-out. Such a purpose does not decide its c15t
+category: the category follows the purposes in it that the visitor can
+consent to. Legitimate interest never grants a category on its own. If none of
+a category's purposes has a consent basis, the category needs all of them
+consented, which only Accept all does. Stack switches
+cover only the purposes some vendor processes on consent. Display-model rows
+expose this as `hasConsentBasis`. Custom preference UIs can call
+`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
+`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
+declarations. The configured restrictions are on the kernel's IAB state as
+`publisherRestrictions`.
+
+Consent-gated scripts, network rules and iframes with a `vendorId` also apply
+the confirmed restrictions for that vendor:
+
+* Type `0` blocks a target that declares the purpose in `iabPurposes` or
+  `iabLegIntPurposes`.
+* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
+  vendor consent. Legitimate interest no longer satisfies it.
+* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
+  legitimate interest. Consent no longer satisfies it.
+
+Types `1` and `2` block the target when the vendor list does not mark the
+purpose as flexible for that vendor. Targets without a `vendorId` ignore
+restrictions. A target that uses only legitimate interest once restrictions
+apply is not blocked by a refused category, since it needs no consent; its
+legitimate interest signals and the visitor's objection decide. GPC, opt-out
+directives and strict scope still block it, and the category stays refused for
+scripts that depend on it. Accept all grants the vendor signal a restriction
+moves a purpose to, including legitimate interest for a vendor that declares
+none. Legitimate interest a restriction introduces applies until the visitor
+objects: the preference centres show it as allowed, and saving without touching
+it encodes it as allowed. `introducedLegitimateInterest` from
+`@c15t/iab/headless` lists those purposes and vendors for custom preference
+UIs.

package/docs/frameworks/react/network-blocker.md

@@ -0,0 +1,146 @@
+---
+title: Block network requests
+description: Block fetch and XHR calls to third-party domains in a React app
+  until the visitor grants their consent category.
+group: frameworks
+---
+
+## Add rules to the provider
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
+list until the visitor grants their category. Use it for beacons and API
+calls that bypass script loading, such as a pixel fired by an SDK that is
+already on the page.
+
+Add `networkBlocker` to the `ConsentProvider` options from your
+[quickstart](./quickstart.md). Set the URL to the endpoint
+supplied by your Inth project.
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/react';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+const networkBlocker = {
+  rules: [
+    { id: 'google-analytics', domain: 'google-analytics.com', category: 'measurement' },
+    { id: 'meta-pixel', domain: 'facebook.com', pathIncludes: '/tr', category: 'marketing' },
+  ],
+};
+
+export function Consent({ children }: { children: ReactNode }) {
+  return (
+    <ConsentProvider options={{ mode, networkBlocker }}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+    </ConsentProvider>
+  );
+}
+```
+
+Render your app inside `ConsentProvider`. Blocking starts when it renders, so
+components outside it that send requests while rendering, or modules evaluated
+before it, are not covered. See the limits below.
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains: `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. A request is
+blocked when a matching rule's condition is not met by the visitor's
+effective permissions.
+
+`category` takes the same conditions as scripts:
+
+```ts
+{ category: 'measurement' }
+{ category: { and: ['measurement', 'marketing'] } }
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Add `vendor` to also block the request while the visitor has turned that
+vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
+instead.
+
+| Option               | Default  | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `rules`              | required | Rules described above                                        |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking              |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request |
+
+## What a blocked request looks like
+
+The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
+resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The provider holds matching requests from its first render in the browser,
+before any of its children render or run effects. That covers requests from
+child components, including their mount effects, and from effects in
+components rendered next to the provider. The blocker module itself loads
+after mount and decides each held request. Apps without `networkBlocker` do
+not download it.
+
+The standalone `useNetworkBlocker` hook works the same way from the first
+render of the component that calls it. That render patches `fetch` and
+`XMLHttpRequest`. If React throws the render away and never commits it, the
+hold ends after 10 seconds. Nothing checked consent for the requests it held,
+so they fail the way the blocker fails a blocked request: a 451 response for
+`fetch`, a failed XHR. The same happens when the component unmounts before
+the blocker loads.
+
+While consent is unknown, a matching request that would be blocked waits
+instead of failing. Consent is unknown until the policy has loaded, which is
+also when a returning visitor's stored choice takes effect. The request is
+then sent if the choice allows it and blocked otherwise. If the policy fails
+to load, optional categories stay denied and waiting requests are blocked.
+If the policy request never finishes, they keep waiting and are never sent.
+
+A synchronous XHR cannot wait. Before the blocker module has loaded, a
+matching one throws a `NetworkError` from `send()`. After that, one that
+consent does not allow yet is blocked.
+
+## What the network blocker cannot stop
+
+The blocker only sees requests made after the provider starts rendering in
+the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:
+
+* Code that runs before the provider renders: inline scripts in the HTML,
+  third-party tags in `<head>`, scripts loaded before hydration (such as
+  `next/script` with `beforeInteractive`), and client modules that evaluate
+  earlier. Webpack builds evaluate a route's client component modules when
+  its chunk loads, so their top-level code runs first. Turbopack evaluates a
+  client component module when its first element renders, which inside the
+  provider is after blocking starts.
+* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
+  provider rendered.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` or `<iframe>` elements, web workers and service
+  workers.
+* With the standalone `useNetworkBlocker` hook instead of the provider
+  option, requests sent before the component that calls it renders.
+  Blocking starts in that component's first render, not the provider's.
+
+Keep tracking calls out of that window:
+
+* Send them from an effect or an event handler, never at module top level.
+* Load vendor SDKs through `scripts` instead of a `<script>` tag or
+  `next/script`, so they wait for consent before they run at all.
+* Check `useConsent('measurement')` (or the category you need) before you
+  call a vendor from your own code, and treat the blocker as a backstop.
+
+## Verify
+
+Open the browser's network panel, clear site data and reload. Requests
+matching a rule should not appear until you grant their category; with
+logging on, the console lists each blocked request. Reject, reload, and
+check that they still do not appear. The
+[verification guide](../../guides/verify-consent.md) covers automated checks.

package/docs/frameworks/react/script-loader.md

@@ -61,3 +61,9 @@ already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
 declared data when its category is denied. See
 [clear on revocation](../../integrations/clear-on-revocation.md) for configuration
 and browser limits.
+
+## Shared lifecycle controls
+
+See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
+preference delegation, withdrawal reloads, and application events. These controls
+use the same core runtime across frameworks.