@c15t/react 3.1.0 → 3.2.0-canary.0

package/docs/frameworks/react/headless.md

@@ -1,7 +1,7 @@
 ---
 title: Headless
-description: Build a custom consent banner in React with the c15t/react/headless
-  hooks inside your ConsentProvider.
+description: Build a custom consent banner or embed gate in React with the
+  c15t/react/headless hooks inside your ConsentProvider.
 group: frameworks
 ---
 
@@ -30,29 +30,28 @@ The headless hooks read the runtime from the nearest `ConsentProvider` from
 banner, and keep the dialog and persistent preferences control.
 
 ```tsx title="src/consent-banner.tsx"
-import { useHeadlessConsentUI, useTranslations } from 'c15t/react/headless';
-
-const ACTION_LABELS = {
-	accept: 'acceptAll',
-	customize: 'customize',
-	dismiss: 'acknowledge',
-	reject: 'rejectAll',
-	save: 'save',
-} as const;
+import {
+	useBannerCopy,
+	useConsentLabels,
+	useHeadlessConsentUI,
+} from 'c15t/react/headless';
 
 export const Banner = () => {
 	const { banner, performAction, openDialog } = useHeadlessConsentUI();
-	const { common, rights } = useTranslations();
+	const { title, description } = useBannerCopy();
+	const labels = useConsentLabels();
 
 	if (!banner.isVisible) {
 		return null;
 	}
 
 	return (
-		<section aria-label="Privacy">
+		<section aria-label={title}>
+			<h2>{title}</h2>
+			<p>{description}</p>
 			{banner.preferenceControls.map((right) => (
 				<button key={right} type="button" onClick={openDialog}>
-					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
+					{labels.preferenceControls[right]}
 				</button>
 			))}
 			{banner.actionGroups.map((group) => (
@@ -64,7 +63,7 @@ export const Banner = () => {
 							data-primary={banner.primaryActions.includes(action) || undefined}
 							onClick={() => performAction(action)}
 						>
-							{common[ACTION_LABELS[action]]}
+							{labels.actions[action]}
 						</button>
 					))}
 				</div>
@@ -76,8 +75,10 @@ export const Banner = () => {
 
 `banner.actionGroups` is the resolved layout: reject and accept share a group
 at equal prominence, and the rest follow. `banner.orderedActions` is the same
-list flattened. Under a notice the only action is `dismiss`, and
-`banner.preferenceControls` recommends additional buttons for opening
+list flattened. `banner.primaryActions` lists the actions to style as
+primary. Under a notice the only action is `dismiss`, and
+`banner.primaryActions` contains it. `banner.preferenceControls` recommends
+additional buttons for opening
 preferences. Under a notice it contains `opt-out`, which selects the
 "Do not sell or share my data" label. The example renders that button and
 an "OK" button. Both controls keep their own command: opening
@@ -86,6 +87,20 @@ preferences and dismissing the notice.
 The list is a rendering helper. It does not establish that your UI implements
 all policy rights. Provide disclosure and persistent preferences access.
 
+`useBannerCopy()` returns the `title` and `description` for the active
+prompt. A notice reads `cookieBanner.noticeTitle` and
+`cookieBanner.noticeDescription`, then falls back to the choice copy in the
+same language before English. `useConsentLabels()` returns
+`actions`, a label for each action, and `preferenceControls`, a label for
+each preference control. `dismiss` reads `common.acknowledge`, then
+`common.dismiss`. Both hooks follow the active language and fill missing
+keys from English, and they are the same strings the pre-built banner
+renders.
+
+The hooks wrap `resolvePromptCopy`, `resolveActionLabels`, and
+`resolvePreferenceControlLabels`. Those take a translations object and
+are exported from `c15t`, so code outside React can produce the same copy.
+
 `performAction` saves all categories for `accept`, none for `reject`, the
 current draft for `save`, records a dismissal for `dismiss`, and opens the
 preference center for `customize`. `banner.diagnostics` reports when a host
@@ -94,5 +109,117 @@ prominence. Review each diagnostic when configuring custom presentation.
 
 `banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
 shape from `presentation.prompt`, so a headless surface can follow the same
