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

package/docs/customization/tokens.md

@@ -1,88 +1,22 @@
 ---
-title: Theme tokens and CSS
-description: Style c15t with semantic tokens and use the stylesheet that matches
-  your CSS tooling.
+title: Theme tokens
+description: Change c15t's colors, type, radius, spacing, shadows and motion
+  with theme tokens, and see every --c15t-* variable with its default.
 group: customization
 ---
 
-## Load the stock stylesheet once
+## Where tokens come from
 
-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:
-
-```css
-@tailwind base;
-@tailwind components;
-@import 'c15t/react/styles.tw3.css';
-@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`.
+c15t's components take their colors from `--c15t-*` CSS variables, and most
+of their fonts, radii, spacing, shadows and motion too. c15t's stylesheet sets
+the defaults. You change them with a theme object or with CSS, and every part
+that reads a token changes with it. Some values are still fixed for one
+component, such as button padding, the radius of the "Secured by" tag and
+several font sizes and weights, so a token change does not move them. Restyle
+those parts through [slots](./slots.md) or your own CSS.
+[Stylesheets and CSS layers](./stylesheets.md)
+covers which stylesheet to load, and [dark mode](./dark-mode.md)
+covers the dark set of tokens.
 
 ## Set semantic values together
 
@@ -94,27 +28,117 @@ readable in each state.
 import { defineTheme } from '@c15t/ui/theme';
 
 export const theme = defineTheme({
-  colors: { primary: '#2f6f4e' },
-  radius: { lg: '4px' },
-  consentActions: {
-    primary: { variant: 'primary', mode: 'filled' },
-    dismiss: { variant: 'neutral', mode: 'stroke' },
-  },
+	colors: { primary: '#2f6f4e' },
+	radius: { lg: '4px' },
+	consentActions: {
+		primary: { variant: 'primary', mode: 'filled' },
+		dismiss: { variant: 'neutral', mode: 'stroke' },
+	},
 });
 ```
 
-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).
+Install `@c15t/ui` if importing its theme helper directly. Where the theme
+goes depends on the framework:
+
+| Framework                      | Tokens                                                                                                                            | `consentActions`                    |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| Next.js, TanStack Start, React | `<ConsentTheme theme={theme} />`, rendered on the server where the app has one                                                    | `theme` in the provider options     |
+| Nuxt, Vue                      | `theme` or `tokens` in the module or plugin options                                                                               | Not available                       |
+| Astro                          | `theme` in the integration options                                                                                                | The same `theme`                    |
+| Svelte, SvelteKit              | `generateThemeCSS(theme)` from `@c15t/ui/theme` on the server, in a `<style>` element, or `--c15t-*` variables in your stylesheet | `theme` on `ConsentManagerProvider` |
+| HTML, JavaScript               | `ui.theme`                                                                                                                        | Not available                       |
+
+React and Svelte providers do not turn tokens in their `theme` option into
+CSS, and warn in development when a theme holds tokens but the page has no
+`<style id="c15t-theme">`. Your framework's customize page shows the full
+setup.
 
 `consentActions` selects styling by action role. A per-action entry overrides
 `primary`, which overrides `default`.
 
+## Combine a generated theme with your own CSS
+
+`generateThemeCSS` writes its variables on `:root:root` and
+`.c15t-theme-root.c15t-theme-root`, one step more specific than the defaults
+in `styles.css`. The theme therefore overrides the defaults whether its
+`<style>` element comes before or after the stylesheet. The same output backs
+`ConsentTheme` in React, Next.js and TanStack Start, Astro's `theme` option and
+the script tag's `ui.theme`.
+
+A `--c15t-*` variable you set on plain `:root` in your own CSS loses to a
+generated theme that sets the same variable, even when your rule loads later.
+Put the value in the theme, or raise your selector:
+
+```css
+:root:root {
+  --c15t-primary: #2f6f4e;
+}
+```
+
+Scoped rules such as `[data-prompt] { --c15t-primary: ... }` set the variable
+on the banner element itself, so they still apply inside it.
+
+## Every token
+
+Every framework uses the same tokens. A theme object, such as `ConsentTheme`'s
+`theme`, Astro's and Vue's `theme` or the script tag's `ui.theme`, takes the
+theme key, such as `radius.lg`. Vue and Nuxt `tokens` take the CSS variable
+name without the leading `--`, such as `c15t-radius-lg`. A stylesheet sets the
+CSS variable itself. Your framework's customize page shows where each one goes.
+[Motion and animation](./motion.md) explains the duration and
+easing tokens.
+
+| CSS variable                  | Theme key                        | Default                                         |
+| ----------------------------- | -------------------------------- | ----------------------------------------------- |
+| `--c15t-primary`              | `colors.primary`                 | `hsl(228, 100%, 60%)`                           |
+| `--c15t-primary-hover`        | `colors.primaryHover`            | `hsl(228, 100%, 55%)`                           |
+| `--c15t-surface`              | `colors.surface`                 | `hsl(0, 0%, 100%)`                              |
+| `--c15t-surface-hover`        | `colors.surfaceHover`            | `hsl(0, 0%, 98%)`                               |
+| `--c15t-border`               | `colors.border`                  | `hsl(0, 0%, 90%)`                               |
+| `--c15t-border-hover`         | `colors.borderHover`             | `hsl(0, 0%, 85%)`                               |
+| `--c15t-text`                 | `colors.text`                    | `hsl(0, 0%, 10%)`                               |
+| `--c15t-text-muted`           | `colors.textMuted`               | `hsl(0, 0%, 40%)`                               |
+| `--c15t-text-on-primary`      | `colors.textOnPrimary`           | auto-derived from `colors.primary` when omitted |
+| `--c15t-overlay`              | `colors.overlay`                 | `hsla(0, 0%, 0%, 0.5)`                          |
+| `--c15t-switch-track`         | `colors.switchTrack`             | `hsl(0, 0%, 85%)`                               |
+| `--c15t-switch-track-active`  | `colors.switchTrackActive`       | `hsl(228, 100%, 60%)`                           |
+| `--c15t-switch-thumb`         | `colors.switchThumb`             | `hsl(0, 0%, 100%)`                              |
+| `--c15t-font-family`          | `typography.fontFamily`          | `system-ui, -apple-system, sans-serif`          |
+| `--c15t-font-size-sm`         | `typography.fontSize.sm`         | `0.875rem`                                      |
+| `--c15t-font-size-base`       | `typography.fontSize.base`       | `1rem`                                          |
+| `--c15t-font-size-lg`         | `typography.fontSize.lg`         | `1.125rem`                                      |
+| `--c15t-font-weight-normal`   | `typography.fontWeight.normal`   | `400`                                           |
+| `--c15t-font-weight-medium`   | `typography.fontWeight.medium`   | `500`                                           |
+| `--c15t-font-weight-semibold` | `typography.fontWeight.semibold` | `600`                                           |
+| `--c15t-line-height-tight`    | `typography.lineHeight.tight`    | `1.25`                                          |
+| `--c15t-line-height-normal`   | `typography.lineHeight.normal`   | `1.5`                                           |
+| `--c15t-line-height-relaxed`  | `typography.lineHeight.relaxed`  | `1.75`                                          |
+| `--c15t-space-xs`             | `spacing.xs`                     | `0.25rem`                                       |
+| `--c15t-space-sm`             | `spacing.sm`                     | `0.5rem`                                        |
+| `--c15t-space-md`             | `spacing.md`                     | `1rem`                                          |
+| `--c15t-space-lg`             | `spacing.lg`                     | `1.5rem`                                        |
+| `--c15t-space-xl`             | `spacing.xl`                     | `2rem`                                          |
+| `--c15t-radius-sm`            | `radius.sm`                      | `0.25rem`                                       |
+| `--c15t-radius-md`            | `radius.md`                      | `0.5rem`                                        |
+| `--c15t-radius-lg`            | `radius.lg`                      | `0.75rem`                                       |
+| `--c15t-radius-full`          | `radius.full`                    | `9999px`                                        |
+| `--c15t-shadow-sm`            | `shadows.sm`                     | `0 1px 2px hsla(0, 0%, 0%, 0.05)`               |
+| `--c15t-shadow-md`            | `shadows.md`                     | `0 4px 12px hsla(0, 0%, 0%, 0.08)`              |
+| `--c15t-shadow-lg`            | `shadows.lg`                     | `0 8px 24px hsla(0, 0%, 0%, 0.12)`              |
+| `--c15t-duration-fast`        | `motion.duration.fast`           | `80ms`                                          |
+| `--c15t-duration-normal`      | `motion.duration.normal`         | `150ms`                                         |
+| `--c15t-duration-slow`        | `motion.duration.slow`           | `200ms`                                         |
+| `--c15t-easing`               | `motion.easing`                  | `cubic-bezier(0.4, 0, 0.2, 1)`                  |
+| `--c15t-easing-out`           | `motion.easingOut`               | `cubic-bezier(0.215, 0.61, 0.355, 1)`           |
+| `--c15t-easing-in-out`        | `motion.easingInOut`             | `cubic-bezier(0.645, 0.045, 0.355, 1)`          |
+| `--c15t-easing-spring`        | `motion.easingSpring`            | `cubic-bezier(0.34, 1.56, 0.64, 1)`             |
+
+The radius tokens round different parts. `radius.lg` rounds the banner card,
+the preference dialog, `ConsentGate` placeholders and the floating trigger.
+`radius.md` rounds buttons, accordions, tabs and the vendor list.
+`radius.sm` rounds small parts inside the banner and dialog. To give the banner
+and its buttons the same 4px corners, set both `lg` and `md`.
+
 ## Target a prompt with CSS
 
 ```css
