@c15t/react 3.0.0-alpha.9 → 3.0.0

package/docs/concepts/data-fetching.md

@@ -14,14 +14,14 @@ the same protocol, so every path below works with either. Only `offline()`
 removes backend requests. For a recommendation by framework, start with
 [choose your setup](./choose-your-setup.md).
 
-| Fetching path                    | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
-| -------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Build-time manifest, recommended | Your server or browser resolves a bundled policy snapshot with each visitor's inputs  | Inth or your c15t backend   | Your framework supports a build integration and policy changes can ship with a rebuild                 |
-| Cached manifest on your server   | Your application resolves public policy data with each request's location and signals | Inth or your c15t backend   | Policy changes must reach the app without rebuilding, or builds cannot access the backend              |
-| Regular backend `/init`          | The consent backend                                                                   | The same backend            | You want the fewest moving parts, need backend-owned request resolution, or have no application server |
-| Manifest in the browser          | The browser, using supplied or unknown location                                       | Inth or your c15t backend   | You deliberately want client resolution and have planned geography, bundle size and policy refresh     |
-| Offline                          | The browser or local runtime, using bundled rules                                     | No backend submission       | Local development and tests. Not recommended for production environments.                              |
-| Custom transport                 | Your implementation                                                                   | Your implementation         | An existing service cannot use the c15t backend protocol                                               |
+| Fetching path                                             | Where policy resolves                                                                        | Where choices are submitted | Choose it when                                                                                                                                       |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build-time manifest, recommended for server-rendered apps | Your server resolves a bundled policy snapshot with each visitor's inputs                    | Inth or your c15t backend   | Your framework renders on the server, supports a build integration, and policy changes can ship with a rebuild                                       |
+| Cached manifest on your server                            | Your application resolves public policy data with each request's location and signals        | Inth or your c15t backend   | Policy changes must reach the app without rebuilding, or builds cannot access the backend                                                            |
+| Regular backend `/init`                                   | The consent backend                                                                          | The same backend            | You have no application server, as in a React, Vue or Svelte single-page app, want the fewest moving parts, or need backend-owned request resolution |
+| Manifest in the browser                                   | The browser, using a supplied location, or `/init` when the policy needs one it doesn't have | Inth or your c15t backend   | The policy has no location rules or the page knows the visitor's location, and you accept about 3 KB more bundle and a rebuild for policy edits      |
+| Offline                                                   | The browser or local runtime, using bundled rules                                            | No backend submission       | Local development and tests. Not recommended for production environments.                                                                            |
+| Custom transport                                          | Your implementation                                                                          | Your implementation         | An existing service cannot use the c15t backend protocol                                                                                             |
 
 ## What is a consent manifest?
 
@@ -45,21 +45,58 @@ requires a refresh strategy for cached or build-time manifests.
 The build fetches your public policy once and bundles it, so the server never
 fetches it at runtime.
 
