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

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

@@ -16,15 +16,17 @@ same `ConsentProvider`; the [quickstart](../quickstart.md) mounts both.
 import { ConsentDialogLink } from 'c15t/react';
 
 export function SiteFooter() {
-  return (
-    <footer>
-      <nav aria-label="Legal">
-        <a href="/privacy">Privacy policy</a>
-        <a href="/terms">Terms</a>
-        <ConsentDialogLink className="footer-link">Privacy settings</ConsentDialogLink>
-      </nav>
-    </footer>
-  );
+	return (
+		<footer>
+			<nav aria-label="Legal">
+				<a href="/privacy">Privacy policy</a>
+				<a href="/terms">Terms</a>
+				<ConsentDialogLink className="footer-link">
+					Privacy settings
+				</ConsentDialogLink>
+			</nav>
+		</footer>
+	);
 }
 ```
 
@@ -37,8 +39,8 @@ To reuse an existing link component, pass `asChild`:
 
 ```tsx
 <ConsentDialogLink asChild>
-  <a href="#cookie-preferences">Manage cookies</a>
-</ConsentDialogLink>
+	<a href="#cookie-preferences">Manage cookies</a>
+</ConsentDialogLink>;
 ```
 
 ## Props

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

@@ -1,35 +1,20 @@
 ---
 title: ConsentDialogTrigger
-description: Floating button and toolbar that reopen the preference center after
-  the first prompt.
+description: Add the c15t ConsentDialogTrigger floating button or toolbar inside
+  a React ConsentProvider so visitors can reopen the preference center after the
+  first prompt.
 group: frameworks
 ---
 
-## Usage
+## Add the trigger inside ConsentProvider
 
-`ConsentDialogTrigger` is a draggable floating button that opens the preference center. Place it once, next to the banner and dialog, so visitors can revisit their choices without a footer link.
+`ConsentDialogTrigger` is a draggable floating button that opens the preference center. Place it once inside `ConsentProvider`, next to the banner and dialog from the [quickstart](../quickstart.md), so visitors can revisit their choices without a footer link.
 
-```tsx
-import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogTrigger,
-  ConsentProvider,
-  offline,
-} from 'c15t/react';
-import { policyRulePresets } from '@c15t/schema';
-
-const mode = offline({ policyRules: [policyRulePresets.europeOptIn()] });
-
-export function App() {
-  return (
-    <ConsentProvider options={{ mode }}>
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogTrigger showWhen="after-prompt" />
-    </ConsentProvider>
-  );
-}
+```tsx title="src/consent.tsx"
+import { ConsentDialogTrigger } from 'c15t/react';
+
+// Inside the ConsentProvider from your quickstart, next to the dialog:
+<ConsentDialogTrigger showWhen="after-prompt" />;
 ```
 
 `showWhen="after-prompt"` keeps the button out of the way while a choice or notice is still owed and shows it once the visitor has answered, so the banner and the trigger never compete for the same corner. The default, `always`, shows it whenever the preference center is closed.
@@ -56,43 +41,63 @@ Use `ConsentDialogTriggerToolbar` when you want app-owned controls beside the pr
 import { ConsentDialogTriggerToolbar } from 'c15t/react';
 
 <ConsentDialogTriggerToolbar
