@c15t/react 3.0.0-alpha.8 → 3.0.0

package/docs/frameworks/react/scripts.md

@@ -11,45 +11,33 @@ group: frameworks
 Pass vendor loaders to `ConsentProvider` through `options.scripts`. The
 provider loads each script when its category is allowed and removes it when
 the category is denied. The [quickstart](./quickstart.md)
-registers PostHog this way:
-
-```ts title="src/scripts.ts"
-import { posthog } from '@c15t/integrations/posthog';
-
-export const scripts = [
-	posthog({
-		id: 'phc_your_project_key',
-		initOptions: { cookieless_mode: 'never' },
-		loadMode: 'after-consent',
-	}),
-];
-```
-
-The provider in `src/consent.tsx` receives them:
+registers PostHog this way in `src/consent.tsx`:
 
 ```tsx title="src/consent.tsx"
-import { manifest } from '@c15t/browser/headless';
+import { posthog } from '@c15t/integrations/posthog';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
-import { consentManifest } from './c15t-manifest';
-import { scripts } from './scripts';
-
-import 'c15t/react/styles.css';
-
-const mode = manifest({
-	backendURL:
-		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
-	manifest: consentManifest,
-});
+const options = {
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
+	scripts: [
+		posthog({
+			id: 'phc_your_project_key',
+			initOptions: { cookieless_mode: 'never' },
+			loadMode: 'after-consent',
+		}),
+	],
+};
 
 export const Consent = ({ children }: { children: ReactNode }) => (
-	<ConsentProvider options={{ mode, scripts }}>
+	<ConsentProvider options={options}>
 		{children}
 		<ConsentBanner />
 		<ConsentDialog />
@@ -75,9 +63,10 @@ covers a vendor without one.
   ran keeps running, so after the visitor turns off a category they had
   allowed, the provider reloads the page once the save finishes. Set
   `reloadOnConsentRevoked: false` only if every gated vendor stops itself.
-* **`alwaysLoad` helpers.** Some integrations, such as Google Consent Mode,
-  load before consent and pass the visitor's choice to the vendor. Read the
-  vendor's guide; a category on a script does not always mean zero requests.
+* **`alwaysLoad` helpers.** Some integrations, such as the Google Consent Mode
+  helpers by default, load before consent and pass the visitor's choice to the
+  vendor. Read the vendor's guide; a category on a script does not always mean
+  zero requests.
 
 ## When the script loader downloads
 

package/docs/frameworks/react/troubleshooting.md

@@ -5,34 +5,12 @@ description: Fix a missing banner, early vendor requests, unstyled components
 group: frameworks
 ---
 
-## Why does the build fail to download the manifest?
-
-**Check.** `vite build` or `vite dev` stops before compiling, with an error
-from `consentManifest` that starts with `@c15t/core/build:`.
-
-| Error                                                    | Cause                                                                                                                           | Fix                                                                                  |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `build-time manifests require an absolute upstream URL.` | `backendURL` is empty or relative, such as `/api/c15t`                                                                          | Pass the absolute backend URL from your Inth project                                 |
-| `build-time manifests require an http(s) upstream URL.`  | `backendURL` uses another protocol                                                                                              | Use the `https://` URL Inth shows                                                    |
-| `/manifest responded 404`                                | 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, or set `VITE_C15T_BACKEND_URL`        |
-| `/manifest returned an invalid consent manifest.`        | The URL answered with something other than a consent manifest, such as an HTML page                                             | Point `backendURL` at the backend itself, not your site or a dashboard page          |
-| `fetch failed`                                           | The build cannot reach the backend                                                                                              | Build where the backend is reachable. A failed download never reuses an old snapshot |
-
-## Why can't TypeScript find ./c15t-manifest?
-
-**Check.** `tsc`, `vue-tsc` or your editor reports that it cannot find the
-module `./c15t-manifest`, on a fresh checkout or in CI.
-
-**Fix.** `consentManifest` writes `src/c15t-manifest.ts` when `vite build` or
-`vite dev` starts, and the file is not in Git. Run one of them before the type
-check. In CI, run the build first, or cache the generated file with the build
-output.
-
 ## There is no banner
 
 **Check.** In DevTools Network, find the `GET` request to `/init` on your
