@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/upgrade-v3.md

@@ -1,381 +1,517 @@
 ---
-title: Upgrade to v3 policies
-description: Migrate policy configuration, consent records, callbacks, and
-  custom transports to the v3 policy system.
+title: Migrate to v3
+description: Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React
+  providers, the JavaScript runtime, custom UI built on useConsentManager,
+  callbacks, policies, stored consent and a self-hosted backend.
 group: reference
 ---
 
-## React version requirement
+## What changes in v3
+
+* One package, `c15t`, replaces `@c15t/nextjs`, `@c15t/react` and the v2
+  `c15t` store. Import from its subpaths: `c15t/next`, `c15t/react`, and `c15t`
+  for the headless engine.
+* The vendor helpers move from `@c15t/scripts` to `@c15t/integrations`, with
+  the same subpaths and helper names.
+* `ConsentManagerProvider` becomes `ConsentProvider` in React. Next.js apps
+  that resolve consent on the server use `ConsentRoot`.
+* `mode` and `backendURL` become one transport, `hosted({ url })` or
+  `offline()`.
+* Policy packs become policy rules. You set them in your Inth project, in a
+  self-hosted backend's `manifest.policyRules`, or in `offline({ policyRules })`.
+* `useConsentManager()` is gone. Each field has its own hook, and a codemod
+  rewrites most calls.
+* Callbacks have new names, and each reports either a recorded choice or a
+  permission change.
+* Visitors' existing choices keep working. v3 reads the v2 cookie.
+* A self-hosted backend takes `database` instead of `adapter`, and needs a
+  schema migration.
+* `@c15t/node-sdk` has a new client, `createC15tClient()`. Its methods return
+  results instead of throwing, and it reads no environment variables.
+
+## Upgrade in this order
+
+1. Upgrade React and React DOM to 18 or newer. The v3 React and Next.js
+   adapters require them, and `c15t/next` requires Next.js 15 or 16.
+2. [Replace the packages](#replace-the-packages), including the
+   [integrations dependency](#rename-the-integrations-dependency).
+3. Run the [`useConsentManager()` codemod](#replace-useconsentmanager) if your
+   code calls it.
+4. Replace the provider for your framework: [Next.js](#nextjs-with-consentmanagerprovider),
+   [React](#react-with-consentmanagerprovider) or [JavaScript](#javascript-with-getorcreateconsentruntime).
+5. Update [callbacks](#replace-callbacks), [policies](#move-policy-packs-to-policy-rules)
+   and [other options](#rename-options-and-components).
+6. If you self-host, [upgrade the backend](#upgrade-a-self-hosted-backend) in the
+   same release as the clients.
+7. If server code calls the API, [update the Node.js SDK](#update-the-nodejs-sdk).
+8. [Check the result](#check-the-migration).
+
+## Replace the packages
+
+Remove `@c15t/nextjs` and `@c15t/react`, 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 do not use its vendor helpers.
+
+| v2 import                                          | v3 import                                                                                                                                       |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@c15t/nextjs`                                     | `c15t/next`. Server helpers are in `c15t/next/server`, `c15t/next/pages` and `c15t/next/api`.                                                   |
+| `@c15t/react`                                      | `c15t/react`                                                                                                                                    |
+| `@c15t/react/headless`                             | `c15t/react/headless`                                                                                                                           |
+| `@c15t/nextjs/styles.css`                          | `c15t/next/styles.css`                                                                                                                          |
+| `@c15t/react/styles.css`                           | `c15t/react/styles.css`                                                                                                                         |
+| `c15t` (`getOrCreateConsentRuntime` and the store) | `c15t` for the engine and `c15t/runtime` for a managed runtime. The APIs are new; see [JavaScript](#javascript-with-getorcreateconsentruntime). |
+| `DevTools` from `@c15t/dev-tools/react`            | `DevTools` from `c15t/react/devtools` or `c15t/next/devtools`                                                                                   |
+| `@c15t/scripts/*`                                  | `@c15t/integrations/*`, with unchanged helper names. See [rename the integrations dependency](#rename-the-integrations-dependency).             |
+
+The scoped packages `@c15t/nextjs`, `@c15t/react` and `@c15t/core` still exist
+at v3, so imports from them keep working if you pin them to `@alpha`. The docs
+use the `c15t` subpaths.
+
+## 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 and earlier v3 alphas:
 
-The v3 React and Next.js adapters require React and React DOM 18 or newer.
-Upgrade both packages together before installing v3. Earlier alpha peer ranges
-incorrectly allowed React 16 and 17 even though v3 already uses `useId` and
-`useSyncExternalStore`, which those versions do not provide.
+```ts
+import { createEventDispatcher } from '@c15t/scripts/events';
+import { posthog } from '@c15t/scripts/posthog';
+```
 
-## Start with a policy rule
+After:
 
 ```ts
-import { policyRulePresets } from '@c15t/schema';
-import { offline } from '@c15t/react';
+import { createEventDispatcher } from '@c15t/integrations/events';
+import { posthog } from '@c15t/integrations/posthog';
+```
 
-const mode = offline({
-	policyRules: [policyRulePresets.europeOptIn()],
-});
+The `scripts` configuration option and the `Script` type keep their names.
+`@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
 ```
 
-Pass `mode` to `ConsentProvider`. For a backend integration, configure
-`policyRules` on the backend and use `hosted({ url })` in the provider. Follow the
-[React quickstart](https://c15t.com/docs/frameworks/react/quickstart),
-[Next.js quickstart](https://c15t.com/docs/frameworks/next/quickstart), or
-[JavaScript quickstart](https://c15t.com/docs/frameworks/javascript/quickstart) for a complete
-integration.
+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.
 
-The CLI no longer offers `offline-add-policy-packs`, which generated v2
-configuration. For offline integrations, configure `offline({ policyRules })`
-as shown above.
+## Replace `useConsentManager()`
 
-Replace legacy `policyPacks` and nested `consent` configuration with rules:
+`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:
 
-```ts
-import type { PolicyRule } from '@c15t/schema';
-
-const policyRules = [
-	{
-		id: 'default-opt-in',
-		match: { fallback: true },
-		model: 'opt-in',
-		prompt: 'choice',
-		categories: ['measurement', 'marketing'],
-		scopeMode: 'strict',
-	},
-] satisfies PolicyRule[];
+```bash
+npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
 ```
 
-`model` controls permission defaults. `prompt` controls whether the visitor must
-make a choice, dismiss a notice, or see no prompt. Opt-in and IAB models require
-`prompt: 'choice'`. Opt-out supports `choice`, `notice`, and `none`. The `none`
-model permits optional categories in scope, allows only `prompt: 'none'`, owes
-no rights, and renders no consent UI. v2's `none` model maps to it directly.
-
-When `categories` selects only some optional categories, you must set
-`scopeMode` explicitly. A strict scope blocks categories outside the rule. A permissive scope allows
-those categories unless another restriction applies. An omitted scope, `['*']`,
-or a list containing only `necessary` expands to the default optional categories.
-`necessary` is always permitted.
-
-`offline()` without `policyRules` resolves `recommendedPolicyRules()`, whose
-Europe rule also matches a visitor with no country. A known US country with a
-missing state uses US opt-out with GPC and persistent preferences; a missing
-Canadian province stays strict opt-in. The last rule is `none` for other known
-unmatched locations. Resolution exposes `matched`, `no-match`,
-`unconfigured`, or `failed`; while nothing has matched, optional categories stay
-denied and no consent surface renders. A missing or malformed policy never grants
-optional permissions by itself.
-
-## Read the state you need
-
-| Purpose                                         | Snapshot field         | React hook                              |
-| ----------------------------------------------- | ---------------------- | --------------------------------------- |
-| Gate scripts and optional features              | `effectivePermissions` | `useConsent(category)`, `useConsents()` |
-| Inspect recorded choices and confirmation times | `explicitChoice`       | `useExplicitChoice()`                   |
-| Decide whether to prompt                        | `promptRequirement`    | `usePromptRequirement()`                |
-| Inspect the resolved rule                       | `policyRule`           | `usePolicyRule()`                       |
-| Inspect matching or failure                     | `resolution`           | `usePolicyResolution()`                 |
-
-An effective permission is not evidence of a grant. Under an opt-out rule it can
-be true before a visitor acts. A notice dismissal updates `noticeDismissal` and
-does not record consent. Global Privacy Control updates privacy signals and
-configured opt-out directives without turning a browser signal into a choice.
-
-## Replace choice callbacks
-
-```tsx
+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 every v2 field.
+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')`                                      | `useHeadlessConsentUI().saveCustomPreferences()`, which saves the draft                    |
+| `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 the draft of the nearest
+`ConsentDraftProvider`. When one component stages choices and another saves
+them, render both inside the same `ConsentDraftProvider`; otherwise the save
+commits nothing you staged. `ConsentWidget` already includes one. The codemod
+adds a `TODO(c15t v3)` comment where this applies.
+
+## Next.js with `ConsentManagerProvider`
+
+A typical v2 App Router app wrapped the layout in a client component:
+
+```tsx title="Before (v2): components/consent-manager/provider.tsx"
+'use client';
+
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentManagerProvider,
+} from '@c15t/nextjs';
+
+export default function ConsentManagerClient({ children }) {
+	return (
+		<ConsentManagerProvider
+			options={{ mode: 'hosted', backendURL: 'https://your-project.c15t.dev' }}
+		>
+			<ConsentBanner />
+			<ConsentDialog />
+			{children}
+		</ConsentManagerProvider>
+	);
+}
+```
+
+v3 gives you two ways forward:
+
+* **Resolve consent on the server** (recommended). The server reads the
+  visitor's policy and stored choice, so gated scripts can start right after
+  hydration and the banner can be in the first HTML. Replace the client
+  component with `ConsentRoot`, pass it `resolveConsent()` from
+  `c15t/next/server` as `state` and your `defineConsentConfig()` result as
+  `config`, and add the manifest route. Follow the
+  [App Router guide](https://c15t.com/docs/frameworks/next/app-router) or the
+  [Pages Router guide](https://c15t.com/docs/frameworks/next/pages-router). This replaces v2's
+  `fetchInitialData()`, `ssrData` and `C15tPrefetch`.
+* **Keep browser initialization**, as v2 did without `fetchInitialData()`. Keep
+  your client component, import from `c15t/next`, and change the provider:
+
+```tsx title="After (v3): components/consent-manager/provider.tsx, changed lines"
+import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/next';
+
+// In the component, replace ConsentManagerProvider:
 <ConsentProvider
-	options={{
-		mode,
-		callbacks: {
-			onChoiceRecorded(event) {
-				console.log('Visitor recorded a choice', event);
-			},
-			onPermissionsChanged(event) {
-				console.log('Effective permissions changed', event);
-			},
-		},
-	}}
+  options={{ mode: hosted({ url: 'https://your-project.c15t.dev' }) }}
 >
-	{children}
-</ConsentProvider>
 ```
 
-Replace `onConsentSet` with `onChoiceRecorded` for explicit accept, reject, or
-save actions. Use `onPermissionsChanged` for permission changes caused by a
-choice, expiry, policy update, or privacy signal. Provider callbacks no longer
-include `onBannerFetched`; use the resolved policy and pending state to render
-loading UI.
-
-Only `kernel.commands.save()` creates an explicit choice. `save('all')` accepts,
-`save('none')` rejects, and `save({ marketing: false })` confirms only marketing.
-A partial save keeps the other categories' confirmation times. Use
-`commands.dismissNotice()` for the notice action and `kernel.hydrate()` to apply
-validated records without recording an action.
-
-## Keep existing storage
-
-The reader accepts valid v2 storage and translates it into per-category receipts.
-It does not rewrite storage on startup. Existing denials continue to restrict
-permissions; expired or incompatible positive receipts cannot restore grants.
-The next explicit action writes the v3 record. Notice dismissal and privacy
-opt-out directives have separate records.
-
-Pass server-prepared `initialRecords`, `initialPolicyResolution`, and `now`
-through the adapter's prefetch configuration. Do not rebuild consent from a
-boolean `hasConsented` or copy effective permissions into explicit choice records.
-Pending prefetch results cannot restore records after a clear or overwrite a
-newer choice.
-
-## Update custom transports and backend clients
-
-Use `KernelTransport` from `@c15t/core/transports`. Init returns a versioned
-`policyResolution` with a matched rule and fingerprints, or an explicit
-non-matched outcome. Use `mapInitOutputToInitResponse` for an HTTP init payload.
-Do not return legacy `policy` or `policyDecision` fields.
-
-Save requests contain the explicit choice and the categories confirmed by this
-action. Return a `SaveResult` with `ok`; optional identity and record methods
-must preserve the same receipt format. Forward the policy contract headers when
-implementing an HTTP proxy. Keep client, schema, backend, and framework adapters
-on compatible v3 versions.
-
-Use the supplied hosted or manifest transports to capture policy evidence for
-saves and retries. They preserve the action's policy, location, language, and
-privacy signal inputs. A stale policy assertion is an error; it must not silently
-save under a different rule. See the
-[backend endpoint reference](https://c15t.com/docs/self-host/api/endpoints) for wire fields.
-
-## Shared runtime ownership
-
-Astro and SvelteKit can create a runtime outside a component tree with
-`createConsentRuntime` from `@c15t/core/runtime`. Pass that runtime to a
-framework provider with its `runtime` prop. The owner calls `start()` after
-mount and `dispose()` when the page no longer needs it. Borrowing providers
-subscribe to the kernel and render UI without initializing or disposing it.
-
-Runtime construction preserves the prepared server snapshot. Storage reads,
-privacy-signal activation and script loading begin on `start()`. Pass server
-records through `prefetch.initialRecords` with their evaluation time to keep
-the first browser render consistent with the server. `runtime.clearRecords()`
-clears both persisted and in-memory records.
-
-Runtime callbacks use `onChoiceRecorded`, `onPermissionsChanged` and
-`onError`. Hydrating records does not report a new visitor choice.
-
-Astro's serializable offline descriptor accepts `policyRules`, just like the
-other adapters' offline factories. Configure a preset or explicit rules;
-omitting them keeps the conservative fallback.
-
-## Presentation corrections
-
-Use `blocking` for backdrop, scroll locking and focus trapping together.
-Choice banners default to non-blocking, choice walls always block, and notices
-never block. A notice configured as a wall falls back to a floating card.
-Preferences remain centered; `variant` and `position` apply only to prompts.
-
-Replace reads of `uncoveredRights` with `preferenceControls`. The latter is a
-list of additional preferences buttons recommended for the stock UI. It does
-not verify disclosure or persistent access to policy rights.
-
-Notice acknowledgement uses `common.acknowledge`, falling back to
-`common.dismiss` for older translation bundles. It does not record a choice.
-
-## Astro notice acknowledgement
-
-```astro
----
-import ConsentBanner from '@c15t/astro/components/consent-banner.astro';
----
+Static exports use browser initialization too. See
+[static export](https://c15t.com/docs/frameworks/next/static-export) and
+[client-side setup](https://c15t.com/docs/frameworks/next/client-side).
+
+Either way, change the stylesheet import to `c15t/next/styles.css`, and 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
+[CLI setup command](https://c15t.com/docs/cli/quickstart) can generate the browser-initialized
+version for you.
+
+## React with `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. |
+
+`hosted` and `offline` are exported from `c15t/react`. The
+[React quickstart](https://c15t.com/docs/frameworks/react/quickstart) shows the full provider.
+[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.
+
+## JavaScript with `getOrCreateConsentRuntime`
+
+v2's `getOrCreateConsentRuntime()`, `configureConsentManager()` and the
+Zustand `consentStore` are gone. v3 has two replacements:
+
+* `createConsentKernel()` from `c15t`, with `createHostedTransport()`. You read
+  `kernel.getSnapshot()`, listen with `kernel.subscribe()`, and save with
+  `kernel.commands.save('all' | 'none' | { marketing: false })`. See the
+  [JavaScript quickstart](https://c15t.com/docs/frameworks/javascript/quickstart).
+* A script tag that includes the stock banner, for sites without a build
+  step. See [script tag](https://c15t.com/docs/frameworks/html/quickstart).
+
+v3 also adds adapters for TanStack Start, Nuxt, Vue, Astro, Svelte and
+SvelteKit. If you wired the v2 runtime into one of these frameworks, move to its
+adapter from [Choose your setup](./concepts/choose-your-setup.md).
+
+## Replace callbacks
+
+Callbacks stay under `options.callbacks`, 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 provider callback. Read `usePolicyResolution()` to know when the policy has resolved.                                  |
+| `onError`, `onBeforeConsentRevocationReload` | Unchanged                                                                                                                 |
+
+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`. To act only on a real change, keep the last
+`snapshot.explicitChoice` you saw and compare it.
+
+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.
+
+```tsx title="After (v3): provider 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:
 
-<ConsentBanner dismissButtonText="Got it" />
+* **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 { policyRulePresets } from 'c15t';
+import { offline } from 'c15t/react';
+
+const mode = offline({
+	policyRules: [policyRulePresets.europeOptIn(), policyRulePresets.worldNone()],
+});
 ```
 
-Astro's `ConsentBanner` accepts `dismissButtonText` as an optional string. It
-labels the notice acknowledgement button, which defaults to
-`common.acknowledge` and falls back to `common.dismiss` in older translation
-bundles. Acknowledging a notice preserves the visitor's consent choices.
-
-## IAB blocking behavior
-
-IAB banners and dialogs use the same `presentation.prompt.blocking` and
-`presentation.preferences.blocking` settings as the other consent components.
-A blocking surface shows a backdrop, traps focus and locks page scrolling.
-Explicit `blocking` values take precedence over deprecated `scrollLock` and
-`trapFocus` options. IAB components stay hidden without a matched policy,
-including when a dialog receives `open={true}`.
-
-The React consent dialog still blocks pointer interaction with the page when
-`blocking` is true and you hide its backdrop with `overlay={false}`.
-
-Legacy prompt options now control the whole blocking behavior. For example,
-`scrollLock: true` alone enables a backdrop and focus trapping as well as
-scroll locking. Set `blocking: false` explicitly for a non-modal banner.
-
-Custom dialog backdrops follow the same rule. A dialog resolved as non-blocking
-omits both the default backdrop and a supplied `overlay`. To retain a custom
-backdrop when migrating from `trapFocus: false`, set
-`presentation.preferences.blocking: true` and keep your `overlay` prop.
-
-## Next.js and TanStack Start renames
-
-These names changed without deprecated aliases. `defineConsentConfig`,
-`ConsentConfig` (the URL config) and `ConsentProvider` from `@c15t/react` are
-unchanged.
-
-Next.js (`c15t/next`, `c15t/next/server`, `c15t/next/pages`):
-
-| v2                                                                                            | v3                                                         |
-| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `ConsentBoundary`                                                                             | `ConsentRoot`                                              |
-| `ConsentBoundaryProps`                                                                        | `ConsentRootProps`                                         |
-| `config={initialConsent}` (the visitor's resolved state)                                      | `state={...}`                                              |
-| `consent={consentConfig}` (the `defineConsentConfig` result)                                  | `config={consentConfig}`                                   |
-| `prefetchInitialConsent(options)`                                                             | `resolveConsent(options)` with `config` or `backendURL`    |
-| `readInitialConsentConfig(options)`                                                           | `resolveConsent(options)` without `config` or `backendURL` |
-| `InitialConsentConfig`, and `KernelConfig` where it named the returned value                  | `ConsentState`                                             |
-| `PrefetchInitialConsentOptions`                                                               | `ResolveConsentOptions`                                    |
-| `ReadInitialConsentConfigOptions`                                                             | `ConsentRequestOptions`                                    |
-| Pages Router `readInitialConsentConfig(req, opts)` and `prefetchInitialConsent({ req, ... })` | `resolveConsent({ req, ... })`                             |
-
-TanStack Start (`c15t/tanstack-start`, `c15t/tanstack-start/server`):
-
-| v2                                    | v3                                             |
-| ------------------------------------- | ---------------------------------------------- |
-| `ConsentBoundary`                     | `ConsentRoot`                                  |
-| `config={config}`                     | `state={state}`                                |
-| `ConsentConfig` (the returned state)  | `ConsentState`                                 |
-| `prefetchInitialConsent`              | `resolveConsent(options)` with `backendURL`    |
-| `readInitialConsentConfig`            | `resolveConsent(options)` without `backendURL` |
-| `createConsentConfigHandler(options)` | `createConsentStateHandler(options)`           |
-| `mergeInitIntoConsentConfig`          | `mergeInitIntoConsentState`                    |
-
-`consentLoaderOptions`, `backendURL`, `initRoute` and `DEFAULT_INIT_ROUTE` are
-unchanged.
-
-## `Frame` is now `ConsentGate`
-
-The component that mounts an embed only while its category is allowed is now
-`ConsentGate` in React, Next.js, TanStack Start, Svelte and Vue. The old names
-still work as deprecated aliases and will be removed in a later major release.
-
-| v2                                                                   | v3                                                                           |
-| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `Frame`, `Frame.Root`, `Frame.Title`, `Frame.Button`                 | `ConsentGate`, `ConsentGate.Root`, `ConsentGate.Title`, `ConsentGate.Button` |
-| `FrameProps`, `FrameCompoundComponent`                               | `ConsentGateProps`, `ConsentGateCompoundComponent`                           |
-| `c15t/react/frame`, `c15t/react/components/frame`                    | `c15t/react/consent-gate`, `c15t/react/components/consent-gate`              |
-| Vue `ConsentFrame`, `@c15t/vue/runtime/components/consent-frame.vue` | `ConsentGate`, `@c15t/vue/runtime/components/consent-gate.vue`               |
-
-Props and behavior are unchanged. The placeholder keeps its `frame.*`
-translation keys, `--frame-*` CSS custom properties and
-`data-testid="frame-placeholder"`, so custom copy, styles and tests continue
-to apply.
-
-## Next.js RSC banner removal
-
-The `@c15t/nextjs/rsc` entry (`c15t/next/rsc`) and its `RscConsentBanner`,
-`RscBannerGate` and `RscBannerActions` exports are gone. Imports of that
-entry now fail to resolve. Use the regular banner for server rendering.
-The retained benchmark results showed slightly faster banner visibility and
-interaction for the experimental shell, so this removal should not be read
-as a performance improvement.
-
-Replace `<RscConsentBanner config={config} />` with `<ConsentBanner />` inside
-the same `ConsentRoot`, importing it from `c15t/next` when you use the
-umbrella package or from `@c15t/nextjs` when you depend on the scoped package
-directly. With an awaited `resolveConsent` result, the server renders
-the banner into the response, which is what the RSC variant was for. Move
-`presentation` to `options.presentation` on `ConsentRoot`.
-
-Two defaults differ from the removed shell. It rendered no branding link, so
-pass `hideBranding` to keep that. It also styled only its root and action row
-(through the stock `ConsentBanner.Root` and `PolicyActions`) and left the
-card, title, description, footer and buttons without base classes, whereas
-`ConsentBanner` merges the stock styles into every part. If that changes a
-custom layout, do not reach for `noStyle` on the whole banner, which also
-drops the root positioning and action-row layout the old shell kept; compose
-the compound parts instead and pass `noStyle` only to the parts you styled
-yourself.
-
-`ConsentBanner` has no `classNames` or `children` props. Move each legacy
-`classNames` key to the `ConsentRoot` `options.components` slots, which take
-`{ className }`:
-
-| `classNames` key                                                   | Replacement                                                                                                                                                                                                           |
-| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `root`, `card`, `title`, `footer`                                  | `components.banner.root`, `.card`, `.title`, `.footer`                                                                                                                                                                |
-| `description`                                                      | `components.description.banner`                                                                                                                                                                                       |
-| `rights`, `rightLink`                                              | `components.banner.rights`, `components.banner.rightLink`                                                                                                                                                             |
-| `acceptButton`, `rejectButton`, `customizeButton`, `dismissButton` | No per-button slot. Use `components.button.primary` / `.secondary` for shared styles, or target `[data-action="accept"]`, `[data-action="reject"]`, `[data-action="customize"]` and `[data-action="dismiss"]` in CSS. |
-
-Custom `children`, and any direct use of `RscBannerGate` or
-`RscBannerActions`, map to the compound parts of `ConsentBanner` in a Client
-Component. `RscBannerGate` becomes `ConsentBanner.Root`, which mounts only
-while the policy owes a prompt and reopens on expiry. Remove the gate
-`prompt` and `model` props; the root derives `data-prompt` and `data-model`
-from the `ConsentRoot` policy. Rename `title` to `aria-label` to preserve its
-accessible label. Keep `children`, `className`, `variant`, `position` and
-`blocking` on the root. Add `disableAnimation` and `trapFocus={false}` to
-retain the old gate defaults.
-
-`RscBannerActions`
-becomes `ConsentBanner.PolicyActions`, which renders the rights links and the
-action row the policy requires; `ConsentBanner.Rights`, `RightLink`, `Footer`,
-`FooterSubGroup` and the four buttons are available for finer control.
-`PolicyActions` takes none of the old `acceptLabel`, `rejectLabel`,
-`customizeLabel`, `dismissLabel`, `rightLabels` or `classNames` props: set
-labels through the provider `i18n` translation overrides (`common.acceptAll`,
-`common.rejectAll`, `common.customize`, `common.acknowledge`, `rights.*`), or
-render `ConsentBanner.AcceptButton` and the other buttons with your own
-children; `renderAction` on `PolicyActions` replaces one button; classes move
-to the `components` slots listed in the table. Place the former `children`
-inside `ConsentBanner.Card`:
-
-```tsx title="components/banner.tsx"
-'use client';
+| v2 preset                                 | v3 preset     |
+| ----------------------------------------- | ------------- |
+| `europeOptIn()`, `europeIab()`            | Same names    |
+| `californiaOptIn()`, `californiaOptOut()` | Same names    |
+| `quebecOptIn()`                           | Same name     |
+| `worldNoBanner()`                         | `worldNone()` |
+
+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                                                                                                                           |
+
+`ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
+and `ConsentWidget` keep their names. The `scripts`, `networkBlocker`,
+`legalLinks`, `overrides`, `theme` and `colorScheme` options keep theirs too.
+
+## 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 while it
+is within the policy's validity period and the policy has not changed since the
+visitor chose. Otherwise c15t asks again. Do not copy permissions into new
+records yourself; c15t decides which v2 choices still count.
+
+## Upgrade a self-hosted backend
+
+Deploy the v3 backend and the v3 clients in the same release. A v3 client
+cannot read a v2 backend's `/init` response. Policy resolution fails, optional
+categories stay denied and no banner appears.
+
+1. Install `@c15t/backend@alpha` and the SQL driver for your database.
+2. Replace `adapter` with `database` in your config. The Drizzle, Prisma,
+   TypeORM and Kysely adapters are gone; point `database` at the same SQL
+   database instead. MongoDB has no migration path.
+3. Move `policyPacks`, `branding`, `iab` and `appName` under `manifest`, and
+   rename `policyPacks` to `policyRules`.
+4. Back up the database, then plan and apply the schema migration:
+
+```bash
+npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --plan
+npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply
+```
+
+The migrator recognizes the v2 schema, adopts it, and adds the v3 tables and
+columns. [Database setup](https://c15t.com/docs/self-host/guides/database-setup#upgrade-a-v2-backend)
+covers the details, and the [backend quickstart](https://c15t.com/docs/self-host/quickstart)
+shows a complete v3 config and route.
+
+## Update the Node.js SDK
 
-import { ConsentBanner } from 'c15t/next';
-
-export function Banner() {
-  return (
-    <ConsentBanner.Root>
-      <ConsentBanner.Card>
-        <ConsentBanner.Header>
-          <ConsentBanner.Title />
-          <ConsentBanner.Description />
-        </ConsentBanner.Header>
-        <a href="/privacy">Privacy policy</a>
-        <ConsentBanner.PolicyActions />
-      </ConsentBanner.Card>
-    </ConsentBanner.Root>
-  );
+Install `@c15t/node-sdk@alpha`. The v2 client is gone: create one with
+`createC15tClient()` and pass the backend URL and API key yourself.
+
+| Package manager | Command                            |
+| :-------------- | :--------------------------------- |
+| npm             | `npm install @c15t/node-sdk@alpha` |
+| pnpm            | `pnpm add @c15t/node-sdk@alpha`    |
+| yarn            | `yarn add @c15t/node-sdk@alpha`    |
+| bun             | `bun add @c15t/node-sdk@alpha`     |
+
+```ts
+import { createC15tClient } from '@c15t/node-sdk';
+
+const apiKey = process.env.C15T_API_KEY;
+if (!apiKey) throw new Error('Set C15T_API_KEY');
+
+const c15t = createC15tClient({
+	baseUrl: 'https://app.example.com/api/c15t',
+	apiKey,
+});
+
+const result = await c15t.consents.check({
+	externalId: 'user_123',
+	types: ['privacy_policy', 'marketing_communications'],
+});
+if (result.ok) {
+	console.log(result.data.results.privacy_policy.hasConsent);
 }
 ```
 
-## Session reports in manifest mode
-
-A host that resolves init from a cached manifest never calls `/init`, so a v3
-backend could not count the visitors it served. From this release every
-server-side resolution sends `POST /sessions` to the backend after the fact,
-server-to-server and detached from the response: the Next.js, TanStack Start,
-SvelteKit, Nuxt and Astro init routes, and the Next.js, TanStack Start and
-Astro render-time prefetches. The browser makes no request.
-
-This is a new outbound data flow from your server to the consent backend. The
-report carries the manifest revision, the matched policy, the jurisdiction,
-country, region, language and GPC signal, plus the visitor's user agent and
-address as request headers. It carries no cookies and no identifier. Nothing is
-stored on the backend; the report reaches a `sessions.onReport` sink and the
-request log.
-
-Reporting is on by default and needs an absolute backend URL. Set
-`reportSessions: false` on the adapter to send none. Each report is one
-resolution, not one visitor: a page view can produce a `render` report and a
-`route` report, and nothing in them links the two. A consumer counting sessions
-groups reports by the forwarded address and user agent within a window.
+| v2                                                                  | v3                                                                         |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `c15tClient(options)`, `new C15TClient(options)`                    | `createC15tClient(options)`                                                |
+| `C15T_API_URL`, `C15T_API_TOKEN` read from the environment          | Not read. Pass `baseUrl` and `apiKey`.                                     |
+| `token`                                                             | `apiKey`                                                                   |
+| `prefix`                                                            | Part of `baseUrl`, such as `https://app.example.com/api/c15t`              |
+| `timeout`                                                           | `timeoutMs`, per attempt                                                   |
+| `retryConfig`                                                       | `retry: { maxRetries, initialDelayMs, maxDelayMs }`, or `false`            |
+| `debug`, `C15T_DEBUG`                                               | `onEvent`                                                                  |
+| `client.meta.status()`, `client.status()`                           | `c15t.status()`                                                            |
+| `client.meta.init()`, `client.init()`                               | `c15t.init({ language, country, region, gpc })`                            |
+| `getSubject(id, { type: 'a,b' })`                                   | `subjects.get(id, { types: ['a', 'b'] })`                                  |
+| `createSubject(input)`                                              | `subjects.create(input)`. `givenAt` also takes a `Date`.                   |
+| `patchSubject(id, input)`, `subjects.patch(id, input)`              | `subjects.identify(id, { externalId, identityProvider })`                  |
+| `listSubjects({ externalId })`                                      | `subjects.list({ externalId })`, on a client with `apiKey`                 |
+| `checkConsent(query)`, `consent.check({ externalId, type: 'a,b' })` | `consents.check({ externalId, types: ['a', 'b'] })`                        |
+| `summarizeExperiment(id, query)`, `experiments.summary(id, query)`  | `experiments.summary(id, { from, to, domain })`, on a client with `apiKey` |
+| `ResponseContext` with `data: T \|null`                             | `{ ok: true, data } \|{ ok: false, error }`. Check `ok` first.             |
+| `unwrap()`, `expect()` on the response                              | `unwrap(result)`, imported from `@c15t/node-sdk`                           |
+| `unwrapOr()`, `map()` on the response                               | Check `result.ok`                                                          |
+| `throw: true`                                                       | `unwrap(result)`                                                           |
+| `onSuccess`, `onError`                                              | Check `result.ok` after the call                                           |
+| `C15TError`, `isC15TError()`                                        | `C15tError`, `isC15tError(error, ...codes)`                                |
+| `$fetch`, `fetcher`, `resolveUrl`, `createResponseContext`          | Removed. Pass a custom `fetch` to `createC15tClient` if you need one.      |
+| `createMockClient`, `createMockResponse`, `createMockErrorResponse` | `createMockC15tClient`, `ok`, `err` from `@c15t/node-sdk/testing`          |
+
+`patchSubject` returned `{ success, subject }`. `subjects.identify` returns
+`{ subject }`, and `subject.identityProvider` is always set. Dates in
+responses, such as `givenAt` and `createdAt`, are now `Date` objects rather
+than strings.
+
+The new client also adds `manifest()` and `legalDocuments.publish()`. See the
+[Node.js SDK reference](https://c15t.com/docs/self-host/api/node-sdk).
+
+## 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.