-  ariaLabel="Site controls"
-  actions={[
-    {
-      id: 'theme',
-      label: isDark ? 'Switch to light theme' : 'Switch to dark theme',
-      icon: isDark ? <SunIcon /> : <MoonIcon />,
-      pressed: isDark,
-      onSelect: toggleColorScheme,
-    },
-    {
-      id: 'support',
-      label: 'Open support chat',
-      icon: <ChatIcon />,
-      onSelect: openSupportChat,
-    },
-  ]}
-  preferences={{
-    icon: 'fingerprint',
-    label: 'Manage privacy settings',
-  }}
-/>
+	ariaLabel="Site controls"
+	actions={[
+		{
+			id: 'theme',
+			label: isDark ? 'Switch to light theme' : 'Switch to dark theme',
+			icon: isDark ? <SunIcon /> : <MoonIcon />,
+			pressed: isDark,
+			onSelect: toggleColorScheme,
+		},
+		{
+			id: 'support',
+			label: 'Open support chat',
+			icon: <ChatIcon />,
+			onSelect: openSupportChat,
+		},
+	]}
+	preferences={{ icon: 'fingerprint', label: 'Manage privacy settings' }}
+/>;
 ```
 
 Each custom action needs a stable `id`, an accessible `label`, an `icon`, and an `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable ones. Your app owns the state behind each action. The preferences action moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.
 
-The toolbar does not depend on the consent policy. Your actions always render, so a theme toggle stays available while a banner is up. On the toolbar, `showWhen` applies only to the built-in preferences action: `after-prompt` hides that one item while a choice or notice is owed and shows it once the visitor has answered, and `never` leaves it out. The toolbar renders nothing only when it has no visible item. On the single `ConsentDialogTrigger`, `showWhen` applies to the whole control.
-
-No policy, no UI. When no rule has resolved, because resolution failed, no rule matched and you set no default, or init is still withheld, the built-in preferences action and the single `ConsentDialogTrigger` render nothing; app-owned toolbar actions still do. They appear as soon as a rule resolves, without a remount. A rule with `model: 'none'` owes no rights, so the built-in action and the single trigger hide under it too, unless the rule adds `rights: ['preferences']`. The policy chooses what the control says, you choose where and when it sits, and it disappears only when there is nothing to manage.
-
-The built-in action names the strongest right the active rule guarantees. Under a rule that carries the `opt-out` right, such as a US opt-out notice, its accessible name is the translated "Do not sell or share my data" and the button carries `data-right="opt-out"`. Under any other rule it reads "Manage preferences" with `data-right="preferences"`. Either way it opens the preference center, and a `preferences.label` you pass replaces the default. The button also carries `data-c15t-rights` with every right on the rule.
-
 Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and switch arrow-key navigation to up and down:
 
 ```tsx
-<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />
+<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />;
 ```
 
+### When the controls show
+
+Your toolbar actions do not depend on the consent policy, so a theme toggle
+stays available while a banner is up. The built-in preferences action, and the
+single `ConsentDialogTrigger`, follow the policy:
+
+| Situation                                                                                                         | Built-in action and `ConsentDialogTrigger`             |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| A choice or notice is still owed, with `showWhen="after-prompt"`                                                  | Hidden until the visitor answers                       |
+| `showWhen="never"` on the toolbar                                                                                 | Left out of the toolbar                                |
+| No policy rule has resolved: resolution failed, no rule matched and you set no default, or init is still withheld | Hidden; appears without a remount once a rule resolves |
+| The rule has `model: 'none'`                                                                                      | Hidden, unless the rule adds `rights: ['preferences']` |
+| Any other case                                                                                                    | Shown                                                  |
+
+On the toolbar, `showWhen` applies only to the built-in action. On the single
+`ConsentDialogTrigger`, it applies to the whole control. The toolbar renders
+nothing only when it has no visible item.
+
+### What the built-in action says
+
+* Under a rule with the `opt-out` right, such as a US opt-out notice, its
+  accessible name is the translated "Do not sell or share my data" and it
+  carries `data-right="opt-out"`.
+* Under any other rule it reads "Manage preferences" and carries
+  `data-right="preferences"`.
+* Either way it opens the preference center. A `preferences.label` you pass
+  replaces the default name, and the button carries `data-c15t-rights` with
+  every right on the rule.
+
 ### Toolbar props
 
 | Prop              | Type                                     | Default              | Description                                                                                                                                                      |
