@c15t/react 3.0.0-alpha.9 → 3.0.0

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,60 @@ 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

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,22 +32,21 @@ 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@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`     |
+| 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`     |
 
-Drop `@c15t/integrations@alpha` if you don't use its vendor helpers.
+Drop `@c15t/integrations` if you don't use its vendor helpers.
 
 | v2 import                               | v3 import                                                                          |
 | --------------------------------------- | ---------------------------------------------------------------------------------- |
@@ -59,8 +56,11 @@ Drop `@c15t/integrations@alpha` if you don't use its vendor helpers.
 | `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`.
+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 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,
@@ -459,6 +468,9 @@ A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
   `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
@@ -486,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
@@ -509,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
@@ -574,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

package/docs/guides/banner-experiments.md

@@ -32,7 +32,7 @@ import type { ReactNode } from 'react';
 
 import { scripts } from './scripts';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = hosted({ backendURL: 'https://your-project.inth.app' });
 
 // `control` is the stock banner. `wall` blocks the page until the visitor
 // chooses.
@@ -256,7 +256,6 @@ import { resolveConsent } from 'c15t/next/server';
 import { Suspense } from 'react';
 import type { ReactNode } from 'react';
 
-import { consentOptions } from '@/c15t.server';
 import { ExperimentConsent } from '@/components/experiment-consent';
 import { bannerExperiment } from '@/lib/experiment';
 import { bannerExperimentFlag } from '@/lib/flags';
@@ -266,7 +265,6 @@ import '@/styles/globals.css';
 const ResolvedConsent = async ({ children }: { children: ReactNode }) => {
 	const arm = await bannerExperimentFlag();
 	const state = await resolveConsent({
-		...consentOptions,
 		// `off` keeps this visitor out of the experiment.
 		experiment: arm === 'off' ? undefined : { ...bannerExperiment, arm },
 	});
@@ -399,6 +397,22 @@ arm re-assigns only the visitors who were in it. For a clean analysis, change
 Built-in assignment is not available in Astro; see
 [Astro](#astro).
 
+A Vite app's early `/init` script, from `consentManifest()`, picks the arm
+the same way when you pass it the experiment, and the app then runs that
+arm. Import the same object into `vite.config.ts`:
+
+```ts title="vite.config.ts"
+consentManifest({ initPrefetch: { experiment: bannerExperiment } });
+```
+
+Without it, the app sends its own `/init` for visitors who have not chosen
+yet. The same goes for `consentPrefetchHead` in TanStack Start and
+`buildPrefetchScript` elsewhere, which take the same `experiment` option.
+
+When a feature flag picks the arm, leave `experiment` out of
+`initPrefetch`. The script would pick its own arm and send it to the
+backend, and the app would then send a second `/init` with the flag's arm.
+
 ## Acknowledge presentation diagnostics
 
 Each arm is resolved under the visitor's policy the same way `presentation`
@@ -492,11 +506,12 @@ owed to, and how many of them accepted. c15t sends both to the backend on
 its own; you do not wire anything up.
 
 * **Visitors owed the banner.** While a visitor has no stored choice, every
-  `/init` carries their arm in an `x-c15t-experiment: <id>=<arm>` header,
-  and the backend puts it on that request's session report as
+  `/init` carries their arm as `<id>=<arm>` in the `experiment` query
+  parameter, and the backend puts it on that request's session report as
   `experiment: { id, arm }`. In manifest mode, the server render or the
   init route puts it on the report it sends to `POST /sessions`. A visitor
-  who already chose is not shown the banner, so is not counted.
+  who already chose is not shown the banner, so is not counted. A
+  server-to-server caller can send the `x-c15t-experiment` header instead.
 * **Choices.** Every choice saved through `POST /subjects` carries the arm
   in `metadata.experiment`, as above.