@@ -126,8 +150,9 @@ and put the result in a `<style>` element or your stylesheet. See
 ```
 
 Use attributes exposed by the rendered component, not guessed class names.
-Test the prompt and the preferences dialog separately because tokens scoped to
-one prompt do not automatically reach a portaled dialog.
+The script tag's banner has no `data-prompt` or `data-model`. Test the prompt
+and the preferences dialog separately because tokens scoped to one prompt do
+not automatically reach a portaled dialog.
 
 | Size variable                       | Default | Target        |
 | ----------------------------------- | ------- | ------------- |
@@ -135,5 +160,47 @@ one prompt do not automatically reach a portaled dialog.
 | `--consent-banner-widget-max-width` | `20rem` | Widget        |
 | `--consent-banner-wall-max-width`   | `30rem` | Choice wall   |
 
+The banner footer lays out its actions by the card's width, not the
+viewport's. With the default `compact` profile, a card narrower than 22rem
+puts Reject and Accept on one row and Customize on a full-width row below
+them, on any screen size.
+
 Test long translations and small screens after changing width or typography.
 A compact banner must still fit the required actions.
+
+## Restyle the "Secured by" tag
+
+The tag sits on the edge of the banner and dialog cards and uses the primary
+color by default. Set these variables on `:root`, or on an element that
+contains the tag. The dialog renders in a portal, so a variable set on the
+banner does not reach the dialog's tag.
+
+| Variable                                     | Default                                 | Target                                 |
+| -------------------------------------------- | --------------------------------------- | -------------------------------------- |
+| `--consent-branding-tag-background-color`    | `var(--c15t-primary)`                   | Tag background                         |
+| `--consent-branding-tag-border-color`        | `--c15t-primary` mixed 14% toward black | Tag border                             |
+| `--consent-branding-tag-text-color`          | `var(--c15t-text-on-primary, #fff)`     | "Secured by" and the wordmark          |
+| `--consent-branding-tag-mark-color`          | The text color                          | c15t mark or inth logo                 |
+| `--consent-branding-tag-shadow`              | Inset highlight and a 1px drop shadow   | Tag shadow                             |
+| `--consent-branding-tag-attached-edge-width` | `0px`                                   | Border on the edge that meets the card |
+
+The stylesheet does not declare these variables. Each default resolves on the
+tag, so a `--c15t-primary` you scope to a banner still colors the tag.
+
+This makes the tag look like a tab of the card:
+
+```css
+:root {
+  --consent-branding-tag-background-color: var(--c15t-surface);
+  --consent-branding-tag-border-color: var(--c15t-border);
+  --consent-branding-tag-text-color: var(--c15t-text-muted);
+  --consent-branding-tag-mark-color: var(--c15t-primary);
+  --consent-branding-tag-shadow: none;
+}
+```
+
+The edge that meets the card has no border by default. Above the banner the
+tag overlaps the card's top border by 1px and covers it. Below the dialog the
+tag starts under the card's bottom border. Set
+`--consent-branding-tag-attached-edge-width: 1px` to draw that edge. It is
+drawn over the card's border, so the two borders do not stack.

package/docs/customization/translations.md

@@ -27,9 +27,25 @@ i18n: {
 
 Supply the same message keys in each supported locale. A one-off component prop
 such as `dismissButtonText` is useful for one banner; use translations for a
-site-wide change. Astro's serializable integration options and Vue's module
-configuration have their own types, so verify those shapes before copying a
-React object.
+site-wide change. Astro's serializable integration options have their own
+types, so verify that shape before copying a React object. The Vue plugin and
+Nuxt module have no `i18n` option; their copy comes from the backend.
+
+## Combine messages with backend copy
+
+With a backend or a manifest, the copy it sends for the visitor's language is
+the base. Your `i18n.messages` for that language replace it key by key, and
+keys you leave out keep the backend's wording, including copy edited in your
+Inth project. c15t looks up messages for the exact language first, then for
+its primary language, so `de-AT` uses your `de` messages when there is no
+`de-AT` entry. Messages for other languages are not applied.
+
+A key only overrides the backend when your text differs from c15t's built-in
+wording for that language. So passing the stock bundles from
+`@c15t/translations/all` to enable languages keeps backend edits visible,
+while a key you actually reworded stays pinned in code. Core bundles only
+English; for other languages, import `@c15t/translations/all` so c15t can
+recognize its stock wording.
 
 ## Write labels that describe the action
 
@@ -41,6 +57,47 @@ The notice acknowledgement uses `common.acknowledge`, with `common.dismiss` as
 a fallback for older translation bundles. Keep the displayed label and the
 command's effect aligned.
 
+## Translate the ConsentGate placeholder
+
+The `ConsentGate` placeholder reads the `consentGate` section:
+
+| Key                         | Where it shows                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `consentGate.title`         | The placeholder text. `{category}` is replaced by the category's translated title.                                  |
+| `consentGate.actionButton`  | The button that opens preferences, with the same `{category}` replacement.                                          |
+| `consentGate.policyBlocked` | React and Vue show it in place of the title, with no button, when a strict policy leaves the category out of scope. |
+
+Earlier versions called this section `frame`. Copy under `frame` in
+`i18n.messages` or custom translations still applies. c15t reads it as `consentGate`, a key set under `consentGate`
+wins over the same key under `frame`, and c15t logs a warning once outside
+production. Rename the section to `consentGate` to remove the warning.
+
+## Show right-to-left languages
+
+c15t sets `dir="rtl"` on its surfaces when the resolved language is Arabic,
+Hebrew, Persian, Urdu, Pashto, Sindhi, Kurdish or Dhivehi. It matches the
+primary language, so `ar-EG` counts as Arabic. Hebrew is the only
+right-to-left translation c15t ships. For the others, supply your own
+messages or the copy from your Inth project.
+
+What follows the direction:
+
+* Text, headings and the button row in the banner, the preference dialog and
+  the preference widget flow right to left.
+* A floating or widget banner in its default corner moves to the mirrored
+  corner, so `bottom-left` becomes `bottom-right`. A `position` you set
+  yourself stays where you put it.
+* The HTML script tag, `@c15t/browser` and Astro's banner also set `lang` on
+  their surfaces. React, Vue and Svelte set `dir` only, so set `lang` on
+  `<html>` yourself.
+
+What does not follow yet:
+
+* The IAB TCF dialog aligns several labels, indents and borders to the left.
+* The floating `ConsentDialogTrigger` keeps the corner you give it.
+
+Test right-to-left pages with a real translation before you ship them.
+
 ## Test more than English
 
 Try the longest labels you support at a narrow width, with browser zoom and

package/docs/frameworks/react/callbacks.md

@@ -0,0 +1,118 @@
+---
+title: Callbacks
+description: Run code in a React app when a visitor records a consent choice,
+  when permissions change, when a request fails and before the revocation
+  reload, with the ConsentProvider callbacks option.
+group: frameworks
+---
+
+## Pass callbacks to the provider
+
+Keep the callbacks in their own module:
+
+```ts title="src/consent-callbacks.ts"
+import type { ConsentProviderCallbacks } from 'c15t/react';
+
+export const callbacks = {
+	// Right before the page reloads because a save withdrew a permission.
+	onBeforeConsentRevocationReload: ({ preferences }) => {
+		console.info('Reloading with', preferences);
+	},
+	// The visitor clicked Accept all, Reject all or Save.
+	onChoiceRecorded: ({ confirmed, snapshot }) => {
+		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
+	},
+	// A consent command failed, such as a save the backend rejected.
+	onError: ({ error }) => {
+		console.error('c15t', error);
+	},
+	// Permissions changed for any reason: a choice, an expired choice, a new
+	// policy or a privacy signal.
+	onPermissionsChanged: ({ previous, snapshot }) => {
+		console.info('Permissions', previous, snapshot.effectivePermissions);
+	},
+} satisfies ConsentProviderCallbacks;
+```
+
+Pass them in the `ConsentProvider` options, in the file that renders the
+provider, such as `src/consent.tsx` from the
+[quickstart](./quickstart.md):
+
+```tsx title="src/consent.tsx"
+<ConsentProvider options={{ mode, scripts, callbacks }}>
+```
+
+The provider subscribes the callbacks after it mounts, so they run in the
+browser. If you render on the server, server rendering never calls them. The
+provider calls the latest `callbacks` object it received, so a new object on
+a later render takes effect without a remount. Defining the object at module
+level, as above, keeps it the same across renders.
+
+When you pass your own `runtime` to `ConsentProvider`, the provider does not
+wire `callbacks` or `reloadOnConsentRevoked` from its options. Pass them to
+`createConsentRuntime` instead.
+
+## Available callbacks
+
+| Callback                          | Runs when                                                                                                   | Receives                                                                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `onChoiceRecorded`                | The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useSaveConsents()`. | `snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time as a millisecond timestamp |
+| `onPermissionsChanged`            | Any effective permission changes value.                                                                     | `snapshot`, the state after the change; `previous`, the permissions before it                                                             |
+| `onError`                         | A consent command fails, such as a failed `/init` request or a save the backend rejects.                    | `error`, a message string                                                                                                                 |
+| `onBeforeConsentRevocationReload` | A save withdrew a granted category or vendor, right before c15t reloads the page.                           | `preferences`, the permissions after the save                                                                                             |
+
+The type for the whole object is `ConsentProviderCallbacks` from `c15t/react`.
+Callbacks run after c15t updates its state, so `snapshot` and hooks such as
+`useConsent()` already hold the new values.
+
+## onChoiceRecorded or onPermissionsChanged
+
+`onChoiceRecorded` runs only for a visitor's action. `onPermissionsChanged`
+runs whenever effective permissions change, whatever the cause:
+
+| Event                                                     | `onChoiceRecorded` | `onPermissionsChanged`       |
+| --------------------------------------------------------- | ------------------ | ---------------------------- |
+| Visitor accepts, rejects or saves                         | Yes                | Yes, if a permission changed |
+| A policy resolves and allows categories before any choice | No                 | Yes                          |
+| Global Privacy Control turns off a grant                  | No                 | Yes                          |
+| A recorded choice expires                                 | No                 | Yes                          |
+| Visitor dismisses a notice                                | No                 | No                           |
+
+Use `onChoiceRecorded` for consent analytics and audit trails, because it
+fires only when the visitor chose. Use `onPermissionsChanged` to start or stop
+your own code. Never treat it as proof that the visitor agreed to anything,
+and never save consent from it.
+[How consent works](../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice)
+explains the difference.
+
+Dismissing a notice records no choice and changes no permission. Read it with
+`useNoticeDismissal()` instead. For consent inside one component, use the
+[hooks](./hooks.md), which re-render the component when
+consent changes.
+
+## Before a revocation reload
+
+Removing a script tag cannot stop code that already ran, so c15t reloads the
+page after an accept, reject or save turns off a category or vendor that was
+granted. The reload waits for the save request to finish. Right before it,
+`onBeforeConsentRevocationReload` runs synchronously. Use it to call a
+vendor's shutdown API or flush queued events. Keep it short, because the
+reload does not wait for promises.
+
+A choice that expires, a new policy and a privacy signal change permissions
+without a visitor action, so they do not reload the page.
+
+To handle revocation yourself, set `reloadOnConsentRevoked: false` in the
+provider options. Code the visitor turned off then keeps running until the
+next full page load, and `onBeforeConsentRevocationReload` never runs.
+
+## Verify
+
+1. Add the callbacks from this page, open the console and DevTools Network,
+   clear site data and reload under a policy that shows a banner.
+2. Click **Accept All**. `onChoiceRecorded` and `onPermissionsChanged` both log,
+   and the save request to your backend appears in Network.
+3. Reload. `onChoiceRecorded` does not log again.
+4. Open Privacy settings, turn off a category you allowed and save.
+   `onBeforeConsentRevocationReload` logs, then the page reloads. After the
+   reload, that category's vendor requests are absent from Network.

package/docs/frameworks/react/clear-on-revocation.md

@@ -0,0 +1,106 @@
+---
+title: Clear on revocation
+description: Delete the first-party cookies and Web Storage keys a consent
+  category owns in a React app when that category is denied, with the
+  clearOnRevocation option on ConsentProvider.
+group: frameworks
+---
+
+## Configure cleanup
+
+Gating stops new requests, but it leaves the cookies and storage keys a vendor
+already wrote. List the ones each optional category owns and add them to the
+provider options in `src/consent.tsx`. When that category is denied, c15t
+deletes them:
+
+```tsx title="src/consent.tsx (partial)"
+import type { ClearOnRevocationConfig } from 'c15t';
+
+const clearOnRevocation: ClearOnRevocationConfig = {
+  measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
+  marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
+};
+
+<ConsentProvider options={{ mode, scripts, clearOnRevocation }}>
+```
+
+The provider reads `clearOnRevocation` once, when it mounts; remount it to
+change the list. A provider that borrows a `runtime` does not read it.
+Configure cleanup on the runtime owner instead, with
+`createConsentRuntime({ clearOnRevocation })`.
+
+## Name cookies and keys
+
+Each optional category takes three lists. Without `clearOnRevocation`, c15t
+deletes nothing, and `necessary` cannot be configured.
+
+| Field            | Takes                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ |
+| `cookies`        | Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects. |
+| `localStorage`   | Keys, or prefixes ending in `*`.                                                                             |
+| `sessionStorage` | Keys, or prefixes ending in `*`.                                                                             |
+
+Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
+but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
+and a bare `*` are not supported. Cookie names are matched as written,
+without URL decoding.
+
+By default c15t tries the current host and its parent domains, and the
+current path and its parents. For a cookie set on a specific scope, use an
+object:
+
+```ts
+const cookies = [
+  { name: 'analytics-id', domain: 'example.com', path: '/' },
+  { name: 'checkout-metrics', domain: '', path: '/checkout' },
+  { name: 'partitioned-metrics', partitioned: true },
+];
+```
+
+An empty `domain` means a host-only cookie. A `domain` or `path` you set
+replaces the automatic attempts for that field. Partitioned cookies need
+`partitioned: true`. A prefix only finds cookies the current page can read,
+so use an exact name for a cookie on another path.
+
+c15t never deletes its own consent records, even when a pattern matches
+them.
+
+## When cleanup runs
+
+* On the first page load after the policy resolves, for every denied
+  category. This covers a new opt-in visitor and a returning visitor whose
+  choice expired.
+* Whenever a category changes from allowed to denied, after a saved refusal,
+  expiry, a policy change or a Global Privacy Control signal.
+
+Cleanup does not run during server rendering, while the policy is still
+loading, on draft switch changes in the dialog, or when the provider
+unmounts. It runs once per change and does not poll. Under an opt-out
+policy, an expired choice that stays allowed deletes nothing. If a resolved
+policy later falls back to denial after a failed request, cleanup deletes
+the data, and a successful retry cannot restore it.
+
+Switching off one vendor inside an allowed category deletes nothing, because
+the category stays allowed.
+
+## Browser limits
+
+c15t can delete first-party cookies that JavaScript can read, and keys in
+the current origin's `localStorage` and `sessionStorage`. It cannot delete
+`HttpOnly` cookies or another origin's data; expire those from your server.
+A vendor SDK still running on the page can write its cookies again, which is
+one reason c15t reloads the page after a revocation. Deletion failures do
+not block the consent update. See
+[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
+
+## Verify cleanup
+
+1. Allow measurement and let Google Analytics run. In DevTools Application,
+   Cookies shows `_ga` and a `_ga_<id>` cookie.
+2. Open Privacy settings, turn measurement off and save. c15t reloads the
+   page. Both cookies are gone, and `analytics:*` keys are gone from Local
+   storage.
+3. Reload. The cookies do not come back, because Google Analytics no longer
+   loads.
+4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
+   and check that the cookie is gone from that scope too.