-backend URL. With the bundled manifest, the browser makes no request before
-the banner unless the policy depends on a country or region it does not know.
+backend URL. With `hosted()`, the browser sends it while the provider first
+renders. With a bundled `manifest()`, the browser makes no request before the
+banner unless the policy depends on a country or region it does not know.
 
 | What you see                    | Cause                                                                                                                         | Fix                                                                                                                                                               |
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -44,6 +22,82 @@ A policy with `prompt: 'none'` shows no banner by design, and so does a
 returning visitor with a valid stored choice. [Policies](../../concepts/policies.md)
 explains why a region may not show one.
 
+## Why does the build fail to download the manifest?
+
+**Check.** `vite build` stops with an error from `consentManifest` that
+starts with the plugin's name, such as
+`@c15t/core/build: could not fetch the consent manifest from <url> during the
+build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite`
+for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps
+going. The part in parentheses names the cause:
+
+| Message                                                                   | Cause                                                                                                                           | Fix                                                                           |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error | The build cannot reach the backend                                                                                              | Build where the backend is reachable                                          |
+| `no response within 10 seconds`                                           | The backend did not answer in time                                                                                              | Check the backend, or build where it is reachable                             |
+| `/manifest responded 404`                                                 | 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, or set `VITE_C15T_BACKEND_URL` |
+| `/manifest returned an invalid consent manifest.`                         | The URL answered with something other than a consent manifest, such as an HTML page                                             | Point `backendURL` at the backend itself, not your site or a dashboard page   |
+
+A failed download never reuses an old snapshot. To deploy while the backend
+is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
+`undefined`, and the browser fetches the policy from the backend at runtime.
+
+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.
+
+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
+`VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass the absolute backend URL from your Inth
+project. The [troubleshooting guide](../../guides/troubleshooting.md#why-does-the-build-fail-to-download-the-manifest)
+lists every message.
+
+A notice that the build `skipped the consent manifest fetch` means the backend
+URL is relative, such as `/api/c15t`. Pass the absolute backend URL instead.
+With `onBuildError: 'fail'`, this stops the build with `build-time manifests
+require an absolute upstream URL`.
+
+## Why is snapshot undefined?
+
+**Check.** `snapshot` from `c15t/generated` is `undefined`, and the browser
+requests `${backendURL}/manifest` on page load.
+
+**Fix.** `snapshot` is `undefined` when Vite has no policy to serve:
+
+* `consentManifest` is missing from `plugins` in `vite.config.ts`. Without the
+  plugin, `c15t/generated` still resolves, but exports `undefined`.
+* The fetch failed in `vite dev`, or in a build with
+  `C15T_ON_BUILD_ERROR=runtime`. The terminal shows a `could not fetch the
+  consent manifest` warning.
+* The backend URL is relative, so the plugin skipped the fetch.
+* `consentManifest({ source: 'runtime' })` is set, so the plugin never
+  fetches.
+
+Fix the cause, then restart `vite dev` or rebuild. The plugin fetches once
+when Vite starts.
+
+## The page throws that no IABProvider is mounted
+
+The visitor's policy uses the `iab` model and the backend sent its vendor
+list, but no `IABProvider` is mounted. The standard banner and dialog do
+not handle the IAB model, so they throw rather than leave the visitor
+with no consent UI. Server and browser render the same error.
+
+Fix it one of two ways:
+
+* If the site uses IAB TCF, render `IABProvider` with `IABConsentBanner`
+  and `IABConsentDialog` from `c15t/react/iab` inside your consent
+  provider. They can sit next to the standard banner.
+* If it does not, remove the `iab` model from the policy for that region
+  in your Inth project or policy pack.
+
+A backend that answers `gvl: null` turns IAB off for that request. The
+policy then runs as opt-in and nothing throws.
+
+The check passes once `c15t/react/iab` has loaded. If you import the IAB
+components with a dynamic `import()`, a render of the standard banner
+that happens before the import finishes still throws.
+
 ## Inspect the active policy
 
 Render this component inside `ConsentProvider`. It reads state and records no
@@ -91,13 +145,27 @@ covers the options.
 ## The banner has no styles
 
 **Check.** In DevTools Elements, the banner has classes but no rules apply.
-
-**Fix.** Import `c15t/react/styles.css` once in the module that renders the
-provider. With Tailwind 3, keep that import above the `@tailwind` directives
-and add `c15t/postcss-tailwind3` before `tailwindcss` in your PostCSS
-config. Without the plugin, Tailwind 3 drops c15t's rules or fails the build
-with `` `@layer components` is used but no matching `@tailwind components` directive is present ``.
-See [Tailwind CSS](../../customization/tailwind.md#set-up-tailwind-css-3).
+Look for c15t's `<style>` element: `<style data-href="c15t-first-paint">` in
+`<head>` on React 19, or `<style data-c15t-styles>` next to the banner on
+React 18 or with a `nonce`. Check the console for a Content Security Policy
+error.
+
+**Fix.**
+
+* No c15t `<style>` element: the provider sets `styles: false` or `noStyle`.
+  With `styles: false`, import `c15t/react/styles.css` once in the module
+  that renders the provider.
+* The console reports a blocked inline style: set the provider's `nonce`, as
+  [Content Security Policy](./content-security-policy.md)
+  shows.
+* Under Tailwind 3, buttons lose their padding and cards their borders:
+  Tailwind 3's unlayered preflight beats c15t's layered rules. Set
+  `styles: false`, import `c15t/react/styles.css` above the `@tailwind`
+  directives and add `c15t/postcss-tailwind3` before `tailwindcss` in your
+  PostCSS config. Without the plugin, Tailwind 3 drops c15t's rules or fails
+  the build with
+  `` `@layer components` is used but no matching `@tailwind components` directive is present ``.
+  See [Tailwind CSS](../../customization/tailwind.md#set-up-tailwind-css-3).
 
 ## The console warns that theme tokens are no longer turned into CSS
 

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

@@ -6,8 +6,6 @@ description: Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers
 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.
@@ -15,15 +13,15 @@ Paste into Claude Code, Codex, Cursor or another coding agent at the root of you
 ```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.
