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

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

@@ -93,18 +93,48 @@ it is `dialog`. These set that surface:
 * The Customize button on a `ConsentBanner`, and the "Manage preferences"
   or "Do not sell or share my data" button a notice renders.
 * `ConsentDialogLink` and `ConsentDialogTrigger`.
-* The button in a `Frame` placeholder.
+* The button in a `ConsentGate` placeholder.
 * `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/{frame.md → consent-gate.md}

@@ -1,14 +1,14 @@
 ---
-title: Frame
-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.
+title: ConsentGate
+description: Gate a YouTube or map iframe behind consent with ConsentGate in
+  React, showing a placeholder that opens the preference center until the
+  category is allowed.
 group: frameworks
 ---
 
 ## Gate an embed behind consent
 
-`Frame` mounts its children only while the effective permission for one
+`ConsentGate` 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
@@ -16,11 +16,11 @@ load. Render it anywhere inside the `ConsentProvider` from your
 placeholder button opens.
 
 ```tsx title="src/product-video.tsx"
-import { Frame } from 'c15t/react';
+import { ConsentGate } from 'c15t/react';
 
 export function ProductVideo() {
   return (
-    <Frame category="marketing" className="video-frame">
+    <ConsentGate category="marketing" className="video-frame">
       <iframe
         src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
         title="Product tour"
@@ -28,18 +28,18 @@ export function ProductVideo() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
 `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
+there too so the preference center can display and save it. `ConsentGate` 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
+on `ConsentGate` to reserve the embed's space, so the page does not shift when the
 placeholder is replaced.
 
 ## Props
@@ -51,22 +51,22 @@ placeholder is replaced.
 | `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
+wrapper element that stays in the page in both states. `ConsentGateProps` 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
+`ConsentGate` 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
+so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
+children unmount and the embed disappears. `ConsentGate` does not depend on the
 network blocker or the iframe blocker modules; use those for markup you
 cannot wrap in a component.
 
@@ -84,18 +84,20 @@ 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
-`Frame` shows the placeholder first and swaps in the embed after resolution
+`ConsentGate` 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
+`ConsentGate` 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
+configuration with sizing, titles and the same `ConsentGate` usage across
 frameworks.
 
 To read the same permission in your own components, use `useConsent` from
@@ -104,24 +106,24 @@ 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
+The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
+`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
+behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
 translated text; pass children to either to replace it.
 
 ```tsx
-<Frame
+<ConsentGate
   category="marketing"
   placeholder={
-    <Frame.Root>
-      <Frame.Title category="marketing" />
+    <ConsentGate.Root>
+      <ConsentGate.Title category="marketing" />
       <p>The video is also available on our channel.</p>
-      <Frame.Button category="marketing">Choose cookies</Frame.Button>
-    </Frame.Root>
+      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
+    </ConsentGate.Root>
   }
 >
   <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
-</Frame>
+</ConsentGate>
 ```
 
 The built-in placeholder carries `data-testid="frame-placeholder"` and its
@@ -131,7 +133,7 @@ button `data-testid="frame-open-dialog"`.
 
 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
+transcript, address or link outside the `ConsentGate` 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.
 
@@ -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,9 +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. See [consent state](../../../guides/consent-state.md) and
+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

@@ -85,6 +85,31 @@ Privacy Control overrides shows a note under its row: "Your saved choice is
 restricted by the current privacy settings." The switch still reflects the
 saved value; the effective permission is off.
 
+### Vendors
+
+When the provider declares `vendors`, each category's expanded description
+ends with one card per vendor whose category condition names that category,
+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
+the category is off in the draft the vendor switches are disabled, with the
+hint "Turn on this category to choose vendors." A vendor declared
+`disabled`, or one that only falls under `necessary`, is listed without a
+switch. Accept all and Reject all clear every vendor denial, including one
+staged but not yet saved. Under an `iab` policy no vendor rows render.
+Vendors that are only referenced by a script slug, without a name and
+privacy policy URL, still gate loading but are not listed, and so does a
+vendor whose condition negates a category, since no category row can
+host it. See
+[granular consent](../../../integrations/granular-consent.md).
+
 ### Actions
 
 The preference center always renders Reject all, Accept all and Save, with
@@ -102,8 +127,12 @@ such as `['disclosure']`, renders the widget and Save completes without
 writing a consent record.
 
 For a fully custom preference center, `useConsentDraft()` returns the same
-draft: `values`, `displayedCategories`, `isDirty`, `isStale`, `set`,
-`update`, `acceptAll`, `rejectAll`, `save` and `reset`.
+draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
+`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
+A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
+that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
+`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
+the declared list, the recorded denials and one vendor's effective result.
 
 `useConsentDraft` and `ConsentDraftProvider` import from `c15t/react`.
 
@@ -112,7 +141,10 @@ draft: `values`, `displayedCategories`, `isDirty`, `isStale`, `set`,
 Each row is a disclosure: a button that expands the category description
 and a switch beside it, so a visitor can read the description without
 changing the choice. Each switch has the category title as its accessible
-name. The policy-change alert uses `role="alert"`, and a restriction note is
+name. A category's vendor cards sit in a `region` named "Vendors" with the
+count; each card's expand button carries `aria-expanded`, each vendor
+switch is named "Allow" followed by the vendor name, and is described by
+the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
 an `output` element linked to its switch through `aria-describedby`. The
 root's `dir` attribute follows the active language.
 
@@ -122,7 +154,8 @@ Every part is available as `ConsentWidget.<Part>`. `Root` provides the
 draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
 and `AccordionItems` render the stock rows; `AccordionItem`,
 `AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
-`AccordionArrow` and `Switch` build your own. `PolicyActions` renders the
+`AccordionArrow` and `Switch` build your own; `VendorList` renders one
+category's vendor rows and takes a `category` prop. `PolicyActions` renders the
 resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
 to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
 `CustomizeButton` are the individual buttons.
@@ -155,8 +188,17 @@ export function PreferenceCenter() {
 Provider component slots for the stock structure are `manager.root`,
 `manager.footer`, `manager.actionGroup`, `accordion.root`,
 `accordion.triggerRow`, `accordion.title`, `accordion.control`,
-`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`
-and `tag.manager`.
+`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
+`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
+`vendor-list.item`, `vendor-list.header`,
+`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

@@ -17,8 +17,23 @@ group: frameworks
 
 `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.
+purpose.
+
+c15t discovers categories from registered scripts, network rules, React `ConsentGate`
+components, and iframes with `data-category` handled by the iframe blocker.
+The browser client also discovers inert scripts tagged with `data-c15t-category`.
+Compound script and network conditions contribute every category they reference.
+
+Discovered categories are added to `consentCategories`, when supplied. The dialog
+always includes Necessary and offers the optional categories in that combined
+set that are also in the resolved policy scope. Choice completion uses the same
+set. If neither configuration nor integrations supply categories, the dialog
+uses the full policy scope.
+
+Categories discovered later are added immediately and retained until the provider
+or runtime is recreated. Adding a category can require a new choice; removing a
+script or unmounting a frame does not remove its category or erase consent.
+Discovery does not grant consent or change backend permission restrictions.
 
 ## Respect policy scope
 
@@ -28,6 +43,27 @@ 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.
 
+For example, a backend rule with `categories: ['necessary']` and scripts assigned
+to `marketing` and `measurement` displays Necessary, Marketing, and Analytics,
+even without `consentCategories`. Accept All records both optional choices and
+keeps the banner dismissed after reload. An explicit list of
+`['necessary', 'measurement']` with no other integrations displays Necessary and
+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. 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()`.
+
 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/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.