-bar, widget, or wall choice the pre-built banner would make, and can trap
-focus and lock scroll exactly when `blocking` is true.
+bar, widget, or wall choice the pre-built banner would make. The pre-built
+banner traps focus and locks page scroll while `blocking` is true. To do
+the same, call `useFocusTrap(blocking, ref)` and `useScrollLock(blocking)`
+from the headless entry, with `blocking` set to
+`banner.isVisible && banner.blocking` and `ref` attached to your banner's
+root element. Scroll locks are counted, so the page scrolls again once the
+banner and any open dialog have both let go.
+
+c15t can show consent copy in the visitor's browser language, which may run
+right to left on a left-to-right page. `useConsentTextDirection()` returns
+`'rtl'` or `'ltr'` for the language the copy is in. Set it as `dir` on your
+banner and preference center roots, as the pre-built ones do.
+
+The pre-built banner and dialog render nothing under the IAB model, and
+the TCF surfaces inside `<IABProvider>` take over. A
+custom surface that handles only opt-in and opt-out should do the same:
+return `null` when `useModel()` is `'iab'`. Call `useIABPolicyGuard()` in
+it as well. It throws `IABUnavailableError` while rendering when the
+policy needs IAB and the app never loaded `<IABProvider>`, so the gap
+shows up in your error boundary instead of as a missing banner.
+
+## Build a custom consent gate
+
+`useConsentGate(category)` tells a custom gate what to render for one
+consent category, with translated copy and an action that opens the
+preference center. Use it when the stock `ConsentGate` placeholder does not
+fit your design, for example a design system card in front of a video or
+map embed. `ConsentGate` runs on the same hook, so both gates follow the
+same rules.
+
+This gate renders its children once `marketing` is granted and the page has
+hydrated, the policy message when the policy blocks `marketing`, and
+otherwise a placeholder with a button that opens the preference center:
+
+```tsx title="src/video-gate.tsx"
+import { useConsentGate } from 'c15t/react/headless';
+import type { ReactNode } from 'react';
+
+export const VideoGate = ({ children }: { children: ReactNode }) => {
+	const { state, title, actionLabel, policyBlockedMessage, requestConsent } =
+		useConsentGate('marketing');
+
+	if (state === 'granted') {
+		return children;
+	}
+	if (state === 'pending') {
+		return null;
+	}
+	if (state === 'policy-blocked') {
+		return <p>{policyBlockedMessage}</p>;
+	}
+	return (
+		<div>
+			<p>{title}</p>
+			<button type="button" onClick={requestConsent}>
+				{actionLabel}
+			</button>
+		</div>
+	);
+};
+```
+
+Render `VideoGate` inside your `ConsentProvider` around the embed, such as a
+YouTube `iframe`.
+
+| Field                  | Type                    | Description                                                                                                            |
+| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `state`                | `ConsentGateState`      | `'granted'`, `'pending'`, `'denied'` or `'policy-blocked'`.                                                            |
+| `categoryTitle`        | `string`                | `consentTypes.<category>.title` from your translations, or the category name when they have none.                      |
+| `title`                | `string` or `undefined` | `consentGate.title`, `Accept {category} consent to view this content.`, with `{category}` replaced by `categoryTitle`. |
+| `actionLabel`          | `string` or `undefined` | `consentGate.actionButton`, `Enable {category} consent`, with `{category}` replaced by `categoryTitle`.                |
+| `policyBlockedMessage` | `string`                | `consentGate.policyBlocked`, or the English message when your translations have none.                                  |
+| `requestConsent`       | `() => void`            | Opens the preference center.                                                                                           |
+
+The result type is exported as `UseConsentGateResult` and the state type as
+`ConsentGateState`. Render from `state`:
+
+* `'granted'`: the effective permission for the category is granted and
+  the page has hydrated. Render the content.
+* `'pending'`: permission is granted but the page has not hydrated yet.
+  Render nothing.
+* `'denied'`: permission is not granted. Render a placeholder with a
+  button that calls `requestConsent`.
+* `'policy-blocked'`: the policy has `scopeMode: 'strict'` and its scope
+  leaves the category out, so the visitor cannot grant it. Render
+  `policyBlockedMessage` without a button. `necessary` is never blocked.
+
+Permission is the value `useConsent(category)` returns. An opt-out policy
+can grant it before the visitor chooses, and a privacy signal such as GPC
+can withdraw a stored grant.
+
+Granted content never appears in the server HTML. When the server snapshot
+grants the category, `state` is `'pending'` in the server HTML and during
+hydration, then turns `'granted'`, so an iframe inside a streamed
+`Suspense` boundary loads once. Server rendering and hydration evaluate the
+snapshot at its own evaluation time and never read the clock, so the gate
+works in a statically prerendered page.
+
+`requestConsent` does not grant the category, because the visitor still has
+to save. The preference center opens on its usual view, not on the
+category. Mount a `ConsentDialog` in the same provider so it has something
+to open. The stock gate button starts loading the pre-built dialog's code
+on hover, focus and idle time. `requestConsent` doesn't, so without a
+banner or dialog trigger on the page, the first open waits for that
+download.
+
+When it mounts, the hook registers the category with the provider, as
+`ConsentGate` does, so the preference center can list it. If you set
+`options.consentCategories` on the provider, list the category there too,
+so the preference center shows it before a gate mounts, including on pages
+without one.
+
+The hook renders no wrapper element. Reserve the embed's space in your own
+markup so the page does not shift when the placeholder is replaced.

