@c15t/react 3.0.0-alpha.5 → 3.0.0-alpha.6

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

@@ -0,0 +1,596 @@
+---
+title: Upgrade from v2
+description: Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers
+  packages, ConsentProvider and transports, the useConsentManager codemod,
+  callbacks, policies, styles, IAB and stored consent.
+group: frameworks
+---
+
+## Hand the upgrade to a coding agent
+
+**Upgrade this React app to c15t v3**
+
+Paste into Claude Code, Codex, Cursor or another coding agent at the root of your app.
+
+```prompt
+Upgrade this React app from c15t v2 to c15t v3.
+
+Read <https://c15t.com/docs/frameworks/react/upgrade-v3.md> first and follow it in order. Do not guess v3 APIs from memory.
+
+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@alpha`, plus `@c15t/integrations@alpha` if the app uses vendor helpers.
+4. Run `npx @c15t/cli@alpha codemods 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.
+8. Run the typecheck and build, and resolve every `TODO(c15t v3)` comment.
+
+When you finish, list the files you changed, anything you could not migrate, and how you checked that vendor requests still wait for consent.
+```
+
+## Before you start
+
+* Upgrade React and React DOM to 18 or later.
+* If you run your own c15t backend, upgrade it in the same release. A v3
+  client can't read a v2 backend. See
+  [Upgrade a self-hosted backend](../../upgrade-v3.md#upgrade-a-self-hosted-backend).
+  Inth-hosted backends need no change.
+
+## Replace the packages
+
+Remove `@c15t/react` and `@c15t/scripts`, then install `c15t` from the
+`alpha` dist-tag. npm's default tag still resolves v2.
+
+| Package manager | Command                                           |
+| :-------------- | :------------------------------------------------ |
+| npm             | `npm install c15t@alpha @c15t/integrations@alpha` |
+| pnpm            | `pnpm add c15t@alpha @c15t/integrations@alpha`    |
+| yarn            | `yarn add c15t@alpha @c15t/integrations@alpha`    |
+| bun             | `bun add c15t@alpha @c15t/integrations@alpha`     |
+
+Drop `@c15t/integrations@alpha` if you don't use its vendor helpers.
+
+| v2 import                               | v3 import                             |
+| --------------------------------------- | ------------------------------------- |
+| `@c15t/react`                           | `c15t/react`                          |
+| `@c15t/react/headless`                  | `c15t/react/headless`                 |
+| `@c15t/react/styles.css`                | `c15t/react/styles.css`               |
+| `DevTools` from `@c15t/dev-tools/react` | `DevTools` from `c15t/react/devtools` |
+| `@c15t/scripts/*`                       | `@c15t/integrations/*`                |
+
+`@c15t/react` is still published at v3, so its imports keep working if you pin
+it to `@alpha`. These docs use `c15t/react`.
+
+Every v3 package ships ESM only. If a CommonJS file in your app calls
+`require()` on a c15t package, convert it to ESM.
+
+## Rename the integrations dependency
+
+v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts`
+from your dependencies and install `@c15t/integrations` from the `alpha`
+dist-tag:
+
+| Package manager | Command                                |
+| :-------------- | :------------------------------------- |
+| npm             | `npm install @c15t/integrations@alpha` |
+| pnpm            | `pnpm add @c15t/integrations@alpha`    |
+| yarn            | `yarn add @c15t/integrations@alpha`    |
+| bun             | `bun add @c15t/integrations@alpha`     |
+
+Replace the package name in each import. Vendor subpaths and helper names stay
+the same.
+
+Before, in v2:
+
+```ts
+import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+import { posthog } from '@c15t/scripts/posthog';
+```
+
+After:
+
+```ts
+import { googleTagManager } from '@c15t/integrations/google-tag-manager';
+import { posthog } from '@c15t/integrations/posthog';
+```
+
+The `scripts` configuration option and the `Script` type keep their names.
+
+Two helper behaviors change. A helper that needs an ID, such as `metaPixel`,
+`googleTagManager` or `posthog`, now throws when the ID is empty or only
+whitespace, where v2 loaded a broken script. And if your code reads
+`@c15t/integrations/registry`, an entry's `consentCategory` can now be a
+compound condition such as `{ and: ['marketing', 'measurement'] }`, not only a
+category name.
+
+`@c15t/scripts` stays available as a deprecated compatibility package for all
+of v3. It re-exports the implementation and types of `@c15t/integrations`, so
+you can migrate imports separately from the rest of the upgrade. Compatibility
+ends in v4; versions already published stay on npm.
+
+To preview the import changes in JavaScript and TypeScript files:
+
+```bash
+npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
+```
+
+Review the output, then run it again without `--dry-run`. The codemod runs
+only when you name it. It does not change `package.json`, lockfiles, or
+imports inside `.vue`, `.svelte` or `.astro` files; update those by hand, then
+reinstall dependencies and build the app.
+
+## Replace `useConsentManager()`
+
+`useConsentManager()` returned the whole consent state, so every component
+that called it re-rendered on every change. v3 has one hook per field. Run the
+codemod first:
+
+```bash
+npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
+```
+
+Review the proposed files, then run it again without `--dry-run`. For this v2
+component:
+
+```tsx title="Before (v2): components/accept-button.tsx"
+import { useConsentManager } from '@c15t/react';
+
+export function AcceptButton() {
+	const { activeUI, has, saveConsents } = useConsentManager();
+	if (activeUI !== 'banner' || has('marketing')) return null;
+	return (
+		<button type="button" onClick={() => void saveConsents('all')}>
+			Accept
+		</button>
+	);
+}
+```
+
+the codemod writes:
+
+```tsx title="After (v3): components/accept-button.tsx"
+import { useActiveUI, useConsent } from '@c15t/react';
+import { useHeadlessConsentUI } from '@c15t/react/headless';
+
+export function AcceptButton() {
+	const activeUI = useActiveUI() ?? 'none';
+	const hasMarketing = useConsent('marketing');
+	const { saveCustomPreferences: saveConsents } = useHeadlessConsentUI();
+	if (activeUI !== 'banner' || hasMarketing) return null;
+	return (
+		<button type="button" onClick={() => void saveConsents('all')}>
+			Accept
+		</button>
+	);
+}
+```
+
+The codemod keeps the entry you imported from. Change `@c15t/react` to
+`c15t/react` afterwards if you moved to the umbrella package. Fields it cannot
+rewrite stay on a `useConsentManager()` call under a `TODO(c15t v3)` comment,
+which fails the build until you replace them. The table lists the v2 fields
+components read. The other fields held provider configuration, such as
+`legalLinks`, `scripts` and `storageConfig`, or store internals; set
+configuration through `ConsentProvider` props.
+Import hooks from `c15t/react`, `c15t/next` or `c15t/tanstack-start`, and
+`useHeadlessConsentUI` from the matching `/headless` entry.
+
+| v2 field                                                      | v3 replacement                                                                                                  |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `activeUI`                                                    | `useActiveUI()`. It returns `null` until c15t picks a surface, where v2 returned `'none'`.                      |
+| `setActiveUI(ui)`                                             | `useSetActiveUI()`                                                                                              |
+| `has(category)`                                               | `useConsent(category)`, one call per category at the top of the component                                       |
+| `consents`                                                    | `useConsents()`                                                                                                 |
+| `saveConsents('all')`                                         | `useHeadlessConsentUI().saveCustomPreferences('all')`                                                           |
+| `saveConsents('necessary')`                                   | `useHeadlessConsentUI().saveCustomPreferences('none')`                                                          |
+| `saveConsents('custom')`                                      | `useConsentDraft().save()`, or `useHeadlessConsentUI().saveCustomPreferences()` inside a `ConsentDraftProvider` |
+| `selectedConsents`                                            | `useConsentDraft().values`                                                                                      |
+| `setSelectedConsent(name, value)`                             | `useConsentDraft().set(name, value)`                                                                            |
+| `setConsent(name, value)`                                     | `useSaveConsents()`, called with `{ [name]: value }`                                                            |
+| `consentInfo`                                                 | `useExplicitChoice()`                                                                                           |
+| `hasConsented()`                                              | `useExplicitChoice() !== null`                                                                                  |
+| `consentCategories`, `consentTypes`, `getDisplayedConsents()` | `useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`                      |
+| `policyCategories`                                            | `usePolicyCategories()`. The v2 list started with `'necessary'`; this one does not.                             |
+| `policyScopeMode`                                             | `usePolicyScopeMode()`                                                                                          |
+| `policyBanner`                                                | `usePromptPresentation()`                                                                                       |
+| `policyDialog`                                                | `usePreferencesPresentation()`                                                                                  |
+| `model`                                                       | `useModel()`. It returns `null` while no policy matches, where v2 returned `'opt-in'`.                          |
+| `branding`                                                    | `useBranding()`. It returns `null` when unset, where v2 returned `'c15t'`.                                      |
+| `iab`                                                         | `useIABSnapshot()`                                                                                              |
+| `locationInfo`                                                | `useLocation()`                                                                                                 |
+| `overrides`, `setOverrides()`                                 | `useOverrides()`, `useSetOverrides()`                                                                           |
+| `setLanguage()`                                               | `useSetLanguage()`                                                                                              |
+| `user`, `identifyUser()`                                      | `useUser()`, `useIdentify()`                                                                                    |
+| `translationConfig`                                           | `useTranslations()` for the active strings                                                                      |
+| `subscribeToConsentChanges(listener)`                         | `useSubscribeToConsentChanges()`, or the `onPermissionsChanged` callback                                        |
+| `updateConsentCategories(categories)`                         | `useRegisterConsentCategories()`                                                                                |
+| `manager`                                                     | Nothing. Use the hooks above.                                                                                   |
+
+`saveCustomPreferences()` saves the way the stock buttons do. It closes the
+banner or dialog after a successful save. `useSaveConsents()` calls the engine
+directly and does not close anything.
+
+In v2, `useConsentManager()` kept one draft per component. In v3,
+`useConsentDraft()` and `useHeadlessConsentUI()` share a draft only inside a
+`ConsentDraftProvider`. Without one, `saveCustomPreferences()` saves a fresh
+draft and ignores what `useConsentDraft().set()` staged, even in the same
+component. Save with `useConsentDraft().save()`, or render the code that stages
+and the code that saves inside one `ConsentDraftProvider`. `ConsentWidget`
+already includes one. The codemod
+adds a `TODO(c15t v3)` comment where this applies.
+
+## Replace `ConsentManagerProvider`
+
+Swap `ConsentManagerProvider` for `ConsentProvider` from `c15t/react`, and pass
+a transport as `mode`:
+
+| v2 option                                | v3 option                                                                                                      |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `mode: 'hosted'` with `backendURL`       | `mode: hosted({ url })`                                                                                        |
+| `mode: 'offline'` with `offlinePolicy`   | `mode: offline({ 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"
+import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/react';
+
+// Replace ConsentManagerProvider:
+<ConsentProvider
+  options={{ mode: hosted({ url: 'https://your-project.c15t.dev' }) }}
+>
+```
+
+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:
+
+```bash
+npx @c15t/cli@alpha codemods consent-provider-options --dry-run --json
+```
+
+Keep your backend URL. An existing hosted URL such as
+`https://your-project.c15t.dev` keeps working with v3 clients. New Inth
+projects use URLs such as `https://your-project.inth.app`. The
+[React quickstart](./quickstart.md) shows the full provider,
+and [data fetching](../../concepts/data-fetching.md) covers custom transports.
+
+Offline 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
+mounts after hydration, as in v2. `fetchSSRData()` from `c15t/react/server`
+can save the browser its first `/init` request. See
+[rendering](./rendering.md).
+
+## Replace callbacks
+
+Callbacks stay under `callbacks` in your options, with new names:
+
+| v2 callback                                  | v3 callback                                                                                                                                                      |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onConsentSet`                               | `onPermissionsChanged` to react to what may run now. `onChoiceRecorded` to react to the visitor's accept, reject or save.                                        |
+| `onConsentChanged`                           | `onChoiceRecorded`. See the note below the table.                                                                                                                |
+| `onBannerFetched`                            | No callback. In React and Next.js, read `usePolicyResolution()` to know when the policy has resolved. In JavaScript, read `resolution` from the kernel snapshot. |
+| `onError`, `onBeforeConsentRevocationReload` | Unchanged                                                                                                                                                        |
+
+The `callbacks-to-v3` codemod renames `onConsentChanged` to
+`onChoiceRecorded`. It leaves a `TODO(c15t v3)` comment there about the new
+payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
+replacement for:
+
+```bash
+npx @c15t/cli@alpha codemods callbacks-to-v3 --dry-run --json
+```
+
+v2's `onConsentChanged` fired only when a save changed at least one category's
+value, and passed `preferences` and `previousPreferences`. v3's
+`onChoiceRecorded` fires for every accept, reject or save that confirms a
+category, including one that saves the same values again, because each save
+renews the choice's confirmation time. Its payload carries `snapshot`,
+`confirmed` and `actionAt`. v3 has no callback that fires only when a save
+changes a value. If you need the before and after values, use
+`onPermissionsChanged`: it passes `previous` and the new `snapshot` whenever
+effective permissions change, whether a save or something else changed them.
+
+v2's `onConsentSet` also fired on initialization and hydration. In v3,
+`onChoiceRecorded` runs only when the visitor acts, and `onPermissionsChanged`
+runs when effective permissions change for any reason, including expiry, a
+policy update or a privacy signal. Neither runs at startup if the resolved
+permissions match the defaults, such as an opt-in policy that leaves every
+category denied. If an external API needs the starting state, read it once at
+startup as well: in React and Next.js from `useEffectivePermissions()` in an
+effect, which also runs on later changes, and in JavaScript from
+`kernel.events.on('init:applied', ({ snapshot }) => ...)`.
+
+```ts title="After (v3): callbacks in your options"
+callbacks: {
+  onChoiceRecorded(event) {
+    console.log('Visitor recorded a choice', event);
+  },
+  onPermissionsChanged(event) {
+    console.log('Effective permissions changed', event);
+  },
+},
+```
+
+## Move policy packs to policy rules
+
+v2 policy packs become policy rules, and `policyPackPresets` becomes
+`policyRulePresets`, exported from `c15t`. Where the rules live depends on your
+backend:
+
+* **Inth**: set the rules in your Inth project. Rules in client code do not
+  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 })`.
+
+```tsx title="After (v3): offline policy rules"
+import { offline, policyRulePresets } from 'c15t';
+
+const mode = offline({
+	policyRules: [
+		policyRulePresets.europeOptIn(),
+		policyRulePresets.worldOptOutNoPrompt(),
+	],
+});
+```
+
+| v2 preset                                 | v3 preset               |
+| ----------------------------------------- | ----------------------- |
+| `europeOptIn()`, `europeIab()`            | Same names              |
+| `californiaOptIn()`, `californiaOptOut()` | Same names              |
+| `quebecOptIn()`                           | Same name               |
+| `worldNoBanner()`                         | `worldOptOutNoPrompt()` |
+
+`worldNone()` is a separate, new preset: it shows nothing and grants no
+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
+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
+`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
+between a permission and a recorded choice.
+
+## Rename options and components
+
+| v2                                                                                                 | v3                                                                                                                                |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `translations`                                                                                     | `i18n`                                                                                                                            |
+| `backendURL`, `mode: 'hosted'`                                                                     | `mode: hosted({ url })`                                                                                                           |
+| `ssrData` (Next.js)                                                                                | `ConsentRoot` with `state` from `resolveConsent()`                                                                                |
+| `iframeBlockerConfig`                                                                              | `iframeBlocker`, or `false` to turn it off                                                                                        |
+| `Frame`                                                                                            | `ConsentGate`. `Frame` still works as a deprecated alias.                                                                         |
+| `frame` translations, such as `frame.title`                                                        | `consentGate`, such as `consentGate.title`. Copy under `frame` still applies and logs a warning outside production.               |
+| `FrameTranslations`                                                                                | `ConsentGateTranslations`. `FrameTranslations` still works as a deprecated alias.                                                 |
+| `--frame-*` CSS variables                                                                          | `--consent-gate-*`, with the same suffixes, such as `--consent-gate-placeholder-background-color`. The old names no longer apply. |
+| `YouTubeEmbed`, `GoogleMap`                                                                        | Removed. Wrap your own embed in `ConsentGate`.                                                                                    |
+| `useConsentScript()`                                                                               | Removed. Register the script in `scripts` with a `@c15t/integrations` helper.                                                     |
+| `useSSRStatus()`                                                                                   | Removed                                                                                                                           |
+| `ConsentButton`                                                                                    | Removed. Use the `ConsentBanner` and `ConsentWidget` buttons, or call `useHeadlessConsentUI()` from your own button.              |
+| `@c15t/react/cookie-banner`                                                                        | `c15t/react/consent-banner`                                                                                                       |
+| `retryConfig`                                                                                      | Removed                                                                                                                           |
+| `store`, including `namespace`, `debug`, `initialConsentCategories` and `initialTranslationConfig` | Removed. Use the top-level `consentCategories` and `i18n` options. Debug information is on `window.c15t`.                         |
+| `window.c15tStore`                                                                                 | `window.c15t`                                                                                                                     |
+| `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`.
+
+```bash
+npx @c15t/cli@alpha codemods consent-provider-options translations-to-i18n --dry-run --json
+```
+
+`ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
+and `ConsentWidget` keep their names. The `scripts`, `networkBlocker`,
+`legalLinks`, `overrides`, `theme` and `colorScheme` options keep theirs too,
+but `theme` tokens no longer produce CSS on their own. See
+[Update styles and themes](#update-styles-and-themes).
+
+`persistence` and `storageConfig` are read once, when the provider mounts. v2
+moved a stored choice when the storage key changed. Remount the provider to
+change storage. Reading a vendor that nothing declares, through `vendors`, a
+script or the backend, returns `false`.
+
+Some names left the root `c15t/react` entry:
+
+| v2 import from the root                                                                                         | v3 import                                                                                                                                      |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useHeadlessConsentUI`, `useConsentDialogTrigger`, `useColorScheme`, `useFocusTrap` and the translation helpers | `c15t/react/headless`                                                                                                                          |
+| Flat banner parts such as `ConsentBannerCard` and `ConsentBannerAcceptButton`                                   | `ConsentBanner.Card`, `ConsentBanner.AcceptButton` and the other compound parts, or the same names from `c15t/react/components/consent-banner` |
+| `TriggerRoot`, `TriggerButton`, `TriggerIcon`, `TriggerText`, `useTriggerContext`, `useDraggable`               | `c15t/react/consent-dialog-trigger`                                                                                                            |
+| Token types such as `ColorTokens` and `TypographyTokens`                                                        | `c15t/react/types`. `Theme` stays on the root.                                                                                                 |
+| `configureConsentManager`, `policyPackPresets`, `ConsentStoreState`, `ConsentManagerInterface`                  | Removed. Use `policyRulePresets` from `c15t`.                                                                                                  |
+
+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@alpha codemods root-exports-to-subpaths --dry-run --json
+```
+
+`ConsentGate` changes one behavior from `Frame`. When its category is granted,
+the embed now mounts after hydration instead of in the server HTML, so an
+iframe loads once instead of twice. Size the wrapper with `className` or
+`style` to hold its space. Test ids change from `frame-placeholder` and
+`frame-open-dialog` to `consent-gate-placeholder` and `consent-gate-button`.
+
+## Update styles and themes
+
+### Render theme CSS
+
+In v2 the provider built CSS from `options.theme` in the browser. In v3 it
+doesn't. Without a change, custom colors, fonts and radii fall back to the
+defaults, and you only see a development warning.
+
+Render `ConsentTheme` with the same theme object, or put the output of
+`generateThemeCSS(theme)` in your own stylesheet. Keep `options.theme` for
+`consentActions` and `slots`. See
+[customization](../../customization/overview.md) and
+[tokens](../../customization/tokens.md).
+
+The `theme-to-consent-theme` codemod marks a provider `theme` that sets
+tokens with a `TODO(c15t v3)` comment.
+
+A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
+`:root` lose to it. Put them in the theme instead, or raise your selector.
+
+### Stylesheets
+
+* Dialog and preference styles moved from `styles.css` to
+  `@c15t/ui/styles/dialog.css`. The React, Next.js and TanStack Start dialogs
+  import it themselves. Import it yourself only if you render `@c15t/ui`
+  class maps for those parts.
+* `iab/styles.css` no longer repeats the default tokens. Import it after
+  `styles.css`.
+* Tailwind CSS 3 builds now fail without a PostCSS plugin, even with
+  `styles.tw3.css`, because the dialog stylesheet is imported from JavaScript.
+  Add `'c15t/postcss-tailwind3': {}` before `tailwindcss` in
+  `postcss.config`. See [Tailwind CSS 3](../../customization/tailwind.md#set-up-tailwind-css-3).
+  Create React App can't run the plugin. The `postcss-tailwind3` codemod adds
+  it to an object-form `postcss.config` and warns about configs it can't
+  edit.
+
+### CSS variables and slots
+
+| v2                                                                    | v3                                                                 |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `--consent-widget-*`                                                  | `--consent-manager-*`, used by `ConsentDialog` and `ConsentWidget` |
+| `--consent-widget-accordion-*`                                        | Removed. Set `--accordion-*` instead.                              |
+| `--frame-*`                                                           | `--consent-gate-*`                                                 |
+| `--consent-banner-entry-animation`, `--consent-banner-exit-animation` | Removed                                                            |
+| `theme.slots.frame`                                                   | `consentGate`, `consentGateTitle` and `consentGateButton`          |
+| `theme.slots.consentDialogFooter`                                     | `consentWidgetFooter`                                              |
+
+The `css-variables-to-v3` codemod renames `--consent-widget-*` and
+`--frame-*` in stylesheets and inline styles, and marks
+`--consent-widget-accordion-*` with a comment instead of renaming it, because
+`--accordion-*` styles every accordion. `theme-to-consent-theme` renames
+`theme.slots.consentDialogFooter` and marks `theme.slots.frame`.
+
+```bash
+npx @c15t/cli@alpha 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
+check slots you set before the upgrade.
+
+## Move IAB setup to `IABProvider`
+
+React, Next.js and TanStack Start no longer take an `iab` provider option.
+Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or
+`ConsentRoot`, around the IAB components. Its props are the options you passed
+to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new
+`publisherRestrictions`.
+
+The `iab-option-to-iab-provider` codemod marks the `iab` option with a
+`TODO(c15t v3)` comment; move it by hand.
+
+A `cmpId` that isn't an integer from 2 to 4095 now throws. Without a `cmpId`,
+the CMP doesn't mount, so there is no `__tcfapi` and no TC string.
+
+`@c15t/iab` no longer exports `createIABManager`, `decodeTCString`,
+`generateTCString` or `c15tToIabPurposes`. Use `createIAB({ kernel, cmpId })`,
+which returns a handle with `generateTCString()`, `acceptAll()`, `rejectAll()`
+and `save()`. If your app depends on `@c15t/iab` directly, upgrade it to
+`@c15t/iab@alpha` too, or your import resolves to the v2 package. Remove it if
+`IABProvider` now covers everything you used it for.
+
+Server integrations now send a reference to the Global Vendor List instead of
+the list, and the browser fetches it when the IAB module mounts. If you set a
+Content Security Policy, allow the list's origin in `connect-src`, or `'self'`
+for same-origin routes.
+
+See the [IAB guide](./iab.md) for a complete setup.
+
+## Update headless UI code
+
+`useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`.
+The `root-exports-to-subpaths` codemod moves the import.
+Some of its methods take different arguments:
+
+| v2                                                 | v3                                                                                               |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `performAction(action, { surface })`               | `performAction(action)`. It also accepts `'dismiss'` and `'customize'`.                          |
+| `openBanner({ force })`                            | `openBanner()`                                                                                   |
+| `saveCustomPreferences({ uiSource })`              | `saveCustomPreferences()`, `saveCustomPreferences('all')` or `saveCustomPreferences('none')`     |
+| `banner.layout`, `dialog.layout`, `hasPolicyHints` | `banner` and `dialog` carry `variant`, `position`, `rights`, `requiredActions` and `diagnostics` |
+
+The `UseHeadlessConsentUIResult` type is no longer exported. Use
+`ReturnType<typeof useHeadlessConsentUI>` if you need it.
+
+## Update complete translation objects
+
+Partial overrides through `i18n.messages` and objects typed as `Translations`
+need no change. A complete translation object typed as `CompleteTranslations`
+fails type-checking until you add the new sections and keys: `consentGate`, which
+replaces `frame`, `rights`, the notice and dismiss strings such as
+`common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy
+under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves
+`frame` copy to `consentGate`.
+
+`i18n.messages` for the visitor's language now merge over the backend's copy
+instead of being replaced by it.
+
+## Keep visitors' existing choices
+
+v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It
+does not rewrite them on page load; the next accept, reject or save writes a
+v3 record.
+
+A v2 denial keeps restricting its category. A v2 grant keeps applying until
+the policy's validity period runs out, and then c15t asks again. If the rule
+comes from a preset and the v2 record noted the policy it was made under, c15t
+also asks again when that policy has changed. Under custom rules, a v2 grant
+applies until it expires. Do not copy permissions into new
+records yourself; c15t decides which v2 choices still count.
+
+## Update dev tools
+
+`@c15t/dev-tools/react` and `@c15t/dev-tools/tanstack` are gone. Import
+`DevTools`, `C15tTanStackDevtoolsPanel` and `c15tDevtools()` from
+`c15t/react/devtools`. Dev tools read the consent engine, so `namespace`,
+`createStoreConnector()` and `getC15tStore()` are gone too. See
+[dev tools](./components/dev-tools.md).
+
+The `dev-tools-to-c15t` codemod points the imports at `c15t/react/devtools` and
+removes the `namespace` prop:
+
+```bash
+npx @c15t/cli@alpha codemods dev-tools-to-c15t --dry-run --json
+```
+
+## 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
+  [Choose your setup](../../concepts/choose-your-setup.md) for those apps.
+
+## Check the migration
+
+1. Run your typecheck and build. Remaining `TODO(c15t v3)` comments from the
+   codemod fail the build until you resolve them.
+2. Load the app with a v2 consent cookie from before the upgrade. The banner
+   stays closed if that choice still applies, and a rejected category stays
+   blocked.
+3. In a private window, check in DevTools Network that vendor requests wait for
+   consent, start after you accept, and stay absent after you reject and
+   reload.
+4. Reopen preferences from your privacy settings link and change a category.
+
+The [verification guide](../../guides/verify-consent.md) has the full release
+checklist.

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

@@ -66,6 +66,12 @@ helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
 is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
 [vendor guide](../../integrations/overview.md) names its slug.
 
+Declaring a helper's vendor is optional. Without a declaration the script
+still loads with its category, but the dialog has no switch for it. In
+development, c15t logs a console warning that names the slug, so you can
+declare it if visitors should be able to turn it off. Production builds
+skip the warning.
+
 A self-hosted backend can declare vendors too. `/init` returns them and c15t
 merges them with the vendors in code. When both declare the same `id`, the
 code declaration wins.