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

package/dist-types/component-hooks/use-manager.d.ts

@@ -1,40 +0,0 @@
-import type { ActiveUI, AllConsentNames, ConsentState, ConsentType, HasCondition, Model, PromptPresentation, TranslationConfig } from '@c15t/core';
-type SaveType = 'all' | 'custom' | 'necessary';
-export declare const useConsentManager: () => {
-    activeUI: ActiveUI;
-    branding: import("@c15t/core").KernelBranding;
-    consentCategories: AllConsentNames[];
-    consentTypes: ConsentType[];
-    consents: ConsentState;
-    draftIsStale: boolean;
-    effectivePermissions: Readonly<ConsentState>;
-    explicitChoice: Readonly<import("@c15t/core").ExplicitChoice> | null;
-    getDisplayedConsents: () => ConsentType[];
-    has: (condition: HasCondition<AllConsentNames>) => boolean;
-    iab: Readonly<import("@c15t/core").KernelIABState> | null;
-    manager: null;
-    model: Model;
-    noticeDismissal: Readonly<import("@c15t/core").NoticeDismissal> | null;
-    optOutDirectives: readonly import("@c15t/core").PrivacyOptOut[];
-    policyBanner: PromptPresentation;
-    policyCategories: AllConsentNames[];
-    policyDialog: import("@c15t/core").PreferencesPresentation;
-    policyRule: Readonly<import("@c15t/core").ResolvedPolicyRule>;
-    policyScopeMode: import("@c15t/core").PolicyScopeMode;
-    privacySignals: import("@c15t/core").KernelPrivacySignals;
-    promptRequirement: Readonly<import("@c15t/core").PromptRequirement>;
-    resetDraft: () => void;
-    resolution: Readonly<import("@c15t/core").PolicyResolution>;
-    restrictions: Readonly<Partial<Record<import("@c15t/core").OptionalConsentCategory, readonly import("@c15t/core").RestrictionReason[]>>>;
-    saveConsents: (type: SaveType, _options?: {
-        uiSource?: string;
-    }) => Promise<void>;
-    selectedConsentTypes: Readonly<ConsentState>;
-    selectedConsents: Readonly<ConsentState>;
-    setActiveUI: (ui: ActiveUI) => void;
-    setSelectedConsent: (name: AllConsentNames, value: boolean) => void;
-    subscribeToConsentChanges: (listener: (state: ConsentState) => void) => () => void;
-    translationConfig: TranslationConfig;
-    updateConsentCategories: (_names: AllConsentNames[]) => void;
-};
-export {};

package/dist-types/components/frame/atoms.d.ts

@@ -1,11 +0,0 @@
-import type { AllConsentNames } from '@c15t/core';
-import type { BoxProps } from '../shared/primitives/box';
-import type { ConsentButtonProps } from '../shared/primitives/button.types';
-declare const FrameRoot: import("react").ForwardRefExoticComponent<Omit<BoxProps, "slotKey"> & import("react").RefAttributes<HTMLDivElement>>;
-declare const FrameTitle: import("react").ForwardRefExoticComponent<Omit<BoxProps, "slotKey"> & {
-    category?: AllConsentNames;
-} & import("react").RefAttributes<HTMLDivElement>>;
-declare const FrameButton: import("react").ForwardRefExoticComponent<Omit<ConsentButtonProps, "slotKey"> & {
-    category: AllConsentNames;
-} & import("react").RefAttributes<HTMLButtonElement>>;
-export { FrameButton, FrameRoot, FrameTitle };

package/dist-types/components/frame/frame.d.ts

@@ -1,2 +0,0 @@
-import type { FrameProps } from './types';
-export declare const Frame: import("react").ForwardRefExoticComponent<Omit<FrameProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/components/frame/index.d.ts