+`manifest()` is the default mode in every server-rendered framework.
+[Consent modes](./modes.md#download-the-manifest-at-build-time)
+covers each framework's build integration and what happens when the
+download fails.
+
 The framework quickstarts include the build integration for supported
 deployments. Server resolution uses the snapshot without an upstream manifest
 request. Browser resolution includes the policy and resolver in the client
-bundle, and may still request location for regional policies. Static Nuxt and
+bundle, and still calls `/init` for a regional policy when the browser doesn't
+know the visitor's location, so the React, Vue and Svelte quickstarts use
+`hosted()` instead. Static Nuxt and
 Astro sites and script-tag sites keep the runtime setup from their guides.
 
 The snapshot is fixed at build time:
 
 * Rebuild after changing policies, translations or vendors. If your CI caches
   build output, force a fresh build.
-* The build must reach the backend. A failed fetch stops Next.js, TanStack
-  Start, SvelteKit and Vite builds. By default, Astro and Nuxt log a warning
-  instead and fetch the policy at runtime.
 * Consent choices still go to the backend.
 
+The build reads the backend URL from your public backend URL variable when
+the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
+`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
+Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
+Vite apps. Each also reads the matching Inth variable, such as
+`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
+[set the backend URL](./modes.md#set-the-backend-url).
+
+The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
+every framework does the same thing:
+
+| Command                                                                   | Default when the fetch fails                             |
+| ------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Production build: `next build`, `vite build`, `nuxt build`, `astro build` | The build stops with an error.                           |
+| Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`                      | A warning, and the server fetches the policy at runtime. |
+
+Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
+`'runtime'` lets a production build finish, and the server fetches the policy
+at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
+option, so you can deploy during a backend outage without a code change:
+
+```sh
+C15T_ON_BUILD_ERROR=runtime npm run build
+```
+
+Turborepo's strict environment mode hides undeclared variables from tasks, so
+list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.
+
+The build skips the fetch, without an error, when it can't use a snapshot,
+for example when the backend URL is relative. With `onBuildError: 'fail'`, a
+relative URL stops the build. [Consent modes](./modes.md#what-happens-when-the-download-fails)
+lists every case.
+
 ## How manifest mode counts visitors
 
 The backend counts visitors from `/init` requests, and manifest resolution
@@ -75,10 +112,10 @@ no report. Set `reportSessions: false` on an adapter to turn it off.
 Each page load gets a journey id, a random UUID sent on requests c15t already
 makes:
 
-| Request          | Query parameters                                                                                 |
-| ---------------- | ------------------------------------------------------------------------------------------------ |
-| `GET /init`      | `c15tJourney`, `c15tJourneyScope`, `c15tStored` (`1` if a choice or notice dismissal was stored) |
-| `POST /subjects` | `c15tJourney`, `c15tJourneyScope`                                                                |
+| Request          | Query parameters                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `GET /init`      | `journey`, `journeyScope`, `stored` (`1` if a choice or notice dismissal was stored) |
+| `POST /subjects` | `journey`, `journeyScope`                                                            |
 
 Session reports carry it as `journey: { id, scope, storedChoice, prompt, domain }`.
 A report and a save with the same `id` belong to one page load. `prompt` is
@@ -98,35 +135,46 @@ Saves replayed after going offline carry none.
 
 Set it on the runtime or provider. In Next.js use `defineConsentConfig({ journey })`;
 in TanStack Start pass the same value to `resolveConsent` and `ConsentRoot`; with
-the inline prefetch script, pass it to `buildPrefetchScript`. Vue, Svelte, Astro
+the inline prefetch script, pass it to `buildPrefetchScript` or to
+`consentManifest({ initPrefetch: { journey } })`. Left unset, the script
+continues a `'tab'` journey the tab already holds. A tab's first page has
+none, so its `/init` reports the scope as `'page'`. The id still links it to
+the save. Pass `journey: 'tab'` to the script too if you report on scope. Vue, Svelte, Astro
 and the script tag use `'page'`. A manifest that resolves locally in the
 browser reports no init, so it sends no journey.
 
-If you pass `hosted()` a `fetch`, match on the path: URLs now carry a query string.
+If you pass a transport `hosted()` a `fetch`, match on the path: URLs now carry a query string.
 
 ## What does regular `/init` do?
 
-`hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for
-consent submissions. The name `hosted` describes the transport protocol; the URL
-can belong to Inth or your own c15t backend.
+`hosted()` uses `${backendURL}/init` for initialization and
+`${backendURL}/subjects` for consent submissions. The name `hosted` describes
+the protocol; the URL can belong to Inth or your own c15t backend.
 
-```ts title="src/consent-mode.ts"
-import { hosted } from 'c15t';
+```ts title="c15t.config.ts"
+import { defineConsentConfig, hosted } from 'c15t/next';
 
-export function createConsentMode(backendURL: string) {
-	return hosted({ url: backendURL });
-}
+export default defineConsentConfig({ mode: hosted() });
 ```
 
-Pass the factory to your adapter's `mode` option. For request rendering, use the
-adapter's server helper and forward its prepared result to the browser. For
-static output, initialize in the browser with a reachable external URL.
+Each framework passes the mode in a different place, and server-rendered
+frameworks take the data `hosted()` from their own package.
+[Consent modes](./modes.md#import-the-factories-from-your-framework-package)
+lists where each one goes.
 
 A regular backend `/init` request lets the backend resolve the visitor context.
 A same-origin URL named `/api/c15t/init` can instead resolve from a cached
 manifest in your application. The URL name alone does not tell you which path
 runs.
 
+In the browser, an inline script in `<head>` can start `/init` while the
+app's JavaScript downloads, and `hosted()` uses that response. Vite apps get
+it from `consentManifest()` by default, Nuxt adds it to pages with
+`ssr: false`, and TanStack Start has `consentPrefetchHead`. Elsewhere, render
+`buildPrefetchScript({ backendURL })` from `c15t` yourself. If c15t assigns
+a banner experiment's arm, give the script the same `experiment`, or
+`hosted()` sends a second `/init` for visitors who have not chosen yet.
+
 ## How do transports and proxies differ?
 
 A transport implements initialization, saving and optional record operations.
@@ -135,28 +183,35 @@ resolver or make personalized responses safe to cache.
 
 For a same-origin init route that resolves a manifest, the hosted transport can
 separate policy reads and record writes. With a backend rewrite mounted at
-`/api/c15t`, a client mode can use:
+`/api/c15t`, a single-page app can use the transport `hosted()` from
+`c15t`:
 
 ```ts title="src/consent-mode.ts"
 import { hosted } from 'c15t';
 
 export const mode = hosted({
-	url: '/api/c15t',
+	backendURL: '/api/c15t',
 	initURL: '/api/c15t/init',
-	assertDecisionInputs: true,
 });
 ```
 
-The route must return the c15t init response contract. `assertDecisionInputs`
-binds saves to the resolved policy when init did not return a signed policy
-snapshot token. The backend can then reject a stale policy decision. Next.js
-sets this option for you when `ConsentRoot` receives a `config` with
-`initURL`.
+The route must return the c15t init response contract. c15t adds its inputs to
+`initURL` as query parameters, replacing any of your own with the same name.
+See [query parameters and CORS](https://c15t.com/docs/self-host/api/endpoints#query-parameters-and-cors)
+for the names. Because `initURL` is set, `assertDecisionInputs` defaults to
+`true`: saves carry the policy decision they were made against when init
+returned no signed policy snapshot token, so the backend can reject a save
+made against a stale policy. Server-rendered frameworks do this for you when
+you set `routePrefix`: the browser re-inits through `${routePrefix}/init`.
+Every framework rejects `routePrefix: '/'` when it sets up, because a
+catch-all consent route at the site root would catch every page.
 
 The init route resolves policy; the backend rewrite forwards `/api/c15t/subjects`
 and other record endpoints. Configure both if you choose this optional proxy
-variant. The
-[Next.js rewrite recipe](https://c15t.com/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
+variant. Server-rendered frameworks do both with one option: `proxy: true` in
+Next.js `c15t.config.ts` or TanStack Start's `createConsentStateHandler`,
+with a consent route created with `proxy: true`. The
+[Next.js recipe](https://c15t.com/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
 shows the configuration. A direct absolute backend URL works
 without a rewrite.
 
@@ -181,9 +236,8 @@ saves locally. The runtime's persistence module stores the choice in browser
 storage. There is no backend audit history, cross-device record service or IP
 geolocation supplied by this transport.
 
-Use your adapter's offline factory so its translations and provider context are
-included. This React and Next.js example replaces the hosted mode in an existing
-client provider:
+Use your framework's `offline()` so its translations and provider context are
+included. In a React app it replaces the mode passed to `ConsentProvider`:
 
 ```ts title="src/consent-mode.ts"
 import { offline } from 'c15t/react';
@@ -191,6 +245,10 @@ import { offline } from 'c15t/react';
 export const mode = offline();
 ```
 
+In Next.js, TanStack Start, Nuxt, Astro and SvelteKit, pass the data
+`offline()` from the framework package where the config takes `mode`; see
+[consent modes](./modes.md#import-the-factories-from-your-framework-package).
+
 With no `policyRules`, the current offline transport uses the recommended rule
 pack. Supplying `policyRules` replaces that pack. Unknown country and region are
 real resolution inputs; offline mode does not discover a visitor's location.

package/docs/concepts/modes.md

@@ -0,0 +1,281 @@
+---
+title: Consent modes
+description: Reference for manifest(), hosted() and offline() in every c15t
+  framework package, where each one resolves the visitor's policy, what it adds
+  to first-load JavaScript, the build-time manifest fetch and its failure
+  policy, and the backend URL variable each framework reads.
+group: concepts
+---
+
+## Choose a mode
+
+A mode decides how c15t finds the policy that applies to a visitor. Every
+framework package exports the same three factories, `manifest()`, `hosted()`
+and `offline()`. Consent choices go to the backend in `manifest()` and
+`hosted()`, whether that backend is [Inth](https://inth.com) or a
+[self-hosted c15t backend](https://c15t.com/docs/self-host/quickstart).
+
+| Mode                      | Where the policy resolves                                                                                           | Backend requests on a first visit                                                                             | Use it when                                                                                                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `manifest()`, the default | Your server, from the policy the build downloaded. With `resolve: 'browser'`, or in a single-page app, the browser. | None to resolve the policy, unless the browser needs a location it doesn't have. Choices post to `/subjects`. | Server-rendered apps. Rebuild to ship policy changes, or set `source: 'runtime'`.                                                                             |
+| `hosted()`                | The backend's `GET /init`                                                                                           | One `/init` per page that resolves consent.                                                                   | Single-page apps and static hosting without a server, where the backend reads each visitor's location from the request. Policy edits apply without a rebuild. |
+| `offline()`               | The browser, from rules in your bundle                                                                              | None. Choices stay in the browser.                                                                            | Local development, tests and demos. Not recommended for production environments.                                                                              |
+
+`manifest()` is the default in Next.js, TanStack Start, Nuxt, Astro and
+SvelteKit. React, Vue, Svelte and `@c15t/browser` have no default: pass a
+mode yourself. The React, Vue and Svelte quickstarts use `hosted()`, because
+a browser has no request location and a bundled regional policy still needs
+`/init` on a first visit. The JavaScript quickstart uses `manifest()`. The
+script tag picks its
+mode from the bundle file; see
+[choose a mode](https://c15t.com/docs/frameworks/html/attributes-and-api#choose-a-mode).
+
+[Data fetching](./data-fetching.md) compares these paths with the
+custom transport and same-origin proxies.
+
+## Import the factories from your framework package
+
+There are two kinds of factory, and each framework package exports the kind it
+needs under the same three names.
+
+| Framework      | Import from           | Pass the mode to                                                                                                                | Kind      |
+| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| Next.js        | `c15t/next`           | `mode` in `c15t.config.ts`                                                                                                      | Data      |
+| TanStack Start | `c15t/tanstack-start` | `createConsentStateHandler({ mode })`                                                                                           | Data      |
+| Nuxt           | `c15t/vue`            | `c15t.mode` in `nuxt.config.ts`                                                                                                 | Data      |
+| Astro          | `c15t/astro`          | `c15t({ mode })` in `astro.config.mjs`                                                                                          | Data      |
+| SvelteKit      | `@c15t/svelte/kit`    | `c15tHandle({ mode })` in `src/hooks.server.ts`                                                                                 | Data      |
+| React          | `c15t/react`          | `ConsentProvider`'s `options.mode`                                                                                              | Transport |
+| Vue            | `c15t/vue/vue-plugin` | `app.use(c15tVue, { mode })`                                                                                                    | Transport |
+| Svelte         | `@c15t/svelte`        | `<ConsentProvider mode={...}>`                                                                                                  | Transport |
+| JavaScript     | `@c15t/browser`       | `init({ mode })`                                                                                                                | Transport |
+| Script tag     | none                  | The bundle file: `c15t.js` is hosted, `c15t.offline.js` offline. The headless and IAB scripts also take `data-mode="manifest"`. | Name      |
+
+**Data factories** return a plain object such as `{ type: 'manifest' }`.
+Server-rendered frameworks read their config on the server and in the
+browser, and Nuxt and Astro serialize it, so the mode has to be data. The
+framework turns it into a transport in the browser and loads the code of
+any mode other than the default with `import()`. The same factories are
+available from `c15t/modes` (or `@c15t/core/modes`) for shared code.
+
+**Transport factories** return the transport itself, with the same `type` and
+options attached as properties. A single-page app has one environment, so
+the bundler keeps only the mode you import and drops the others.
+
+A server-rendered root that receives a transport factory still works, for
+example `hosted()` from `c15t/react` passed to Next.js `ConsentRoot` as
+`options.mode`. Outside production it warns that the transport's code is now
+in the first-load bundle. `custom(transport)` exists only as a transport, so
+it cannot go in a serializable config. Pass it through the root's
+`options.mode` instead.
+
+## manifest()
+
+`manifest()` resolves the visitor's policy from the backend's public consent
+manifest instead of asking the backend's `/init`. A
+[consent manifest](./data-fetching.md#what-is-a-consent-manifest)
+holds your policy rules and copy, and no visitor data.
+
+| Option        | Default    | Behavior                                                                                                                                                                                                                            |
+| ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source`      | `'build'`  | `'build'` uses the snapshot the build integration downloaded. Without one, such as in dev after a failed fetch, it fetches the manifest at runtime. `'runtime'` always fetches at runtime, so policy edits apply without a rebuild. |
+| `snapshot`    | none       | A manifest you supply. You can pass `snapshot` or `source`, not both.                                                                                                                                                               |
+| `resolve`     | `'server'` | `'server'` resolves each visitor on the server and ships no resolver to the browser. `'browser'` resolves in the browser, for pages the server does not render per visitor. Server-rendered frameworks only.                        |
+| `manifestURL` | see below  | Where to fetch the manifest at runtime. On the server, `${backendURL}/manifest`. In the browser, `${routePrefix}/manifest`, else `${backendURL}/manifest`.                                                                          |
+| `geoURL`      | none       | A same-origin route that answers with the visitor's `{ country, region }`. Browser resolution only.                                                                                                                                 |
+| `inputs`      | none       | `{ country, region }` when the page already knows the visitor's location, for example from an edge worker. Browser resolution only.                                                                                                 |
+
+The transport `manifest()` from `c15t/react`, `c15t/vue/vue-plugin`,
+`@c15t/svelte` and `@c15t/browser` always resolves in the browser, so it has
+no `resolve` option. It also takes `backendURL`, `headers`, `credentials`,
+`domain`, `fetch` and `initFallback`. With no options it reads the snapshot
+and the backend URL your build integration downloaded. With `manifestURL`,
+the browser fetches that URL when the page loads and the build's snapshot is
+not used. Saves still go to `backendURL`, or the build's backend URL.
+
+When the policy depends on where the visitor is, and the browser does not
+know the country or region, browser resolution asks `geoURL`, then the
+backend's `/init`. Set `initFallback: false` to resolve for an unknown location
+instead. A policy with location rules therefore saves no request in a
+single-page app unless you pass `inputs` or `geoURL`. The `consentManifest()`
+plugins from `c15t/build`, `c15t/vue/vite` and `@c15t/svelte/vite` warn
+about this when a single-page app build bundles such a policy.
+
+## hosted()
+
+`hosted()` asks the backend's `GET /init` for each visitor's policy and posts
+choices to `${backendURL}/subjects`.
+
+| Option       | Default                     | Behavior                                               |
+| ------------ | --------------------------- | ------------------------------------------------------ |
+| `backendURL` | the framework's backend URL | Backend URL, absolute or relative such as `/api/c15t`. |
+| `headers`    | none                        | Headers sent with `GET /init`.                         |
+
+The transport `hosted()` also takes `initURL`, `assertDecisionInputs`,
+`domain` and `fetch`. `initURL` sends `GET /init` to another URL, usually a
+same-origin route that resolves the manifest, while saves keep going to
+`${backendURL}/subjects`. `assertDecisionInputs` defaults to `true` when
+`initURL` is set, so each save carries the policy decision it was made
+against and the backend can reject a save made against a stale policy.
+
+`hosted()` from `c15t` (`@c15t/core`) is the plain transport and requires
+`backendURL`. The framework exports fill it in from your config or your
+build.
+
+## offline()
+
+Not recommended for production environments.
+
+`offline()` resolves policy rules in the browser and stores choices in browser
+storage. Nothing reaches a backend, so there is no consent record, no
+cross-device history and no IP geolocation.
+
+| Option        | Default                   | Behavior                                                    |
+| ------------- | ------------------------- | ----------------------------------------------------------- |
+| `policyRules` | the recommended rule pack | Rules to resolve. Passing rules replaces the pack entirely. |
+
+Unknown country and region are real inputs: test the missing-location case
+against your rules. See [policy rules](./policies.md).
+
+## What each mode adds to first-load JavaScript
+
+In a server-rendered framework, the browser receives the resolved state with
+the page. It only needs the code to save a choice, and loads the rest when it
+runs:
+
+| Mode                               | First-load JavaScript                                  | Loaded with `import()` when it runs                                                                                                           |
+| ---------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `manifest()`                       | The code that saves choices and builds an init request | The hosted init path, if the browser has to resolve consent again                                                                             |
+| `manifest({ resolve: 'browser' })` | The code that saves choices                            | The browser resolver, English copy and the fetch of `${routePrefix}/manifest` or `${backendURL}/manifest`. Other languages load per language. |
+| `hosted()`                         | The code that saves choices                            | The hosted init path                                                                                                                          |
+| `offline()`                        | Nothing mode-specific                                  | The offline transport, the rule pack and its copy                                                                                             |
+
+With `manifest()` resolved on the server, the manifest snapshot, the resolver,
+the offline rule pack and other languages stay out of the browser bundle.
+
+In a single-page app the bundle contains the mode you imported:
+
+| Mode         | In the bundle                                                                                                                                                                                                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `manifest()` | The snapshot, when the build downloaded one, and the code that saves choices. The resolver starts loading when `manifest()` runs, unless the policy needs a location the page does not know. English copy is bundled; other languages load the first time a visitor needs one. |
+| `hosted()`   | The hosted transport                                                                                                                                                                                                                                                           |
+| `offline()`  | The offline transport, the recommended rule pack and its copy                                                                                                                                                                                                                  |
+
+## Set the backend URL
+
+Each framework reads its backend URL from a public environment variable, so
+the quickstarts never write it in code. Put it in `.env` or your host's build
+settings. The value is public configuration, not a secret.
+
+| Framework                                           | Variable                                                | Inth alternative                                        |
+| --------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
+| Next.js                                             | `NEXT_PUBLIC_C15T_BACKEND_URL`                          | `NEXT_PUBLIC_INTH_PROJECT_URL`                          |
+| Nuxt                                                | `NUXT_PUBLIC_C15T_BACKEND_URL`                          | `NUXT_PUBLIC_INTH_PROJECT_URL`                          |
+| Astro                                               | `PUBLIC_C15T_BACKEND_URL`                               | `PUBLIC_INTH_PROJECT_URL`                               |
+| SvelteKit and Svelte                                | `PUBLIC_C15T_BACKEND_URL`, then `VITE_C15T_BACKEND_URL` | `PUBLIC_INTH_PROJECT_URL`, then `VITE_INTH_PROJECT_URL` |
+| TanStack Start, React, Vue and JavaScript with Vite | `VITE_C15T_BACKEND_URL`                                 | `VITE_INTH_PROJECT_URL`                                 |
+| Script tag                                          | `data-backend-url` on the script element                | –                                                       |
+
+Set either variable. The Inth one holds your Inth project URL, so other Inth
+SDKs in the same app can read it too. When both are set, the c15t variable
+wins.
+
+A backend URL resolves in this order: the mode's own `backendURL`, then the
+framework's top-level `backendURL` option, then the c15t variable, then the
+Inth variable. The build reads each variable from the process environment,
+then from `.env.[mode].local`, `.env.[mode]`, `.env.local` and `.env` in the
+project root, so a c15t variable in `.env` still beats an Inth variable in
+the environment. The Vite plugins set an unset `VITE_C15T_BACKEND_URL` to the
+URL they used, so `import.meta.env.VITE_C15T_BACKEND_URL` in app code reads
+the same value. `withConsentManifest()` does the same for
+`NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js.
+
+Next.js inlines `NEXT_PUBLIC_` variables at build time. Changing the variable
+on a built app has no effect until you rebuild.
+
+## Download the manifest at build time
+
+`manifest()` with the default `source: 'build'` resolves from a snapshot that a
+build integration downloads from `${backendURL}/manifest`:
+
+| Framework            | Build integration                                                   | Name in messages             |
+| -------------------- | ------------------------------------------------------------------- | ---------------------------- |
+| Next.js              | `withConsentManifest()` from `c15t/next/build`, in `next.config.ts` | `@c15t/nextjs/build`         |
+| TanStack Start       | `consentManifest()` from `c15t/tanstack-start/build`                | `@c15t/tanstack-start/build` |
+| React and JavaScript | `consentManifest()` from `c15t/build`                               | `@c15t/core/build`           |
+| Vue                  | `consentManifest()` from `c15t/vue/vite`                            | `@c15t/vue/vite`             |
+| Svelte and SvelteKit | `consentManifest()` from `@c15t/svelte/vite`                        | `@c15t/svelte/vite`          |
+| Nuxt                 | the `c15t/vue` module                                               | `@c15t/vue`                  |
+| Astro                | the `c15t()` integration                                            | `@c15t/astro`                |
+
+The integration downloads the manifest when the production build or the dev
+server starts, and waits at most 10 seconds. Nothing is written into your
+source tree. App code reads the result from `c15t/generated`:
+
+```ts
+import { backendURL, snapshot } from 'c15t/generated';
+```
+
+Both exports are `undefined` when the build has no snapshot, so imports
+compile on a fresh checkout. In the browser bundle of a server-rendered
+framework, `snapshot` is always `undefined`. Next.js goes further: a client
+component that imports `c15t/generated` fails the build.
+
+Rebuild after you change policies, translations or vendors in your project. If
+your CI caches build output, force a fresh build.
+
+## What happens when the download fails
+
+The same policy applies in every framework:
+
+| Command                                                                   | Default when the download fails or no backend URL is set                                |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Production build: `next build`, `vite build`, `nuxt build`, `astro build` | The build stops with an error.                                                          |
+| Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`                      | A warning. The server, or a single-page app's browser, fetches the manifest at runtime. |
+
+`onBuildError` picks one behavior for both commands:
+
+* `'fail'` stops dev too.
+* `'runtime'` lets a production build finish without a snapshot. The manifest
+  is then fetched at runtime.
+
+Pass it where you configure the integration: the second argument of
+`withConsentManifest()`, `consentManifest({ onBuildError })`, the `c15t` key
+in `nuxt.config.ts`, or `c15t({ onBuildError })` in Astro.
+
+The `C15T_ON_BUILD_ERROR` environment variable overrides the option, so you
+can deploy during a backend outage without a code change:
+
+```sh
+C15T_ON_BUILD_ERROR=runtime npm run build
+```
+
+Any value other than `fail` or `runtime` stops the command. Turborepo's strict
+environment mode hides undeclared variables from tasks, so list
+`C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.
+
+A missing backend URL follows the same policy as a failed download: a
+production build stops, dev warns, and an explicit `'runtime'` logs a notice
+and continues. Astro and Nuxt are stricter in `manifest()` mode, including
+`manifest({ snapshot })`: the browser saves consent to the backend, so a
+missing backend URL stops `astro dev` and `nuxt dev` as well.
+
+The download is skipped without an error when the build cannot use a
+snapshot:
+
+* The backend URL is relative, such as `/api/c15t`. With an explicit
+  `onBuildError: 'fail'`, a relative URL stops the build instead.
+* Next.js builds with `output: 'export'`, which has no server.
+* The mode is `hosted()`, `offline()`, `manifest({ snapshot })` or
+  `manifest({ source: 'runtime' })` in Next.js, Nuxt and Astro. Next.js reads
+  the mode from `c15t.config.ts`.
+* A single-page app built with Vite (React, Vue, Svelte, JavaScript) does
+  not use `manifest()`. The mode is set in app code, so the plugin downloads
+  the manifest only once the bundle turns out to read it, after unused code
+  is dropped. A `hosted()` or `offline()` build never contacts the backend.
+  SvelteKit and TanStack Start choose the mode on the server at runtime, so
+  their builds always download it.
+
+A failed download never reuses an older snapshot. The
+[troubleshooting guide](../guides/troubleshooting.md#why-does-the-build-fail-to-download-the-manifest)
+lists each message and its fix.

package/docs/customization/dark-mode.md

@@ -35,7 +35,7 @@ your site and let c15t follow it.
 | Nuxt                    | `colorScheme` under the `c15t` key in `nuxt.config.ts`, or in `app/app.config.ts` | Unset: copies `dark` |
 | Vue                     | `colorScheme` in the `c15tVue` options                                            | Unset: copies `dark` |
 | Astro                   | `colorScheme` in the `c15t()` integration options                                 | `'system'`           |
-| Svelte, SvelteKit       | `colorScheme` on `ConsentManagerProvider`                                         | Unset: copies `dark` |
+| Svelte, SvelteKit       | `colorScheme` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)          | Unset: copies `dark` |
 | HTML                    | `data-color-scheme` on the script tag: `light`, `dark`, `system` or `none`        | `system`             |
 | JavaScript              | `ui.colorScheme` in `init()`                                                      | `'system'`           |
 

package/docs/customization/motion.md

@@ -55,12 +55,12 @@ surface where your framework allows:
 
 | Framework               | For every surface                                                                | For one surface                                                                                                                     |
 | ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js, TanStack Start | `options.disableAnimation` on `ConsentRoot`                                      | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
+| Next.js, TanStack Start | `options.disableAnimation` in Next.js `c15t.config.ts`, or on `ConsentRoot`      | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
 | React                   | `disableAnimation` in the `ConsentProvider` options                              | The same component props                                                                                                            |
 | Nuxt                    | `disableAnimation` in the `c15t` module options                                  | `disableAnimation` prop on `consent-banner.vue`, `consent-manager.vue` and the IAB banner and dialog, when you render them yourself |
 | Vue                     | `disableAnimation` in the `c15tVue` options                                      | The same component props                                                                                                            |
 | Astro                   | `disableAnimation` in the `c15t()` integration options                           | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
-| Svelte, SvelteKit       | `disableAnimation` on `ConsentManagerProvider`                                   | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
+| Svelte, SvelteKit       | `disableAnimation` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)    | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
 | HTML                    | `data-disable-animation` on the script tag, or `ui.disableAnimation` in `config` | `ui.banner.disableAnimation`, `ui.dialog.disableAnimation`                                                                          |
 | JavaScript              | `ui.disableAnimation` in `init()`                                                | `ui.banner.disableAnimation`, `ui.dialog.disableAnimation`                                                                          |
 

package/docs/customization/recipes.md

@@ -82,7 +82,7 @@ presentation: {
 **Svelte**
 
 Render `CookieBanner` in place of `ConsentBanner`, inside
-`ConsentManagerProvider` and next to `ConsentDialog`.
+`ConsentProvider` and next to `ConsentDialog`.
 
 ```svelte title="src/lib/cookie-banner.svelte"
 <script lang="ts">
@@ -245,7 +245,7 @@ export const slimBar = {
 
 **Svelte**
 
-Spread `slimBar` into the options you pass to `ConsentManagerProvider`.
+Spread `slimBar` into the props you pass to `ConsentProvider`.
 Svelte scopes component styles, so the classes live in a global
 stylesheet.
 
@@ -255,7 +255,7 @@ import type { ConsentManagerOptions } from '@c15t/svelte';
 import './slim-bar.css';
 
 /**
- * Spread into the options you pass to `ConsentManagerProvider`. The bar
+ * Spread into the options you pass to `ConsentProvider`. The bar
  * keeps the stock markup and actions; the slot classes put it on one row.
  */
 export const slimBar = {
@@ -451,7 +451,7 @@ const run = (action: string) => {
 
 `getHeadlessConsent()` returns the banner state and `performAction`.
 Render `CookieBar` in place of `ConsentBanner`, inside
-`ConsentManagerProvider`, and keep `ConsentDialog`, which Preferences
+`ConsentProvider`, and keep `ConsentDialog`, which Preferences
 opens.
 
 ```svelte title="src/lib/cookie-bar.svelte"