@@ -113,30 +118,30 @@ The toolbar follows the standard precedence: bundled styles, then provider slots
 
 ```tsx
 <ConsentProvider
-  options={{
-    mode: offline({ policyRules: [policyRulePresets.europeOptIn()] }),
-    components: {
-      trigger: {
-        toolbar: { className: 'my-toolbar' },
-        toolbarItem: { className: 'my-toolbar-item' },
-        toolbarIcon: { className: 'my-toolbar-icon' },
-      },
-    },
-  }}
+	options={{
+		mode,
+		components: {
+			trigger: {
+				toolbar: { className: 'my-toolbar' },
+				toolbarItem: { className: 'my-toolbar-item' },
+				toolbarIcon: { className: 'my-toolbar-icon' },
+			},
+		},
+	}}
 >
-  <ConsentDialogTriggerToolbar
-    className="fixed-toolbar"
-    actions={[
-      {
-        id: 'support',
-        label: 'Open support chat',
-        icon: <ChatIcon />,
-        onSelect: openSupportChat,
-        className: 'support-action',
-      },
-    ]}
-  />
-</ConsentProvider>
+	<ConsentDialogTriggerToolbar
+		className="fixed-toolbar"
+		actions={[
+			{
+				id: 'support',
+				label: 'Open support chat',
+				icon: <ChatIcon />,
+				onSelect: openSupportChat,
+				className: 'support-action',
+			},
+		]}
+	/>
+</ConsentProvider>;
 ```
 
 The toolbar slot keys are `trigger.toolbar`, `trigger.toolbarItem`, and `trigger.toolbarIcon`. With `noStyle`, style the current position and interaction state through `data-corner`, `data-dragging`, and `data-snapping` on the toolbar element.

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

@@ -14,32 +14,37 @@ group: frameworks
 code.
 
 ```tsx title="src/consent.tsx"
-import type { ReactNode } from 'react';
 import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogLink,
-  ConsentProvider,
-  hosted,
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
 } from 'c15t/react';
+import type { ReactNode } from 'react';
+
+import { scripts } from './scripts';
+
 import 'c15t/react/styles.css';
 
-const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
-if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
-const mode = hosted({ url: backendURL });
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog hideBranding />
-      <footer>
-        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-      </footer>
-    </ConsentProvider>
-  );
-}
+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>
+);
+```
+
+To hide the "Secured by" tag in the dialog card, pass `hideBranding`:
+
+```tsx
+<ConsentDialog hideBranding />;
 ```
 
 To open it from your own component, set the active surface:
@@ -48,41 +53,41 @@ To open it from your own component, set the active surface:
 import { useSetActiveUI } from 'c15t/react';
 
 export function PrivacyMenuItem() {
-  const setActiveUI = useSetActiveUI();
-  return (
-    <button type="button" onClick={() => setActiveUI('dialog')}>
-      Cookie preferences
-    </button>
-  );
+	const setActiveUI = useSetActiveUI();
+	return (
+		<button type="button" onClick={() => setActiveUI('dialog')}>
+			Cookie preferences
+		</button>
+	);
 }
 ```
 
 `ConsentDialogLink` does the same with the policy's rights exposed for
 styling; see [ConsentDialogLink](./consent-dialog-link.md). For a floating
 button, see [ConsentDialogTrigger](./consent-dialog-trigger.md). Under an IAB
-policy, mount `IABConsentDialog` from the [IAB guide](../iab/overview.md)
+policy, mount `IABConsentDialog` from the [IAB guide](../iab.md)
 instead; this dialog stays closed for the `iab` model.
 
 ## Props
 
-| Prop                      | Type                                  | Default                         | Description                                                                                                                                                                                                      |
-| ------------------------- | ------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `open`                    | `boolean`                             | follows the active surface      | Controls the open state. When set, Escape and the dialog's own Save, Accept all and Reject all buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed. |
-| `showTrigger`             | `boolean \|ConsentDialogTriggerProps` | `false`                         | Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.                                                                                                          |
-| `models`                  | `Model[]`                             | `['opt-in', 'opt-out', 'none']` | Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.                                                                                                          |
-| `legalLinks`              | `(keyof LegalLinks)[] \|null`         | none                            | Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.                                                              |
-| `hideBranding`            | `boolean`                             | `false`                         | Hides the "Secured by" tag in the card.                                                                                                                                                                          |
-| `uiSource`                | `string`                              | `'dialog'`                      | Source identifier recorded with saves made from this dialog.                                                                                                                                                     |
-| `scrollLock`, `trapFocus` | `boolean`                             | from `blocking`                 | Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.                            |
-| `disableAnimation`        | `boolean`                             | `false`                         | Skips the enter and exit animation of the backdrop and the card.                                                                                                                                                 |
-| `noStyle`                 | `boolean`                             | `false`                         | Removes the built-in styling from every part.                                                                                                                                                                    |
+| Prop                      | Type                                  | Default                         | Description                                                                                                                                                                                                               |
+| ------------------------- | ------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`                    | `boolean`                             | follows the active surface      | Controls the open state. When set, Escape and the dialog's own Save Settings, Accept All and Reject All buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed. |
+| `showTrigger`             | `boolean \|ConsentDialogTriggerProps` | `false`                         | Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.                                                                                                                   |
+| `models`                  | `Model[]`                             | `['opt-in', 'opt-out', 'none']` | Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.                                                                                                                   |
+| `legalLinks`              | `(keyof LegalLinks)[] \|null`         | none                            | Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.                                                                       |
+| `hideBranding`            | `boolean`                             | `false`                         | Hides the "Secured by" tag in the card.                                                                                                                                                                                   |
+| `uiSource`                | `string`                              | `'dialog'`                      | Source identifier recorded with saves made from this dialog.                                                                                                                                                              |
+| `scrollLock`, `trapFocus` | `boolean`                             | from `blocking`                 | Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.                                     |
+| `disableAnimation`        | `boolean`                             | `false`                         | Skips the enter and exit animation of the backdrop and the card.                                                                                                                                                          |
+| `noStyle`                 | `boolean`                             | `false`                         | Removes the built-in styling from every part.                                                                                                                                                                             |
 
 ## Behavior
 
 The dialog is a modal wrapper around the preference center. Its card has a
 header with the title `consentManagerDialog.title` and the description
 `consentManagerDialog.description` followed by the legal links, then the
-same category accordion and Reject all, Accept all and Save actions that
+same category accordion and Reject All, Accept All and Save Settings actions that
 `ConsentWidget` renders, then the branding tag. It mounts through a portal
 into `document.body` after hydration, so it is never part of the server
 HTML.
@@ -97,14 +102,44 @@ it is `dialog`. These set that surface:
 * `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
   from `useHeadlessConsentUI()` on the headless subpath.
 
-The component code is split into its own chunk. It downloads when the
-dialog first opens or when a visitor hovers or focuses a Customize button,
-and renders nothing until that chunk is ready. Passing `open={true}` or
-`showTrigger` loads it on mount.
-
-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
+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 Settings, Accept All and
+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](../../../concepts/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,
@@ -138,11 +173,12 @@ The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
 and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
 while it is blocking. Its `dir` attribute follows the active language.
 
-While blocking, focus moves on open to the panel itself rather than to a
-button, so a screen reader announces the title and description first; Tab
-then enters the legal links and category switches, Tab and Shift+Tab wrap
-inside the panel, and on close focus returns to the element that opened the
-dialog. A non-blocking dialog manages no focus: nothing moves focus into the
+While blocking, focus moves on open to the first tabbable control in the
+panel, so a keyboard user sees the focus ring on a control rather than
+around the whole panel; the `aria-labelledby` and `aria-describedby`
+wiring means a screen reader still announces the title and description as
+focus enters. Tab and Shift+Tab wrap inside the panel, and on close focus
+returns to the element that opened the dialog. A non-blocking dialog manages no focus: nothing moves focus into the
 panel or back to the opener. The backdrop is `aria-hidden` and is not
 focusable.
 
@@ -186,9 +222,18 @@ 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.
+[customize](../customize.md) for slots and tokens.
 
 ## Verify
 

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

@@ -19,17 +19,17 @@ placeholder button opens.
 import { ConsentGate } from 'c15t/react';
 
 export function ProductVideo() {
-  return (
-    <ConsentGate category="marketing" className="video-frame">
-      <iframe
-        src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
-        title="Product tour"
-        loading="lazy"
-        allowFullScreen
-        style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
-      />
-    </ConsentGate>
-  );
+	return (
+		<ConsentGate category="marketing" className="video-frame">
+			<iframe
+				src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
+				title="Product tour"
+				loading="lazy"
+				allowFullScreen
+				style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
+			/>
+		</ConsentGate>
+	);
 }
 ```
 