@@ -1,24 +0,0 @@
-import type { FrameCompoundComponent } from './types';
-/**
- * The Frame component that provides consent-gated content rendering
- *
- * @remarks
- * Acts as a consent boundary for embedded content (iframes, videos, third-party widgets).
- * Conditionally renders children based on user consent, displaying a placeholder when
- * permission is not granted.
- * Supports custom styling via `theme` or complete style override with `noStyle` as well as a custom placeholder.
- *
- * @example
- * ```tsx
- * <Frame category="marketing">
- *   <iframe src="https://www.youtube.com/embed/MtN1YnoL46Q?si=JYIFKdENwls43H-r" />
- * </Frame>
- * ```
- *
- * @see {@link FrameTheme} for theme options
- * @see {@link AllConsentNames} for consent categories
- */
-declare const Frame: FrameCompoundComponent;
-export { FrameButton, FrameRoot, FrameTitle } from './atoms';
-export type { FrameCompoundComponent, FrameProps } from './types';
-export { Frame };

package/dist-types/frame.d.ts

@@ -1 +0,0 @@
-export * from './components/frame';

package/dist-types/ui-save.d.ts

@@ -1,5 +0,0 @@
-import type { ConsentKernel, SaveResult } from '@c15t/core';
-/** Explicit navigation supersedes a pending UI action, even to the same dialog. */
-export declare const invalidateConsentUIAction: (kernel: ConsentKernel) => void;
-/** Keep an open preferences dialog available until its own save succeeds. */
-export declare const saveConsentUI: (kernel: ConsentKernel, save: () => Promise<SaveResult>, canClose: () => boolean) => Promise<SaveResult>;

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