package/docs/frameworks/react/iab.md

@@ -274,7 +274,7 @@ The backend's `additionalConsent` option sets the cache, which defaults to the
 
 ### List the providers in the browser
 
-Offline mode has no backend, and some backends do not list providers. In
+Local mode has no backend, and some backends do not list providers. In
 those setups, pass `additionalConsent` with your other IAB options: the
 `IABProvider` props in React, Next.js and TanStack Start, the `createIAB`
 options in JavaScript, and the `iab` option of the Vue, Nuxt, Svelte, Astro
@@ -380,6 +380,13 @@ its own CMP ID. It lists the CMPs it has certified on its
 Ask Google to list your CMP ID through its CMP intake form before you rely on
 the AC string in production.
 
+## c15t's IAB CMP registration
+
+Inth makes c15t. Inth's legal entity, Consent Management Inc., is registered
+with IAB Europe as a CMP under CMP ID 490. The
+[IAB Europe CMP list](https://iabeurope.eu/cmp-list/) shows it under the name
+Consent Management Inc.
+
 ## How the preference centre shows features
 
 The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the

package/docs/frameworks/react/quickstart.md

@@ -25,7 +25,7 @@ You need an [Inth](https://inth.com) project. In the project, set the policy
 rules for your regions, add your site's origin to the trusted origins, and copy
 the backend URL.
 [Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
-covers self-hosting and offline mode.
+covers self-hosting and local mode.
 
 The guide uses `hosted()` mode. Policy, translation and vendor edits in your
 project reach visitors on their next page load, without a rebuild.

package/docs/frameworks/react/rendering.md

@@ -54,7 +54,7 @@ usually shows 50 to 250 ms sooner. There is nothing to configure.
 
 The early request can't read your app's options, so in a few setups it won't
 match and the app sends a second `/init`. Pass `initPrefetch: false` when the
-app uses `offline()` or gives `hosted()` its own `backendURL`, `fetch`,
+app uses `local()` or gives `hosted()` its own `backendURL`, `fetch`,
 `initURL` or `headers`. With its own `fetch`, `hosted()` sends `/init` through
 it and ignores the early response. If it sets `credentials`, `overrides`, `storageKey`, an
 `experiment`, or `journey: false`, pass the same values as

package/docs/frameworks/react/translations.md

@@ -12,10 +12,10 @@ The banner, dialog, widget and gate placeholder read their text from one set
 of translations for the visitor's language. Which set depends on the
 provider's `mode`:
 
-| Mode        | Copy comes from                                                                                                                                                                                       |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hosted()`  | The backend's `/init` response for the visitor's language, from the translations in your Inth project or your self-hosted backend's configuration, with your `i18n` messages for that language on top |
-| `offline()` | Your `i18n` messages, merged over bundled English                                                                                                                                                     |
+| Mode       | Copy comes from                                                                                                                                                                                       |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hosted()` | The backend's `/init` response for the visitor's language, from the translations in your Inth project or your self-hosted backend's configuration, with your `i18n` messages for that language on top |
+| `local()`  | Your `i18n` messages, merged over bundled English                                                                                                                                                     |
 
 With a backend, edit wording in your Inth project first, so it changes without
 a deploy. Code can override that copy in two places:
@@ -35,12 +35,12 @@ When your project has no copy for it, the backend returns its fallback
 language. Set `overrides.language` in the provider options to request a
 specific language instead.
 
-In `offline()` mode, `i18n.locale` picks the language, `en` by default. The
+In `local()` mode, `i18n.locale` picks the language, `en` by default. The
 browser's language is not read.
 
 The banner, dialog and widget set `dir` from the active language. Right-to-left
-languages such as Arabic and Hebrew render with `dir="rtl"`, and a floating
-banner you did not position yourself moves to the opposite side.
+languages such as Arabic and Hebrew render with `dir="rtl"`. The banner stays
+in the same corner.
 
 ## Change the copy in code
 
@@ -73,7 +73,7 @@ Pass them to the provider in the file that renders it, such as
 
 For the visitor's language, your messages replace the backend's copy key by
 key. Keys you leave out keep the project's wording, and messages for other
-languages are not applied. In `offline()` mode c15t bundles only English, so
+languages are not applied. In `local()` mode c15t bundles only English, so
 keys you leave out for another language show in English.
 
 The provider reads `i18n` once, when it mounts. In development it logs a
@@ -137,7 +137,7 @@ Setting the language without calling `init()` changes nothing on screen. Your
 `i18n` messages for the new language apply on top of the copy that arrives.
 Render the switcher anywhere inside `ConsentProvider`.
 
-Switching needs a backend. In `offline()` mode the copy stays in the
+Switching needs a backend. In `local()` mode the copy stays in the
 `i18n.locale` language.
 
 If your site changes language through its own i18n library, you can instead

package/docs/frameworks/react/troubleshooting.md

@@ -44,7 +44,7 @@ is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
 
 Only a build that uses `manifest()` downloads the manifest. The plugin
 fetches after Vite has dropped the code the app does not use, so a `hosted()`
-or `offline()` build never contacts the backend and never fails this way.
+or `local()` build never contacts the backend and never fails this way.
 
 An error or warning that says `no backend URL is set` means the plugin found
 no `backendURL` option and no variable. Set `VITE_C15T_BACKEND_URL` (or

package/docs/frameworks/react/upgrade-v3.md

@@ -18,7 +18,7 @@ Read ./upgrade-v3.md first and follow it in order. Do not guess v3 APIs from mem
 1. List every c15t dependency and import: `@c15t/react`, `@c15t/scripts`, `@c15t/dev-tools` and `c15t`.
 2. Check that React is 18 or later. Stop and tell me if it needs a major upgrade.
 3. Replace the packages with `c15t`, plus `@c15t/integrations` if the app uses vendor helpers.
-4. Run `npx @c15t/cli codemods packages-to-c15t consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks scripts-to-integrations dev-tools-to-c15t policy-packs-to-policy-rules callbacks-to-v3 theme-to-consent-theme iab-option-to-iab-provider css-variables-to-v3 postcss-tailwind3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
+4. Install the Inth CLI with `npm install -g @inth/cli` if `inth` is missing, then run `inth c15t codemods packages-to-c15t consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks scripts-to-integrations dev-tools-to-c15t policy-packs-to-policy-rules callbacks-to-v3 theme-to-consent-theme iab-option-to-iab-provider css-variables-to-v3 postcss-tailwind3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
 5. Check that `ConsentManagerProvider` is now `ConsentProvider` from `c15t/react`, with a transport such as `hosted()` as `mode`. Finish any custom mode the codemod marked.
 6. Update callbacks, policy presets, renamed options and components, theme CSS, CSS variables and IAB setup as the guide describes.
 7. Keep the existing backend URL. If the app runs its own c15t backend, stop and tell me, because it has to be upgraded in the same release with <https://v3.c15t.com/docs/self-host/upgrade-v3.md>.
@@ -34,6 +34,8 @@ When you finish, list the files you changed, anything you could not migrate, and
   client can't read a v2 backend. See
   [Upgrade a self-hosted backend](https://c15t.com/docs/self-host/upgrade-v3).
   Inth-hosted backends need no change.
+* Install the [Inth CLI](https://c15t.com/docs/cli/overview#install-the-inth-cli). The
+  codemods run through `inth c15t codemods`.
 
 ## Replace the packages
 
@@ -111,7 +113,7 @@ ends in v4; versions already published stay on npm.
 To preview the import changes in JavaScript and TypeScript files:
 
 ```bash
-npx @c15t/cli codemods scripts-to-integrations --dry-run --json
+inth c15t codemods scripts-to-integrations --dry-run --json
 ```
 
 Review the output, then run it again without `--dry-run`. The codemod runs
@@ -126,7 +128,7 @@ that called it re-rendered on every change. v3 has one hook per field. Run the
 codemod first:
 
 ```bash
-npx @c15t/cli codemods use-consent-manager-to-hooks --dry-run --json
+inth c15t codemods use-consent-manager-to-hooks --dry-run --json
 ```
 
 Review the proposed files, then run it again without `--dry-run`. For this v2
@@ -227,7 +229,7 @@ a transport as `mode`:
 | v2 option                                | v3 option                                                                                                      |
 | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `mode: 'hosted'` with `backendURL`       | `mode: hosted({ backendURL })`                                                                                 |
-| `mode: 'offline'` with `offlinePolicy`   | `mode: offline({ policyRules })`                                                                               |
+| `mode: 'offline'` with `offlinePolicy`   | `mode: local({ policyRules })`                                                                                 |
 | `mode: 'custom'` with `endpointHandlers` | `mode: custom(transport)`, where `transport` implements the v3 transport interface. `endpointHandlers` throws. |
 
 ```tsx title="After (v3): the provider, changed lines"
@@ -239,12 +241,13 @@ import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/reac
 >
 ```
 
-The `consent-provider-options` codemod rewrites the hosted and offline modes
-and adds the transport import. It can't translate `endpointHandlers`, so it
-leaves a `TODO(c15t v3)` comment on a custom mode:
+The `consent-provider-options` codemod rewrites the hosted mode and adds the
+`hosted` import. It leaves offline and custom modes as they are, with a
+`TODO(c15t v3)` comment. Move `offlinePolicy.policyPacks` to
+`local({ policyRules })` by hand. It can't translate `endpointHandlers`:
 
 ```bash
-npx @c15t/cli codemods consent-provider-options --dry-run --json
+inth c15t codemods consent-provider-options --dry-run --json
 ```
 
 Keep your backend URL. An existing hosted URL such as
@@ -260,7 +263,7 @@ which bundles the policy when Vite builds. It skips `/init` only when the
 policy has no location rules or the page knows the visitor's location. See
 [consent modes](../../concepts/modes.md).
 
-Offline mode keeps choices in the browser and records nothing on a server. Not
+Local mode keeps choices in the browser and records nothing on a server. Not
 recommended for production environments.
 
 If your app renders on the server with React Router or Remix, the banner still
@@ -285,7 +288,7 @@ payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
 replacement for:
 
 ```bash
-npx @c15t/cli codemods callbacks-to-v3 --dry-run --json
+inth c15t codemods callbacks-to-v3 --dry-run --json
 ```
 
 v2's `onConsentChanged` fired only when a save changed at least one category's
@@ -329,12 +332,12 @@ backend:
   change a hosted policy.
 * **Self-hosted**: move the backend's `policyPacks` to `manifest.policyRules`.
   See [policy configuration](https://c15t.com/docs/self-host/guides/policy-packs).
-* **Offline**: move `offlinePolicy.policyPacks` to `offline({ policyRules })`.
+* **No backend**: move `offlinePolicy.policyPacks` to `local({ policyRules })`.
 
-```tsx title="After (v3): offline policy rules"
-import { offline, policyRulePresets } from 'c15t';
+```tsx title="After (v3): local policy rules"
+import { local, policyRulePresets } from 'c15t';
 
-const mode = offline({
+const mode = local({
 	policyRules: [
 		policyRulePresets.europeOptIn(),
 		policyRulePresets.worldOptOutNoPrompt(),
@@ -342,7 +345,7 @@ const mode = offline({
 });
 ```
 
-In Next.js, import `offline` from `c15t/next` instead and set the result as
+In Next.js, import `local` from `c15t/next` instead and set the result as
 `mode` in `c15t.config.ts`. Both take the same `policyRules`.
 
 | v2 preset                                 | v3 preset               |
@@ -357,13 +360,14 @@ rights, while `worldOptOutNoPrompt()` keeps v2's opt-out and preference rights.
 
 The `policy-packs-to-policy-rules` codemod renames `policyPackPresets` and
 `worldNoBanner()`, and moves the import to `c15t` where it came from
-`c15t/react` or `c15t/next`. `consent-provider-options` moves
-`offlinePolicy.policyPacks` into `offline({ policyRules })`. Preset calls need
+`c15t/react` or `c15t/next`. `consent-provider-options` leaves offline mode
+with a `TODO(c15t v3)` comment; move `offlinePolicy.policyPacks` into
+`offline({ policyRules })` by hand. Preset calls need
 no other change, but a hand-written v2 pack uses `consent` and `ui` keys,
 which v3 rules replace with flat keys such as `model` and `prompt`; the
 codemods mark those with a `TODO(c15t v3)` comment.
 
-v3 adds presets for more regions. `offline()` without `policyRules` uses
+v3 adds presets for more regions. `local()` without `policyRules` uses
 `recommendedPolicyRules()`. Read [policies](../../concepts/policies.md) before you
 change a rule's model or prompt, and
 [how consent works](../../concepts/how-consent-works.md) for the difference
@@ -392,13 +396,13 @@ between a permission and a recorded choice.
 | `iab: iab({ ... })`                                                                                | `IABProvider`. See [Move IAB setup](#move-iab-setup-to-iabprovider).                                                                               |
 
 The `consent-provider-options` codemod renames `ConsentManagerProvider` and
-its option and prop types, turns `mode` and `backendURL` into `hosted()` or
-`offline()`, and renames `iframeBlockerConfig`. v2 still accepted the
-deprecated `translations` option; the `translations-to-i18n` codemod moves it
-to `i18n`.
+its option and prop types, turns `mode: 'hosted'` and `backendURL` into
+`hosted()`, and renames `iframeBlockerConfig`. It leaves offline and custom
+modes with a `TODO(c15t v3)` comment. v2 still accepted the deprecated
+`translations` option; rename it to `i18n` by hand.
 
 ```bash
-npx @c15t/cli codemods consent-provider-options translations-to-i18n --dry-run --json
+inth c15t codemods consent-provider-options --dry-run --json
 ```
 
 `ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
@@ -426,7 +430,7 @@ The `root-exports-to-subpaths` codemod moves these imports to their new
 entries and marks removed names with a `TODO(c15t v3)` comment:
 
 ```bash
-npx @c15t/cli codemods root-exports-to-subpaths --dry-run --json
+inth c15t codemods root-exports-to-subpaths --dry-run --json
 ```
 
 `ConsentGate` changes one behavior from `Frame`. When its category is granted,
@@ -498,7 +502,7 @@ The `css-variables-to-v3` codemod renames `--consent-widget-*` and
 `theme.slots.consentDialogFooter` and marks `theme.slots.frame`.
 
 ```bash
-npx @c15t/cli codemods theme-to-consent-theme css-variables-to-v3 postcss-tailwind3 --dry-run --json
+inth c15t codemods theme-to-consent-theme css-variables-to-v3 postcss-tailwind3 --dry-run --json
 ```
 
 `theme.slots` now applies in React. v2 accepted it in types and ignored it, so
@@ -586,7 +590,7 @@ The `dev-tools-to-c15t` codemod points the imports at `c15t/react/devtools` and
 removes the `namespace` prop:
 
 ```bash
-npx @c15t/cli codemods dev-tools-to-c15t --dry-run --json
+inth c15t codemods dev-tools-to-c15t --dry-run --json
 ```
 
 ## Upgrade from an earlier v3 alpha
@@ -622,16 +626,19 @@ handled by the `consent-provider-options` codemod, not by aliases.
 | The build options `outputFile`, `exportName`, `importSource` and `rootDir` | Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.                      |
 
 React removes nothing besides the modes above. Import `manifest()` from
-`c15t/react`, next to `hosted()` and `offline()`, instead of from
+`c15t/react`, next to `hosted()` and `local()`, instead of from
 `@c15t/browser/headless`; React apps need nothing from `@c15t/browser`.
 
 ## Update the CLI
 
-* Run `c15t login` again. The CLI signs in through Inth now and no longer
-  reads sessions saved by v2.
-* `c15t setup` no longer writes `.env.local` or `.env.example` and no longer
-  accepts `--env`. It writes the backend URL into the files it generates.
-* `c15t setup` no longer detects Remix or Gatsby. Pick a guide from
+* Setup moved to the Inth CLI.
+  [Install the Inth CLI](https://c15t.com/docs/cli/overview#install-the-inth-cli), then run
+  `inth c15t` in place of `c15t setup` and `inth c15t codemods` in place of
+  `c15t codemods`.
+* Sign in with `inth login`. Sessions saved by the v2 CLI aren't read.
+* `inth c15t scaffold` writes the backend URL to `.env`, not `.env.local` or
+  `.env.example`.
+* Remix and Gatsby have no CLI support. Pick a guide from
   [Choose your setup](../../concepts/choose-your-setup.md) for those apps.
 
 ## Check the migration

package/docs/frameworks/react/vendor-consent.md

@@ -157,6 +157,11 @@ const xPixelAllowed = useVendorAllowed('x-pixel');
 or the vendor list changed under the edit. Call `reset()` to start again.
 `useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
 returns the recorded vendor decision, or `null` before the visitor made one.
+To list vendors under each category in your own preference center, call
+`useVendorsListedUnder(category)` from `c15t/react/headless`. It returns the
+vendors the stock dialog lists in that category's row, in declared order. A
+vendor known only from a script's `vendor` slug stays listed after the
+visitor turns it off, so they can turn it back on.
 
 A vendor reads as allowed only when it is declared, its category is allowed
 and the visitor has not switched it off. An id that nothing declares, in

package/docs/guides/banner-experiments.md

@@ -138,7 +138,7 @@ sends it with `/init`, and records it on the choices of visitors the banner
 showed it to, so you can compare opt-in rate and time to decision per arm.
 
 The same option exists in `c15t/next` (`ConsentRoot` `options`), `c15t/vue`,
-`@c15t/svelte`, the `c15t()` Astro integration from `c15t/astro`, and
+`c15t/svelte`, the `c15t()` Astro integration from `c15t/astro`, and
 `@c15t/browser`. On a server-rendered page in Next.js, TanStack Start or
 SvelteKit, pass it to `resolveConsent` instead, which counts the arm and hands
 it to the client; see [Vercel Flags SDK](#vercel-flags-sdk).
@@ -292,7 +292,7 @@ from [send the events to your own analytics](#send-the-events-to-your-own-analyt
 in `options`. The layout awaits consent inside `<Suspense>`, as in
 [render the banner in the server HTML](https://c15t.com/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
 so the banner is in the server HTML already showing the visitor's arm.
-`resolveConsent` in `c15t/tanstack-start/server` and `@c15t/svelte/server`
+`resolveConsent` in `c15t/tanstack-start/server` and `c15t/svelte/server`
 takes the same `experiment`.
 
 If you pass `resolveConsent()` to `ConsentRoot` without awaiting it (the
@@ -520,7 +520,7 @@ server has to know the arm. Pass the experiment to `resolveConsent`, as in
 [Vercel Flags SDK](#vercel-flags-sdk): it sends only `{ id, arm }` to the
 backend and hands the full experiment to the client in its state.
 `resolveConsent` takes `experiment` in `c15t/next/server`,
-`c15t/tanstack-start/server` and `@c15t/svelte/server`; Astro and Nuxt pass
+`c15t/tanstack-start/server` and `c15t/svelte/server`; Astro and Nuxt pass
 the arm they rendered on their own. When c15t picks the arm in the browser,
 the browser's own `/init` carries it, so a server-rendered page that skips
 the client `/init` has no count for built-in assignment. Resolve the arm with

package/docs/guides/troubleshooting.md

@@ -53,7 +53,7 @@ No banner is sometimes correct. Find out which case you have:
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | The backend request failed or has a CORS error     | Wrong backend URL, or your origin is not trusted                                                                                                                                                               | Copy the URL from your Inth project exactly, including any path. Add the site's origin, such as `https://www.example.com` or `http://localhost:3000`, to the project's trusted origins.                                                                |
 | Requests go to `your-project.inth.app` and fail    | The placeholder backend URL from the guides is still in your code                                                                                                                                              | Replace `https://your-project.inth.app` with the URL from your Inth project, including any path prefix.                                                                                                                                                |
-| No backend request at all                          | No provider mounted, the provider runs in offline mode, or the page resolved from a bundled manifest                                                                                                           | Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](../concepts/modes.md#set-the-backend-url) lists. |
+| No backend request at all                          | No provider mounted, the provider runs in local mode, or the page resolved from a bundled manifest                                                                                                             | Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](../concepts/modes.md#set-the-backend-url) lists. |
 | The policy resolved and no prompt is needed        | The visitor's location maps to a policy without a prompt, such as a US state without a privacy law in the recommended rules                                                                                    | Expected. Test from a location that needs a prompt. Server helpers such as Next.js `resolveConsent` accept a `country` override for testing; remove it before you deploy.                                                                              |
 | The policy resolved and a choice is stored         | A returning visitor                                                                                                                                                                                            | Expected. Clear site data or use a private window.                                                                                                                                                                                                     |
 | The banner is in the DOM but invisible or unstyled | c15t's rules are missing: `styles: false` without an imported stylesheet, a Content Security Policy that blocks c15t's `<style>` elements, Tailwind CSS 3's preflight, or a SvelteKit app without `c15tHandle` | See [stylesheets and CSS layers](../customization/stylesheets.md) for how your framework loads c15t's rules.                                                                                                                                           |
@@ -135,6 +135,7 @@ messages, prefixed with the integration's name, such as
 | `could not fetch the consent manifest from <url> during the build (fetch failed: ...)`, with `ENOTFOUND`, `ECONNREFUSED` or another network error | The build cannot reach the backend                                                                                              | Build where the backend is reachable, or deploy with `C15T_ON_BUILD_ERROR=runtime`                                                             |
 | `... (no response within 10 seconds)`                                                                                                             | The backend did not answer in time                                                                                              | Check the backend, or build where it is reachable                                                                                              |
 | `... (/manifest responded 404 Not Found)`, or another status                                                                                      | The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix | Copy the backend URL exactly as Inth shows it                                                                                                  |
+| `... (/manifest responded 402: <message> (<CODE>))`, or another status followed by a message                                                      | The backend refused the request and said why, such as an account out of its usage allowance                                     | Follow the backend's message                                                                                                                   |
 | `... (/manifest returned an invalid consent manifest.)`                                                                                           | The URL answered with something other than a consent manifest, such as an HTML page                                             | Point the backend URL at the backend itself, not your site or a dashboard page                                                                 |
 | `no backend URL is set, so the build cannot fetch the consent manifest. Pass backendURL or set ...`                                               | No `backendURL` option and no backend URL variable                                                                              | Set the variable your framework reads; see [consent modes](../concepts/modes.md#set-the-backend-url)                                           |
 | `skipped the consent manifest fetch because "/api/c15t" is not an absolute http(s) URL, so the server fetches the policy at runtime.`             | A relative backend URL. A notice, not an error.                                                                                 | Pass the absolute backend URL. With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL.` |
@@ -176,7 +177,7 @@ instead of a factory:
 | Message                                                                                                                                                                                                               | Fix                                                                                                                                                                                                                                                                                            |
 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ``@c15t/react ConsentProvider: `mode` is required. Use manifest() or hosted().``                                                                                                                                      | Pass `mode`, such as `manifest()` from the same package. The start of the message names the package and the API that got no mode, such as `@c15t/svelte ConsentProvider` or `@c15t/core createConsentRuntime()`. Production builds name the package only: ``@c15t/react: `mode` is required.`` |
-| ``@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or offline() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.``                                               | Import the factory and call it: `init({ mode: hosted() })`.                                                                                                                                                                                                                                    |
+| ``@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or local() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.``                                                 | Import the factory and call it: `init({ mode: hosted() })`.                                                                                                                                                                                                                                    |
 | ``c15t: hosted() needs `backendURL`. Pass it, or add consentManifest() from c15t/build to your Vite config and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL).``                                                | The React `hosted()` found no backend URL. `@c15t/browser` throws the same message prefixed `@c15t/browser:`. A production build prints only the first sentence.                                                                                                                               |
 | ``c15t: `mode` is the hosted() transport itself, so its code ships in the client bundle. Pass the hosted() your framework package exports instead: it is plain data, and the root loads the code only when it runs.`` | A warning outside production. A server-rendered root got a transport from `c15t/react`. Import the mode from your framework package. Next.js has its own wording; see [Next.js troubleshooting](https://c15t.com/docs/frameworks/next/troubleshooting).                                        |
 

package/docs/integrations/adobe-analytics.md

@@ -172,7 +172,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -191,7 +191,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();

package/docs/integrations/ahrefs-analytics.md

@@ -164,7 +164,7 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentProvider, manifest } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from 'c15t/svelte';
   import { scripts } from './consent-scripts';
 </script>
 
@@ -183,7 +183,7 @@ handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentRoot } from '@c15t/svelte';
+  import { ConsentRoot } from 'c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();