@@ -53,8 +53,8 @@ placeholder is replaced.
 Other `div` attributes such as `className`, `style` and `ref` apply to the
 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.
+style the wrapper with `className`, and style the built-in placeholder
+through its parts in the provider options.
 
 ## Behavior
 
@@ -70,23 +70,26 @@ 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.
 
-The built-in placeholder shows the title `frame.title`, "Accept {category}
-consent to view this content.", with `{category}` replaced by
-`consentTypes.<category>.title`, and a button labelled `frame.actionButton`,
-"Enable {category} consent". The button opens the preference center; it
+The built-in placeholder shows the title `consentGate.title`,
+`Accept {category} consent to view this content.`, with `{category}`
+replaced by `consentTypes.<category>.title`, and a button labelled
+`consentGate.actionButton`, `Enable {category} consent`. The button opens the
+preference center; it
 does not grant the category by itself, because the visitor still has to
 save. Mount a `ConsentDialog` in the same provider so the button has
 something to open.
 
 Under a policy with `scopeMode: 'strict'`, a category outside the rule's
-scope cannot be granted. The built-in placeholder then shows `frame.policyBlocked`,
+scope cannot be granted. The built-in placeholder then shows `consentGate.policyBlocked`,
 "This content is unavailable under your region's consent policy.", without
 the button, and a stored grant for that category stays blocked.
 
 When the provider starts from a snapshot prefetched on the server, the
-server renders the children or placeholder according to effective permission.
-A grant in the request cookie allows the embed only when policy and privacy
-signals permit it. Browser privacy signals detected during hydration can
+server renders the placeholder for a denied category. For a granted
+category it renders the empty wrapper, and the children mount once
+hydration completes, so an iframe loads once even when the page streams
+inside a `Suspense` boundary. A grant in the request cookie allows the
+embed only when policy and privacy signals permit it. Browser privacy signals detected during hydration can
 withdraw that permission. In a browser-only setup the
 provider has no permission until it resolves policy on the client, so
 `ConsentGate` shows the placeholder first and swaps in the embed after resolution
@@ -124,8 +127,24 @@ translated text; pass children to either to replace it.
 </ConsentGate>
 ```
 
-The built-in placeholder carries `data-testid="frame-placeholder"` and its
-button `data-testid="frame-open-dialog"`.
+To restyle the built-in placeholder without replacing it, set its parts
+under `components['consent-gate']` in the provider options. `root` is the
+card, and `title` and `button` are its text and button. The `consentGate`, `consentGateTitle` and
+`consentGateButton` theme slots reach the same parts. The button part
+applies on top of `button.primary`.
+
+```tsx
+components: {
+  'consent-gate': {
+    root: { className: 'rounded-none' },
+    button: { className: 'font-semibold' },
+  },
+},
+```
+
+The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
+its title `data-testid="consent-gate-title"` and its button
+`data-testid="consent-gate-button"`.
 
 ## Accessibility
 
@@ -142,7 +161,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