@@ -1,71 +0,0 @@
----
-title: ConsentProvider
-description: Configure the v3 consent runtime and share its state with child components.
-group: frameworks
----
-
-## Mount one provider
-
-```tsx
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Replace the URL with your Inth project endpoint. Import the adapter stylesheet
-once at the app root. In Next.js this component needs a client boundary; prefer
-the framework's `ConsentRoot` when passing server-resolved state.
-
-## Provider responsibilities
-
-The provider owns initialization, persistence, configured script loading and
-subscriptions. Keep it mounted across client navigation. Its initial mode and
-prefetch configuration belong to the runtime's creation, not a per-render
-mechanism for switching visitors or backends.
-
-| Option                | Purpose                                                         |
-| --------------------- | --------------------------------------------------------------- |
-| `mode`                | Hosted, offline or custom transport factory                     |
-| `scripts`             | Consent-managed script configurations                           |
-| `callbacks`           | Choice, permission and error events                             |
-| `theme`, `components` | Theme tokens and component slot attributes                      |
-| `presentation`        | Prompt and preferences layout behavior                          |
-| `i18n`                | Languages and message overrides                                 |
-| `storageConfig`       | Browser record storage configuration                            |
-| `enabled`             | Set false only when intentionally bypassing consent enforcement |
-
-`enabled: false` grants categories and allows gated loading while suppressing
-consent UI. It is not a way to fix failed initialization or hide a banner in
-production.
-
-## Observe changes without inventing choices
-
-`onChoiceRecorded` reports explicit accept, reject and save actions.
-`onPermissionsChanged` also covers changes caused by policy, expiry or privacy
-signals. Hydration and notice dismissal do not become explicit choices.
-
-An externally owned runtime can be passed through `runtime`. Its owner must
-start and dispose it. A provider borrowing that runtime must not initialize or
-dispose a second copy. See [consent state](../../../guides/consent-state.md) and
-[deployment modes](../../../guides/deployment-modes.md).
-
-## Clear data when consent is denied
-
-Set `options.clearOnRevocation` to declare cookies, localStorage keys, and
-sessionStorage keys by optional consent category. Cleanup waits for policy
-resolution, then clears denied categories and later allowed-to-denied
-transitions. This option is initial-only. See
-[clear on revocation](../../../integrations/clear-on-revocation.md) for examples,
-cookie scopes, and browser limits.

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

@@ -1,33 +0,0 @@
----
-title: Consent categories
-description: Assign optional features to categories and understand how policy
-  scope affects permission.
-group: frameworks
----
-
-## Choose categories by purpose
-
-| Category        | Purpose                                        |
-| --------------- | ---------------------------------------------- |
-| `necessary`     | Functionality required for the site to operate |
-| `functionality` | Optional features such as support widgets      |
-| `measurement`   | Analytics and usage measurement                |
-| `experience`    | Optional personalization                       |
-| `marketing`     | Advertising and marketing                      |
-
-`necessary` is always permitted. Assign categories based on what an integration
-does in your application; renaming analytics to necessary does not change its
-purpose. The provider's displayed categories and the resolved policy scope must
-agree.
-
-## Respect policy scope
-
-A strict scope denies categories outside the rule. A permissive scope can allow
-out-of-scope categories unless another restriction applies. When a rule selects
-only some optional categories, set `scopeMode` explicitly. An omitted scope,
-`['*']`, or a list containing only `necessary` expands to the default optional
-categories; a necessary-only list is not a shortcut for disabling all tracking.
-
-Use effective permissions to gate work and explicit choices to inspect what the
-visitor confirmed. Read [consent state](../../../guides/consent-state.md) for that
-distinction and [migration](../../../upgrade-v3.md) for v3 policy configuration.

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

@@ -1,58 +0,0 @@
----
-title: Hooks
-description: Gate features and save consent choices in React components with the
-  focused hooks exported from c15t/react.
-group: frameworks
----
-
-## Read only the state you need
-
-Every hook reads the runtime from the nearest `ConsentProvider`, so call them
-from components rendered inside that provider and import them from
-`c15t/react`.
-
-```tsx title="src/optional-feature.tsx"
-import { useConsent } from 'c15t/react';
-
-export function OptionalFeature() {
-  const allowed = useConsent('marketing');
-  return allowed ? <div>Optional marketing content</div> : null;
-}
-```
-
-Call hooks inside the consent provider. `useConsent` reads effective permission,
-which can be true under an opt-out policy without a recorded grant.
-
-| Need                              | Hook                                       |
-| --------------------------------- | ------------------------------------------ |
-| One category's current permission | `useConsent(category)`                     |
-| All current permissions           | `useConsents()`                            |
-| Recorded per-category choices     | `useExplicitChoice()`                      |
-| Whether a prompt is required      | `usePromptRequirement()`                   |
-| Active policy and resolution      | `usePolicyRule()`, `usePolicyResolution()` |
-| Save an explicit choice           | `useSaveConsents()`                        |
-| Open or close a consent surface   | `useSetActiveUI()`                         |
-| Acknowledge a notice              | `useDismissNotice()`                       |
-
-## Save from a visitor action
-
-Render this component inside your existing `ConsentProvider`.
-
-```tsx title="src/reject-button.tsx"
-import { useSaveConsents } from 'c15t/react';
-
-export function RejectButton() {
-  const save = useSaveConsents();
-  return <button type="button" onClick={() => void save('none')}>Reject optional</button>;
-}
-```
-
-This is an isolated action example, not a complete policy-aware banner. Use the
-stock UI or headless surface actions for a complete prompt. Do not call save on
-mount to persist a state derived from permissions.
-
-`useConsentManager` remains available for the combined UI API, including draft
-management. Prefer focused hooks for simple feature gates and use the headless
-UI hook when implementing a complete custom prompt. Read
-[consent state](../../../../guides/consent-state.md) before treating a callback as evidence
-of a choice.

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

@@ -1,53 +0,0 @@
----
-title: IAB TCF
-description: Mount the IAB TCF banner and dialog inside a React ConsentProvider
-  and configure the CMP ID, policy and vendor data.
-group: frameworks
----
-
-## Prepare the IAB configuration
-
-Use the IAB integration when your application needs the Transparency and Consent
-Framework. Configure an IAB policy, the correct CMP identity and vendor data for
-your deployment. A demo CMP ID is not a production configuration.
-
-Install `@c15t/iab` alongside your framework adapter, then mount the IAB
-components inside an existing consent provider connected to Inth.
-
-Import the components from `c15t/react/iab` and render them inside your
-existing `ConsentProvider` from `c15t/react`. Import `c15t/react/iab/styles.css`
-at your global stylesheet entry.
-
-```tsx title="src/iab-consent.tsx"
-import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
-
-export function IABConsent({ cmpId }: { cmpId: number }) {
-  return (
-    <IABProvider cmpId={cmpId}>
-      <IABConsentBanner />
-      <IABConsentDialog />
-    </IABProvider>
-  );
-}
-```
-
-Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
-preferences entry point through the surrounding consent provider.
-
-## Resolve the policy before rendering
-
-IAB components remain hidden until an applicable policy resolves. Forcing a
-dialog open does not create a policy or vendor list. Inspect resolution and the
-Global Vendor List response before changing rendering conditions.
-
-IAB presentation follows `presentation.prompt.blocking` and
-`presentation.preferences.blocking`. A blocking dialog needs focus management,
-scroll locking and a backdrop together. See [migration](../../../upgrade-v3.md) for
-legacy option behavior.
-
-## Verify vendor and purpose choices
-
-Test category choices alongside vendor, purpose, legitimate-interest and special
-feature controls used by your integration. Confirm the TC String and `__tcfapi`
-reflect the saved state, and verify the vendor's actual requests. A category-only
-banner test does not establish that the IAB flow works.

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

@@ -1,63 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts once and let effective permissions control loading.
-group: frameworks
----
-
-## Register scripts on the provider
-
-Install `@c15t/scripts` for vendor helpers. This React-compatible client component
-uses Inth as the backend. Set the URL to the endpoint supplied by your Inth
-project and keep the component mounted around your application.
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-const scripts = [metaPixel({ pixelId: '123456789012345' })];
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Import your adapter's stylesheet globally, as in the framework quickstart. For
-an existing server-resolved `ConsentRoot`, keep that root and pass
-`scripts` as a top-level prop instead of mounting a second provider.
-
-## Understand loading and revocation
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Some helpers use `alwaysLoad` to load the SDK and signal consent through its own
-API. Read the vendor guide; a category field alone does not guarantee no
-requests.
-
-Removing a script element cannot undo JavaScript that already executed or
-requests already sent. Use the vendor's supported consent and cleanup behavior,
-and stop future event calls after revocation. Test both initial denial and a
-change from allowed to denied.
-
-Use [custom integrations](../../integrations/building-integrations.md) for an
-unlisted vendor and [verification](../../guides/verify-consent.md) for the network
-checks. Google helpers have a separate
-[Consent Mode contract](../../integrations/google-tag-manager.md).
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
-declared data when its category is denied. See
-[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
-and browser limits.

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

@@ -1,217 +0,0 @@
----
-title: Styling
-description: Import the React stylesheet and theme c15t components with tokens,
-  slots, and class names on ConsentProvider.
-group: frameworks
----
-
-## Stylesheet
-
-Import the stylesheet once, next to your global CSS, in the entry module that
-renders `ConsentProvider`:
-
-```tsx
-import 'c15t/react/styles.css';
-```
-
-Every rule lives in `@layer components`, so unlayered utilities from Tailwind
-v4 and atomic classes from StyleX override it without specificity tricks.
-Tailwind v3 treats `@layer components` as its own directive, so import the
-Tailwind 3 build from your Tailwind entry instead, between the `components`
-and `utilities` directives:
-
-```css
-@tailwind base;
-@tailwind components;
-@import 'c15t/react/styles.tw3.css';
-@tailwind utilities;
-```
-
-## Tokens
-
-The provider snippets below are partial configuration examples. Apply them to
-your existing `ConsentProvider` from `c15t/react`, keeping its `mode`, children
-and other options.
-
-Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
-properties. Set them on the provider through `theme`, or override the
-variables directly in your CSS.
-
-React and Next.js render the theme stylesheet in the server HTML before
-the banner. Pass the same theme on the server and the first client render
-so your custom tokens apply before hydration. The provider's `nonce`
-option also applies to this stylesheet for Content Security Policy.
-
-`colorScheme: 'dark'` applies dark tokens in the server HTML.
-`colorScheme: 'system'` uses a CSS media query to follow the visitor's
-preference before hydration. If your app manages dark mode through a
-root class instead, include that class in the server HTML too.
-
-```tsx
-import { ConsentProvider, defineTheme } from 'c15t/react';
-
-const theme = defineTheme({
-	colors: { primary: '#2f6f4e' },
-	radius: { lg: '4px' },
-	consentActions: {
-		primary: { variant: 'primary', mode: 'filled' },
-		dismiss: { variant: 'neutral', mode: 'stroke' },
-	},
-});
-
-<ConsentProvider options={{ mode, theme }} />;
-```
-
-`consentActions` decides how each action role looks: `default` applies to
-every button, `primary` to whichever actions the policy or your props mark
-primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
-Per-action keys win over `primary`, which wins over `default`.
-
-Banner sizing has its own variables. Override them in CSS when a variant
-needs a different footprint:
-
-| Variable                            | Default | Applies to       |
-| ----------------------------------- | ------- | ---------------- |
-| `--consent-banner-max-width`        | `440px` | `floating` cards |
-| `--consent-banner-widget-max-width` | `20rem` | `widget` chips   |
-| `--consent-banner-wall-max-width`   | `30rem` | `wall` cards     |
-
-## Colors by consent model
-
-The primary action can change while the brand color stays the same. Set
-`consentActions.primary` once, then select `primaryButton` per policy as
-shown in [ConsentBanner](../components/consent-banner.md#per-policy-buttons).
-
-To give opt-in and opt-out banners different colors, scope the tokens to
-the root's attributes. Include hover and foreground colors when overriding
-CSS tokens directly:
-
-```css
-[data-prompt][data-model='opt-in'] {
-	--c15t-primary: #2f6f4e;
-	--c15t-primary-hover: #24563c;
-	--c15t-text-on-primary: #fff;
-}
-
-[data-prompt][data-model='opt-out'] {
-	--c15t-primary: #6b3fa0;
-	--c15t-primary-hover: #55327f;
-	--c15t-text-on-primary: #fff;
-}
-```
-
-These colors apply to the action marked primary. Button layout and color
-changes do not change the policy or expire a saved choice.
-
-## Slots
-
-Each component part is a slot. A slot accepts any attributes the element
-takes, so the contract is the same whether you write class strings or pass an
-object with `className` and `style`. Set slots on the provider under
-`components`, keyed by component and part.
-
-For a full-width notice, use the supported `bar` variant. Inside your existing
-provider, replace the stock banner with:
-
-```tsx title="src/regional-banner.tsx"
-import { ConsentBanner, usePolicyRule } from 'c15t/react';
-
-export function RegionalBanner() {
-  const policy = usePolicyRule();
-  return <ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />;
-}
-```
-
-To remove the notice card's radius, add these values to the existing
-`options.components.banner` slots. The root owns `data-prompt`, so the card
-uses Tailwind's `group` selector to read it:
-
-```ts
-const bannerSlots = {
-  root: { className: 'group' },
-  card: { className: 'group-data-[prompt=notice]:rounded-none' },
-  rightLink: {
-    className: 'underline-offset-4 data-[right=opt-out]:text-red-700',
-  },
-};
-
-// In the existing options.components object:
-// banner: bannerSlots
-```
-
-The root also carries `data-variant`, so you can restyle one shape without
-touching the others. Tailwind, giving a `bar` a brand-colored top edge and
-tighter text:
-
-```tsx
-<ConsentProvider
-	options={{
-		mode,
-		presentation: { prompt: { variant: 'bar' } },
-		components: {
-			banner: {
-				root: { className: 'group' },
-				card: {
-					className:
-						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
-				},
-			},
-			description: {
-				banner: { className: 'group-data-[variant=bar]:text-xs' },
-			},
-		},
-	}}
-/>
-```
-
-`data-variant` sits on the root, so child slots use Tailwind's `group`
-prefix to read it.
-
-StyleX, spreading the result of `stylex.props()` into a slot:
-
-```tsx
-import * as stylex from '@stylexjs/stylex';
-
-const styles = stylex.create({
-	card: { borderRadius: 0, boxShadow: 'none' },
-	rightLink: { textUnderlineOffset: 4, color: 'rgb(185 28 28)' },
-});
-
-<ConsentProvider
-	options={{
-		mode,
-		components: {
-			banner: {
-				card: stylex.props(styles.card),
-				rightLink: stylex.props(styles.rightLink),
-			},
-		},
-	}}
-/>;
-```
-
-Set `noStyle` on a component to drop the built-in classes from every part and
-keep only what your slots pass. Set `noStyle` in the provider options to do it
-for every component.
-
-Banner slot keys under `components.banner`:
-
-| Key           | Element                                                                                                           |
-| ------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `root`        | Fixed-position wrapper carrying `data-prompt`, `data-model`, `data-variant`, `data-position`, and `data-blocking` |
-| `cardShell`   | Sizes the card and holds the branding tag                                                                         |
-| `card`        | The visible card, carrying `data-state`                                                                           |
-| `header`      | Title and description container                                                                                   |
-| `title`       | Heading                                                                                                           |
-| `footer`      | Action area                                                                                                       |
-| `actions`     | Group of action groups                                                                                            |
-| `actionGroup` | One group of equally prominent actions                                                                            |
-| `rights`      | Group of right links, rendered before the actions                                                                 |
-| `rightLink`   | One right link, carrying `data-action="right"` and `data-right`                                                   |
-| `overlay`     | Backdrop shown when the banner blocks the page                                                                    |
-
-Action buttons carry `data-action` and `data-variant`, and right links carry
-`data-action="right"`, so a single rule such as `[data-action='dismiss']` or
-`[data-action='right']` styles one role across every surface. Right links are
-underlined text by default, so the only button on a notice is the primary
-action.

package/docs/guides/consent-state.md

@@ -1,60 +0,0 @@
----
-title: Understand consent state
-description: Distinguish policy resolution, effective permissions, explicit
-  choices, notices and privacy signals.
-group: guides
----
-
-## Use effective permissions to gate features
-
-`effectivePermissions` answers whether a category is allowed now. It combines
-the resolved policy, stored choices and privacy signals. Under an opt-out rule,
-permission can be true before the visitor acts. It is not evidence of a recorded
-grant.
-
-| Task                                        | State or API                                         |
-| ------------------------------------------- | ---------------------------------------------------- |
-| Load a script or render an optional feature | `effectivePermissions`, React `useConsent(category)` |
-| Inspect what the visitor confirmed          | `explicitChoice`                                     |
-| Decide whether to show a prompt             | `promptRequirement`                                  |
-| Explain regional behavior                   | `policyRule`                                         |
-| Diagnose initialization                     | `resolution`                                         |
-
-## Record only explicit visitor actions
-
-```ts
-// Run in the corresponding click or form-submit handler.
-await kernel.commands.save('all');
-await kernel.commands.save('none');
-await kernel.commands.save({ marketing: false });
-```
-
-These are three separate examples: accept, reject and a partial save. A partial
-save confirms only the supplied categories and keeps the other categories'
-confirmation times. Do not call all three in one handler.
-
-`onChoiceRecorded` reports an explicit choice. `onPermissionsChanged` reports
-changes in effective permissions, including changes caused by expiry or privacy
-signals. Hydration must not be counted as another visitor choice.
-
-## Treat notices and privacy signals separately
-
-`commands.dismissNotice()` acknowledges the current notice. It does not grant
-categories or overwrite existing denials. Global Privacy Control, or GPC, is a
-browser privacy signal. Its configured restrictions can change permissions
-without creating an explicit choice.
-
-A rule with `prompt: 'none'` can still require a persistent preferences entry
-point. Check the policy's rights instead of hiding preferences merely because
-the banner is absent. An unresolved rule is another distinct state; optional
-permissions stay denied until resolution succeeds.
-
-## Preserve records during hydration
-
-Server helpers return records with policy information and evaluation time.
-Forward that configuration intact. Copying an allowed category into a receipt
-would invent a grant and lose its original confirmation time.
-
-Valid v2 records can be read without a startup rewrite. The next explicit action
-writes the v3 format. See [migration](../upgrade-v3.md) for expiry, partial saves,
-custom transports and backend contract changes.