+Read ./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.
+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.
 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.
+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>.
 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.
@@ -34,33 +32,35 @@ When you finish, list the files you changed, anything you could not migrate, and
 * 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).
+  [Upgrade a self-hosted backend](https://c15t.com/docs/self-host/upgrade-v3).
   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.
+Remove `@c15t/react` and `@c15t/scripts`, then install `c15t`.
+
+| Package manager | Command                               |
+| :-------------- | :------------------------------------ |
+| npm             | `npm install c15t @c15t/integrations` |
+| pnpm            | `pnpm add c15t @c15t/integrations`    |
+| yarn            | `yarn add c15t @c15t/integrations`    |
+| bun             | `bun add c15t @c15t/integrations`     |
 
-| 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` if you don't use its vendor helpers.
 
-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`                | Nothing: remove the import. Keep `c15t/react/styles.css` only with `styles: false` |
+| `DevTools` from `@c15t/dev-tools/react` | `DevTools` from `c15t/react/devtools`                                              |
+| `@c15t/scripts/*`                       | `@c15t/integrations/*`                                                             |
 
-| 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/*`                |
+The `packages-to-c15t` codemod rewrites the `@c15t/react` imports and removes
+the stylesheet import. It doesn't edit `package.json`.
 
-`@c15t/react` is still published at v3, so its imports keep working if you pin
-it to `@alpha`. These docs use `c15t/react`.
+`@c15t/react` is still published at v3, so its imports keep working after you
+upgrade it. 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.
@@ -68,15 +68,14 @@ Every v3 package ships ESM only. If a CommonJS file in your app calls
 ## 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:
+from your dependencies and install `@c15t/integrations`:
 
-| 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`     |
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
 
 Replace the package name in each import. Vendor subpaths and helper names stay
 the same.
@@ -98,11 +97,11 @@ 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.
+`googleTagManager` or `posthog`, now logs an error and skips its script 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
@@ -112,7 +111,7 @@ 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
+npx @c15t/cli codemods scripts-to-integrations --dry-run --json
 ```
 
 Review the output, then run it again without `--dry-run`. The codemod runs
@@ -127,7 +126,7 @@ 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
+npx @c15t/cli 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 +226,7 @@ a transport as `mode`:
 
 | v2 option                                | v3 option                                                                                                      |
 | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `mode: 'hosted'` with `backendURL`       | `mode: hosted({ url })`                                                                                        |
+| `mode: 'hosted'` with `backendURL`       | `mode: hosted({ backendURL })`                                                                                 |
 | `mode: 'offline'` with `offlinePolicy`   | `mode: offline({ policyRules })`                                                                               |
 | `mode: 'custom'` with `endpointHandlers` | `mode: custom(transport)`, where `transport` implements the v3 transport interface. `endpointHandlers` throws. |
 
@@ -236,7 +235,7 @@ import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/reac
 
 // Replace ConsentManagerProvider:
 <ConsentProvider
-  options={{ mode: hosted({ url: 'https://your-project.c15t.dev' }) }}
+  options={{ mode: hosted({ backendURL: 'https://your-project.c15t.dev' }) }}
 >
 ```
 
@@ -245,7 +244,7 @@ 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
+npx @c15t/cli codemods consent-provider-options --dry-run --json
 ```
 
 Keep your backend URL. An existing hosted URL such as
@@ -254,6 +253,13 @@ 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.
 
+The quickstart keeps `hosted()` and adds `consentManifest()` from
+`c15t/build` to `vite.config.ts`. `hosted()` then reads the backend URL from
+`VITE_C15T_BACKEND_URL`, so it needs no arguments. v3 also adds `manifest()`,
+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
 recommended for production environments.
 
@@ -279,7 +285,7 @@ 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
+npx @c15t/cli codemods callbacks-to-v3 --dry-run --json
 ```
 
 v2's `onConsentChanged` fired only when a save changed at least one category's
@@ -336,6 +342,9 @@ const mode = offline({
 });
 ```
 
+In Next.js, import `offline` from `c15t/next` instead and set the result as
+`mode` in `c15t.config.ts`. Both take the same `policyRules`.
+
 | v2 preset                                 | v3 preset               |
 | ----------------------------------------- | ----------------------- |
 | `europeOptIn()`, `europeIab()`            | Same names              |
@@ -362,25 +371,25 @@ 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).                                                              |
+| v2                                                                                                 | v3                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `translations`                                                                                     | `i18n`                                                                                                                                             |
+| `backendURL`, `mode: 'hosted'`                                                                     | `mode: hosted({ backendURL })` from `c15t/react` on `ConsentProvider`. Next.js `ConsentRoot`: `NEXT_PUBLIC_C15T_BACKEND_URL` and `c15t.config.ts`. |
+| `ssrData` (Next.js)                                                                                | `ConsentRoot` with `state` from `resolveConsent()`                                                                                                 |
+| `iframeBlockerConfig`                                                                              | `iframeBlocker`, or `false` to turn it off                                                                                                         |
+| `Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, `FrameProps`                                    | `ConsentGate` and its parts. The `Frame` names still work as deprecated aliases and log a one-time warning outside production.                     |
+| `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
@@ -389,7 +398,7 @@ 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
+npx @c15t/cli codemods consent-provider-options translations-to-i18n --dry-run --json
 ```
 
 `ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
@@ -417,7 +426,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@alpha codemods root-exports-to-subpaths --dry-run --json
+npx @c15t/cli codemods root-exports-to-subpaths --dry-run --json
 ```
 
 `ConsentGate` changes one behavior from `Frame`. When its category is granted,
@@ -448,16 +457,25 @@ A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
 
 ### 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).
+* Remove the c15t stylesheet import, such as `@c15t/react/styles.css` or
+  `@c15t/nextjs/styles.css`. The stock components in `c15t/react`,
+  `c15t/next` and `c15t/tanstack-start` render the rules they use as
+  `<style>` elements, so no stylesheet request holds back the first paint. An
+  import you keep still styles the components, but the rules ship twice and
+  the stylesheet still delays the first paint.
+* Keep an import of the v3 stylesheet, such as `c15t/react/styles.css`, only
+  with Tailwind CSS 3 or a named cascade layer, and set
+  `styles: false` in the provider options so the components add no second
+  copy. See
+  [stylesheets and CSS layers](../../customization/stylesheets.md#import-the-stylesheet-yourself).
+  The `packages-to-c15t` codemod removes `@c15t/react` and `@c15t/nextjs`
+  stylesheet imports. With Tailwind CSS 3 or a cascade layer it keeps them,
+  pointed at `c15t`, with a `TODO(c15t v3)` comment.
+* With manual styles, `iab/styles.css` no longer repeats the default tokens.
+  Import it after `styles.css`. Automatic IAB styling needs neither import.
+* Tailwind CSS 3 needs a PostCSS plugin for c15t's `styles.css`. Add
+  `'c15t/postcss-tailwind3': {}` before `tailwindcss` in `postcss.config`,
+  and set `styles: false`. 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.
@@ -480,7 +498,7 @@ The `css-variables-to-v3` codemod renames `--consent-widget-*` and
 `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
+npx @c15t/cli 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
@@ -503,8 +521,8 @@ 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
+and `save()`. If your app depends on `@c15t/iab` directly, upgrade it to v3
+too, on the same release as `c15t`. Remove it if
 `IABProvider` now covers everything you used it for.
 
 Server integrations now send a reference to the Global Vendor List instead of
@@ -568,9 +586,45 @@ 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
+npx @c15t/cli codemods dev-tools-to-c15t --dry-run --json
 ```
 
+## Upgrade from an earlier v3 alpha
+
+The v3 alphas renamed and removed APIs that never shipped in a stable release.
+Names that were in stable v2 keep a deprecated alias. Every other renamed name
+is removed with no alias, so a build that still uses one fails to type-check
+or throws at runtime.
+
+### Deprecated, still working
+
+Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside
+production, log a one-time warning such as
+``c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead.``
+
+| Package                                          | Deprecated                                                                   | Use instead                                         |
+| ------------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------- |
+| `c15t/react`, `c15t/next`, `c15t/tanstack-start` | `Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, and the `FrameProps` type | `ConsentGate` and its parts, and `ConsentGateProps` |
+
+v2's `ConsentManagerProvider` and string modes such as `mode: 'hosted'` are
+handled by the `consent-provider-options` codemod, not by aliases.
+
+### Removed
+
+| Removed                                                                    | Use instead                                                                                                             |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `hosted({ url })`                                                          | `hosted({ backendURL })`, or the framework's backend URL variable                                                       |
+| `createManifestTransport({ manifest })`                                    | `createManifestTransport({ snapshot })`                                                                                 |
+| `assertDecisionInputs` defaulting to `false` on `hosted()`                 | It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.                                       |
+| `hostedModes` from `c15t/runtime/provider`                                 | `readHostedMode(mode)`                                                                                                  |
+| `buildManifest: true` in Astro and Nuxt                                    | `onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`. |
+| A generated `c15t-manifest.ts` and its `.gitignore` entry                  | `import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.                                      |
+| 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/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