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

package/docs/customization/tokens.md

@@ -1,33 +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.
-
-```tsx
-import 'c15t/react/styles.css';
-```
-
-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;
-```
-
-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
 
@@ -39,18 +28,116 @@ 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. 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. 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
 
@@ -63,8 +150,9 @@ entry overrides `primary`, which overrides `default`.
 ```
 
 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        |
 | ----------------------------------- | ------- | ------------- |
@@ -72,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,48 @@ 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`, custom translations or an older backend's `/init` response
+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.

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

@@ -1,26 +1,42 @@
 ---
 title: ConsentBanner
-description: Pre-built consent banner shown when consent is required.
+description: Render the c15t consent banner in a React app, choose its variant
+  and position, and compose its parts.
 group: frameworks
 ---
 
-## Usage
-
-```tsx
-import { ConsentBanner, ConsentDialog, ConsentProvider, offline } from 'c15t/react';
-import { policyRulePresets } from '@c15t/schema';
-
-const mode = offline({ policyRules: [policyRulePresets.europeOptIn()] });
-
-export function Consent({ children }: { children: React.ReactNode }) {
-	return (
-		<ConsentProvider options={{ mode }}>
-			{children}
-			<ConsentBanner />
-			<ConsentDialog />
-		</ConsentProvider>
-	);
-}
+## Render the banner inside `ConsentProvider`
+
+Render `ConsentBanner` once inside `ConsentProvider`, next to `ConsentDialog`.
+The [quickstart](../quickstart.md) mounts both in
+`src/consent.tsx`:
+
+```tsx title="src/consent.tsx"
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
+} from 'c15t/react';
+import type { ReactNode } from 'react';
+
+import { scripts } from './scripts';
+
+import 'c15t/react/styles.css';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={{ mode, scripts }}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
 ```
 
 The banner renders whatever the active policy rule requires. It reads the rule
@@ -122,16 +138,14 @@ button through the provider's theme:
 ```ts
 const theme = {
 	colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
-	consentActions: {
-		primary: { variant: 'primary', mode: 'filled' },
-	},
+	consentActions: { primary: { variant: 'primary', mode: 'filled' } },
 } as const;
 ```
 
 Pass `theme` in `ConsentProvider` options. Per-action theme overrides such
 as `consentActions.dismiss` take precedence over this primary style.
-See [Styling](../styling/overview.md) for tokens and slots, and
-[Policy presets](../concepts/policy-presets.md) for the rule IDs and coverage.
+See [customize](../customize.md) for tokens and slots, and
+[policies](../../../concepts/policies.md) for the rule IDs and coverage.
 
 ## Variants
 
@@ -143,14 +157,14 @@ Set the variant on the banner, or on the provider under
 `presentation.prompt` when every banner should share it. The prop wins.
 
 ```tsx
-<ConsentBanner variant="floating" position="bottom-center" />
+<ConsentBanner variant="floating" position="bottom-center" />;
 ```
 
 A floating card in a corner or centered on an edge. This is the default for
 every prompt. A notice keeps the same card, with its right link and "OK" in the footer.
 
 ```tsx
-<ConsentBanner variant="bar" position="top" />
+<ConsentBanner variant="bar" position="top" />;
 ```
 
 A bar across the full width of the viewport. From 1024px wide the text, the
@@ -158,14 +172,14 @@ right links, and the controls share one row. Opt in to it for regions that
 expect a classic cookie bar.
 
 ```tsx
-<ConsentBanner variant="widget" position="bottom-right" />
+<ConsentBanner variant="widget" position="bottom-right" />;
 ```
 
 A compact card with smaller type. The full description and its legal links
 remain visible. Pair it with a short notice.
 
 ```tsx
-<ConsentBanner variant="wall" />
+<ConsentBanner variant="wall" />;
 ```
 
 A centered card over a backdrop that blocks the page until the visitor
@@ -248,7 +262,7 @@ Use the individual parts when you need a different order or your own markup:
 	<ConsentBanner.RightLink right="opt-out" asChild>
 		<a href="/privacy/do-not-sell">Do not sell or share my data</a>
 	</ConsentBanner.RightLink>
-</ConsentBanner.Rights>
+</ConsentBanner.Rights>;
 ```
 
 `useBannerCopy()` returns the title, description, and prompt kind the banner