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

package/docs/frameworks/react/customize.md

@@ -0,0 +1,250 @@
+---
+title: Customize
+description: Change the colors, fonts, layout, button styles and copy of the
+  c15t banner and dialog in a React app with the stylesheet, theme tokens,
+  provider options and slots.
+group: frameworks
+---
+
+## Pick the right tool
+
+| Change                               | Use                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| Brand colors, fonts, radius, spacing | [Theme tokens](#change-colors-fonts-and-radius)                     |
+| Light and dark colors, animation     | [Dark mode and motion](#turn-on-dark-mode-and-change-motion)        |
+| Which button is filled or outlined   | [`consentActions`](#style-the-action-buttons)                       |
+| Banner shape and position            | [`ConsentBanner` props or `presentation`](#change-the-banner-shape) |
+| One element of a component           | [Component parts](#style-one-component-part)                        |
+| Labels and languages                 | [Copy and translations](#change-the-copy)                           |
+| Different markup entirely            | [Headless](./headless.md)                                           |
+
+[Customization](../../customization/overview.md) explains how these choices relate
+across frameworks.
+
+See the [design gallery](../../customization/recipes.md) for five banner designs,
+from a bottom bar to a fully custom one, with tested code for this framework.
+
+## Import the stylesheet
+
+Import the stylesheet once, in the module that renders `ConsentProvider`. The
+[quickstart](./quickstart.md) does this in `src/consent.tsx`:
+
+```tsx
+import 'c15t/react/styles.css';
+```
+
+The import is the same with or without Tailwind. To import the stylesheet from
+CSS instead, put it at the top of your global stylesheet, above any
+`@tailwind` directives. `postcss-import`, which Vite uses, ignores an
+`@import` that follows other rules. Tailwind 3 also needs a PostCSS plugin;
+[Tailwind CSS](../../customization/tailwind.md#set-up-tailwind-css-3) shows the
+setup.
+
+## Change colors, fonts and radius
+
+Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
+properties. The package stylesheet sets the default values. To change them,
+render `ConsentTheme` with your theme where your app renders on the server,
+or override the variables directly in your CSS.
+
+`ConsentTheme` renders a `<style id="c15t-theme">` element with the
+variables for `theme`. It is not a client component: rendered from a Server
+Component or another server-only file, the theme generator stays out of the
+browser bundle. Rendered from a client component it still works, but the
+browser downloads the generator (about 1.7 KB gzip). The provider no longer
+turns `theme` tokens into CSS. It still reads `consentActions` and slot
+styles from its `theme` option, and warns in development when `theme` holds
+tokens but the page has no `c15t-theme` stylesheet.
+
+| `ConsentTheme` prop | Purpose                                                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`             | Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.                                                                                     |
+| `colorScheme`       | `'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`. |
+| `nonce`             | Content Security Policy nonce for the `<style>` element.                                                                                                                                    |
+
+Pass the same `colorScheme` to `ConsentTheme` and to the provider. If your
+app manages dark mode through a root class, such as next-themes' `dark`
+class, omit `colorScheme` and include that class in the server HTML.
+[Dark mode](../../customization/dark-mode.md) covers `theme.dark`, `null` and
+a dark first paint.
+
+To switch between different token sets at runtime, render `ConsentTheme`
+from a client component and change its props, which ships the generator.
+
+Outside a component, call `generateThemeCSS(theme, colorScheme)` from
+`c15t/react/utils`, or `@c15t/react/utils` with the scoped package. It
+writes the same CSS as `ConsentTheme`. Outside React, import it from
+`@c15t/ui/theme`. Call it on the server or at build time and put the result in a
+`<style>` element or your stylesheet. It escapes `<`, so the result is safe
+inside `<style>`.
+
+A single-page app has no server render, so pick one of two ways:
+
+* **Set the variables in your CSS.** Nothing extra ships to the browser. Load
+  this after `c15t/react/styles.css`:
+
+  ```css title="src/index.css"
+  :root {
+    --c15t-primary: #2f6f4e;
+    --c15t-primary-hover: #24563c;
+    --c15t-text-on-primary: #fff;
+    --c15t-radius-lg: 4px;
+  }
+  ```
+
+* **Render `ConsentTheme` next to the provider.** Use this when the theme lives
+  in TypeScript or changes at runtime. The browser downloads the theme
+  generator.
+
+  ```tsx title="src/consent-theme.ts"
+  import { defineTheme } from 'c15t/react';
+
+  export const theme = defineTheme({
+    colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
+    radius: { lg: '4px' },
+  });
+  ```
+
+  In `src/consent.tsx`, render `<ConsentTheme theme={theme} />` from
+  `c15t/react` just before `<ConsentProvider>`.
+
+In a server-rendered app, such as React Router framework mode, render
+`ConsentTheme` in the root component so the `<style>` element is part of the
+server HTML. [Theme tokens](../../customization/tokens.md) lists every variable.
+
+`ConsentTheme` outranks a plain `:root` rule, wherever each one loads. If you
+use both, a variable set in both places takes the `ConsentTheme` value. Write
+your CSS overrides on `:root:root` to beat it, or move the values into the
+theme.
+
+## Style the action buttons
+
+`consentActions` decides how each action looks. `default` applies to every
+button, `primary` to the action the policy or your props mark primary, and
+`accept`, `reject`, `customize` and `dismiss` to one action each. Pass it
+through the provider's `theme` option:
+
+```tsx title="src/consent.tsx"
+<ConsentProvider
+  options={{
+    mode,
+    scripts,
+    theme: {
+      consentActions: {
+        primary: { variant: 'primary', mode: 'filled' },
+        dismiss: { variant: 'neutral', mode: 'stroke' },
+      },
+    },
+  }}
+>
+```
+
+The provider's `theme` option only reads `consentActions` and slot styles.
+Tokens passed there do nothing, and the provider logs a warning in development.
+Changing button styles does not change the policy or expire a saved choice.
+
+## Change the banner shape
+
+`ConsentBanner` takes `variant` (`floating`, `bar`, `widget` or `wall`) and
+`position`. To use one shape everywhere, set `presentation.prompt` in the
+provider options instead. This banner is a full-width bar for notices and a
+card for choices:
+
+```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'} />
+	);
+}
+```
+
+Render `RegionalBanner` in place of `ConsentBanner` inside the provider.
+[ConsentBanner](./components/consent-banner.md#variants)
+lists every variant and position, and how to order buttons per policy.
+
+## Style one component part
+
+Each component part is a slot. Set slots in the provider options under
+`components`, keyed by component and part. A slot takes any attribute the
+element accepts, such as `className` or `style`.
+
+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.
+
+[Class names and CSS-in-JS](../../customization/class-names.md) shows CSS
+Modules, vanilla-extract, StyleX and Emotion classes on a part.
+
+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.
+
+[Component parts](../../customization/slots.md) lists every part key under
+`components` and the `data-*` attributes each part carries. Action buttons
+carry `data-action`, so a single rule such as `[data-action='dismiss']`
+styles one role across every surface. Right links are underlined text by
+default, so the only button on a notice is the primary action.
+
+[Component parts](../../customization/slots.md) lists every component's part keys
+and when to drop the built-in styles with `noStyle`. The `ConsentGate`
+placeholder's parts are `components['consent-gate'].root`, `.title` and
+`.button`.
+[Class names and CSS-in-JS](../../customization/class-names.md) covers CSS
+Modules, vanilla-extract, StyleX and Emotion, and
+[Tailwind CSS](../../customization/tailwind.md) covers utilities on parts.
+
+## Turn on dark mode and change motion
+
+Pass `colorScheme` in the provider options and the same value to
+`ConsentTheme`. Leave it unset to follow a `dark` class on `<html>`, and add
+dark colors with `theme.dark`. [Dark mode](../../customization/dark-mode.md)
+covers each value and a dark first paint.
+
+`disableAnimation` in the provider options turns off the banner and dialog
+animations, and the same prop on `ConsentBanner` or `ConsentDialog` overrides
+it for one surface. [Motion and animation](../../customization/motion.md) covers
+the duration and easing tokens and reduced motion.
+
+## Change the copy
+
+Labels, descriptions and languages come from the translations in your Inth
+project and from the provider's `i18n` option. For the visitor's language,
+`i18n.messages` replace the project's copy key by key, and keys you leave out
+keep the project's wording.
+[Copy and translations](../../customization/translations.md) shows the message
+keys. For one banner, `ConsentBanner` also accepts text props such as
+`dismissButtonText`.
+
+## Check the result
+
+Clear site data and reload under a policy that shows a banner. Check the banner
+and the preferences dialog, since both read the same tokens. Test a narrow
+window, keyboard focus and contrast on the primary button. In development, the
+console warns if `theme` holds tokens but the page has no `c15t-theme` style.

package/docs/frameworks/react/embeds.md

@@ -0,0 +1,89 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a React page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker in ConsentProvider.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a React component and want a placeholder until the visitor allows its category. |
+| The iframe blocker | The iframe comes from markup you do not render with React, such as CMS or Markdown content.              |
+
+Both keep the iframe's `src` out of the page until the category is allowed, so
+the embed's host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in `ConsentGate` anywhere inside `ConsentProvider`:
+
+```tsx title="src/video-embed.tsx"
+import { ConsentDialogLink, ConsentGate } from 'c15t/react';
+
+export const VideoEmbed = () => (
+	<ConsentGate
+		category="measurement"
+		placeholder={
+			<div className="placeholder">
+				<p>Allow measurement to load this YouTube video.</p>
+				<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
+			</div>
+		}
+	>
+		<iframe
+			title="YouTube video"
+			sandbox="allow-scripts allow-same-origin allow-presentation"
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
+			allow="encrypted-media; picture-in-picture"
+			allowFullScreen
+		/>
+	</ConsentGate>
+);
+```
+
+The iframe is absent from the page until the visitor allows measurement. The
+`placeholder` shows a message and a
+[`ConsentDialogLink`](./components/consent-dialog-link.md)
+until then. When the visitor withdraws measurement, React removes the iframe.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+[ConsentGate](./components/consent-gate.md) documents the
+built-in placeholder and every prop.
+
+## Gate an iframe with the iframe blocker
+
+`ConsentProvider` runs the iframe blocker by default. Give an iframe
+`data-src` instead of `src`, and a `data-category`:
+
+```html title="Markup from your CMS"
+<iframe
+  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+  data-category="functionality"
+  title="Store map"
+></iframe>
+```
+
+c15t sets `src` from `data-src` when the category is allowed and removes `src`
+when the category is withdrawn. It watches the page, so iframes added later
+are handled too. Add `data-vendor` with a vendor ID to also block the iframe
+while the visitor has turned that vendor off.
+
+To turn the blocker off, set `iframeBlocker: false` in the provider `options`.
+
+## Verify the embeds
+
+Open the production build in a private window with DevTools open, under a
+policy that asks for consent.
+
+1. No iframe has a `src` pointing at `youtube-nocookie.com` or
+   `google.com/maps`, and the Network panel shows no request to them.
+2. Allow the embed's category and save. The iframe loads.
+3. Withdraw the category and save. The page reloads without the embed.
+
+The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.

package/docs/frameworks/react/hooks.md

@@ -0,0 +1,65 @@
+---
+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 one declared vendor may run | `useVendorAllowed(id)`                     |
+| 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.
+
+Use focused hooks for feature gates. For a complete custom prompt or preference
+center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
+for staged choices, inside one `ConsentDraftProvider` so the save commits the
+same draft. v3 has no `useConsentManager()`; the
+[upgrade guide](../../upgrade-v3.md#replace-useconsentmanager) maps each of its
+fields to a hook. Read [how consent works](../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice) before
+treating a callback as evidence of a choice.

package/docs/frameworks/react/iab.md

@@ -0,0 +1,222 @@
+---
+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.
+
+A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
+([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
+String names the CMP that wrote it, so an ID you did not register attributes
+your users' consent records to someone else. Omitting it leaves the add-on
+unmounted: no `__tcfapi`, and no TC String written.
+
+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, after `c15t/react/styles.css`: the IAB
+stylesheet holds only the IAB rules and uses the tokens from the base
+stylesheet.
+
+```tsx title="src/iab-consent.tsx"
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
+
+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.
+
+## Restrict how vendors use a purpose
+
+Publisher restrictions override a vendor's declared use of one purpose. Pass
+them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
+placeholders; use vendors from your list whose declarations allow each
+restriction.
+
+```tsx title="src/iab-consent.tsx"
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
+
+const publisherRestrictions = [
+	// Vendors 10 and 755 may not use purpose 4.
+	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
+	// Vendor 755 must use legitimate interest for purpose 7.
+	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
+];
+
+export function IABConsent({ cmpId }: { cmpId: number }) {
+	return (
+		<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
+			<IABConsentBanner />
+			<IABConsentDialog />
+		</IABProvider>
+	);
+}
+```
+
+Each restriction type has a requirement that depends on the vendor list:
+
+| `restrictionType` | Meaning                                | Allowed when the vendor                                                         |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `0`               | Purpose not allowed on any legal basis | declares the purpose for consent or legitimate interest                         |
+| `1`               | Consent required                       | declares the purpose for legitimate interest and lists it in `flexiblePurposes` |
+| `2`               | Legitimate interest required           | declares the purpose for consent and lists it in `flexiblePurposes`             |
+
+Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
+only with consent. TCF allows restrictions only in service-specific TC strings.
+c15t always writes those, so the deprecated `isServiceSpecific` option has no
+effect on restrictions.
+c15t copies the restrictions when the CMP starts, so changing your array
+afterwards has no effect.
+
+c15t checks restrictions when the vendor list loads and again before each TC
+String is encoded. Unsupported restrictions include type `3`, which the spec
+reserves, a vendor or purpose missing from the list, and a vendor with two
+restriction types for one purpose. They are never dropped. Loading IAB
+settings, saving and generating a TC String all reject with a
+`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
+these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
+written and no consent is recorded. Retrying `whenReady()` does not fetch
+another vendor list. The error lasts until a new vendor list is set up: with an
+explicit `gvl` option that never happens, so saving keeps failing even if the
+kernel later holds a different list. When the CMP follows the kernel's list
+instead, a replacement list is checked again and saving works once it accepts
+the restrictions. When a replacement vendor list makes a restriction
+unsupported, c15t also clears the TC authority confirmed under the previous
+list, so gated scripts stop until the configuration is fixed. Whenever c15t
+withdraws the authority it confirmed, it also removes the TC String from the
+`euconsent-v2` cookie and localStorage entry. Because the check reads the
+current vendor list, a vendor that stops declaring a purpose or its flexibility
+makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
+together.
+
+Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
+`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
+purpose ID, then vendor ID. A stored TC String whose restrictions differ from
+the current configuration is not restored. If the visitor's stored choice is
+otherwise current, the banner opens again, as it does after a policy change,
+and closes once the visitor saves. IAB gates that depend on the TC String stay
+denied until then. c15t also removes the superseded TC String from the
+`euconsent-v2` cookie and localStorage entry, so vendors reading standard
+storage do not pick it up. An unchanged configuration restores the stored TC
+String without asking.
+When reading a string written under TCF policy version 2 or 3, c15t accepts
+type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
+writes always follow the current policy.
+
+The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
+vendor under the legal basis the restrictions leave it. A vendor whose purpose
+now requires legitimate interest gets an objection control instead of a
+consent toggle, and a prohibited purpose no longer lists the vendor. A
+purpose whose vendors all use legitimate interest has no consent switch,
+because turning one off would change nothing the vendors rely on; its
+objection control is the opt-out. Such a purpose does not decide its c15t
+category: the category follows the purposes in it that the visitor can
+consent to. Legitimate interest never grants a category on its own. If none of
+a category's purposes has a consent basis, the category needs all of them
+consented, which only Accept All does. Stack switches
+cover only the purposes some vendor processes on consent. Display-model rows
+expose this as `hasConsentBasis`. Custom preference UIs can call
+`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
+`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
+declarations. The configured restrictions are on the kernel's IAB state as
+`publisherRestrictions`.
+
+Consent-gated scripts, network rules and iframes with a `vendorId` also apply
+the confirmed restrictions for that vendor:
+
+* Type `0` blocks a target that declares the purpose in `iabPurposes` or
+  `iabLegIntPurposes`.
+* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
+  vendor consent. Legitimate interest no longer satisfies it.
+* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
+  legitimate interest. Consent no longer satisfies it.
+
+Types `1` and `2` block the target when the vendor list does not mark the
+purpose as flexible for that vendor. Targets without a `vendorId` ignore
+restrictions. A target that uses only legitimate interest once restrictions
+apply is not blocked by a refused category, since it needs no consent; its
+legitimate interest signals and the visitor's objection decide. GPC and strict
+scope still block it, and the category stays refused for scripts that depend on
+it. Accept All grants the vendor signal a restriction moves a purpose to,
+including legitimate interest for a vendor that declares none. Legitimate
+interest a restriction introduces applies until the visitor objects: the
+preference centres show it as allowed, and saving without touching it encodes
+it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
+those purposes and vendors for custom preference UIs.
+
+## How the preference centre shows features
+
+The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
+script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
+locked section with a lock icon, because the visitor cannot object to them.
+
+Features get their own section after the special purposes. It shows the IAB
+standard text for features from the Global Vendor List's
+`standardTexts.features`. If the list has no standard text, it shows the
+`iab.preferenceCenter.features.description` translation. Each feature lists
+its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
+TCF forbids showing features next to a control that cannot be disabled.
+
+The feature section follows the theme's spacing and typography tokens.
+Its disclosure arrows are decorative and stay out of the accessibility tree.
+
+A custom preference UI gets the same rows from
+`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
+the special purposes only. `featureRows` holds the features, with
+`locked: false` and `toggle: 'none'`, so render them without a control.
+`featuresStandardText` is the standard text, or `null` when you should use the
+translation.
+
+## Consent scope
+
+c15t stores TCF choices per site and browser, which the TCF calls
+service-specific scope. It does not sync TC strings across devices, and every
+TC string it writes has `IsServiceSpecific` set to `1`.
+
+Do not use `/consent/check` or your own account data to skip the TCF banner on
+another device. That turns the choice into multi-device scope, which the TCF
+requires you to disclose in the first layer, and c15t does not show that
+disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
+logs a warning when you pass `false`.