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

package/dist-types/provider.d.ts

@@ -1,4 +1,4 @@
-import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentPresentation, ExperimentState, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
+import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentJourneyOption, ConsentPresentation, ExperimentState, JourneyState, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
 import type { Script } from '@c15t/core/modules/script-loader';
 import type { ConsentControlOptions } from '@c15t/core/runtime';
 import type { ConsentRuntime, ConsentRuntimeModules, ResolveStreamedInit } from '@c15t/core/runtime/provider';
@@ -13,9 +13,10 @@ export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onP
 /**
  * Prepared policy and records; legacy consent projections are not provider
  * inputs. An `experiment` a server helper resolved runs instead of
- * `options.experiment`.
+ * `options.experiment`, and a `journey` it started is the one the provider
+ * continues.
  */
-export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState;
+export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState & JourneyState;
 export interface ConsentProviderOptions extends ConsentControlOptions, Pick<ReactUIOptions, 'colorScheme' | 'disableAnimation' | 'noStyle' | 'scrollLock' | 'theme' | 'trapFocus'> {
     enabled?: boolean;
     presentation?: ConsentPresentation;
@@ -26,6 +27,13 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * provider to change the experiment.
      */
     experiment?: ConsentExperiment;
+    /**
+     * Random journey id that links each `/init` to the save that follows:
+     * `'page'`, `'tab'` or `false`. Initial-only.
+     *
+     * @default 'page'
+     */
+    journey?: ConsentJourneyOption;
     /**
      * Content Security Policy nonce applied to DOM nodes c15t injects.
      *
@@ -77,9 +85,12 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * Pass the pending `Promise<KernelConfig>` instead and the provider
      * mounts at once with a provisional policy, so `children` render (and
      * the static shell can prerender) while the consent data streams in.
-     * Consent surfaces stay hidden until the promise resolves; its first
-     * `init()` then applies the resolved config in place of the transport's
-     * network init. A config that resolves without a policy (persisted
+     * Consent surfaces stay hidden until the promise resolves. On the
+     * server, `ConsentBanner` waits for it in its own Suspense boundary and
+     * follows the page in a later chunk of the same response, before
+     * hydration, when the resolved policy shows a banner; see
+     * `streamBanner`. The resolved config then answers the first `init()`
+     * in place of the transport's network init. A config that resolves without a policy (persisted
      * consents, geo, language only) is applied to the kernel and the
      * transport init runs as usual; a rejected promise is logged outside
      * production and falls through to the transport init. Initial-only:
@@ -97,6 +108,17 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * ```
      */
     prefetch?: ConsentProviderPrefetch | Promise<ConsentProviderPrefetch>;
+    /**
+     * Whether `ConsentBanner` renders on the server once a `prefetch`
+     * promise resolves, so it arrives in the streamed response before the
+     * page hydrates. It shows only when the resolved policy shows a banner
+     * for this visitor. Set `false` to mount the banner after hydration
+     * instead, as with a client-only provider. No effect when `prefetch` is
+     * not a promise. Use the same value on the server and in the browser.
+     *
+     * @default true
+     */
+    streamBanner?: boolean;
     callbacks?: ConsentProviderCallbacks;
     /**
      * Remove configured browser data when its consent permission is revoked.

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.6";
+export declare const version = "3.0.0-alpha.8";

package/docs/concepts/choose-your-setup.md

@@ -13,8 +13,8 @@ to the alternatives it rules out.
 | Your app                                                                               | Setup                                                                                  | Guide                                                                                                                             |
 | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | Next.js App Router with a Next.js server                                               | Server resolves consent from a build-time manifest and streams it to the page          | [App Router](https://c15t.com/docs/frameworks/next/quickstart)                                                                    |
-| Next.js App Router, banner must be in the first HTML                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
-| Next.js with static, ISR or `'use cache'` pages                                        | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
+| Next.js App Router, page must arrive with its banner                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
+| Next.js with static, ISR, `'use cache'` or `ensureStatic = 'navigation'` pages         | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
 | Next.js Pages Router                                                                   | Resolve consent in `getServerSideProps`                                                | [Pages Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                          |
 | Next.js with `output: 'export'`                                                        | Browser resolves consent                                                               | [Static export](https://c15t.com/docs/frameworks/next/static-export)                                                              |
 | TanStack Start with a server                                                           | Root loader resolves consent on the server                                             | [TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart)                                                      |

package/docs/concepts/consent-state.md

@@ -99,6 +99,12 @@ backend that signs policy snapshot tokens rejects a replay made after the
 token expires, which is 30 minutes by default for the self-hosted backend. A
 save still queued by then is recorded only in the browser.
 
+A replay that fails and stays queued emits `save:replayed` with `ok: false` but
+not `command:error`, since the save already reported its first failure. A save
+that leaves the queue without the backend recording it, because it ran out of
+attempts, waited more than 7 days or was refused, emits `command:error` once.
+Development builds also log a `[c15t]` console warning for each of these.
+
 IAB surfaces close in the click task too, but an IAB choice is recorded only
 after its TC string is encoded, which can wait for the TCF library to load.
 If that local step records nothing, for example because the vendor list

package/docs/concepts/data-fetching.md

@@ -68,6 +68,40 @@ no identity; the visitor's IP address and user agent are forwarded under the
 backend's usual IP handling. Static output resolves in the browser and sends
 no report. Set `reportSessions: false` on an adapter to turn it off.
 
+## Link an init to the save that follows
+
+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`                                                                |
+
+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
+`due`, `stored` or `not-required`; a page that falls back to the default opt-in
+banner counts as `due` or `stored`. A stored answer counts as `stored` even if a
+policy change makes c15t ask again.
+
+The id is random, is never the subject id and is never written to a cookie.
+Every save that carries one follows an `/init` or report with the same id.
+Saves replayed after going offline carry none.
+
+| `journey`          | Behavior                                                                                                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'page'` (default) | One id per page load, in memory.                                                                                                                                                   |
+| `'tab'`            | Kept in `sessionStorage` while a prompt is due, and removed once the visitor chooses or no prompt is due. Only when the browser resolves init; server-rendered pages use `'page'`. |
+| `false`            | No journey.                                                                                                                                                                        |
+
+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
+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.
+
 ## What does regular `/init` do?
 
 `hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for

package/docs/customization/motion.md

@@ -8,20 +8,21 @@ group: customization
 
 ## Change the speed with motion tokens
 
-c15t animates its surfaces with three durations and four easing curves. Set
+c15t animates its surfaces with three durations and five easing curves. Set
 them in the theme's `motion` object, or as CSS variables:
 
-| CSS variable             | Theme key                | Default                                | Used by                                         |
-| ------------------------ | ------------------------ | -------------------------------------- | ----------------------------------------------- |
-| `--c15t-duration-fast`   | `motion.duration.fast`   | `80ms`                                 | Banner, buttons, tabs                           |
-| `--c15t-duration-normal` | `motion.duration.normal` | `150ms`                                | Preference dialog, switches, accordions         |
-| `--c15t-duration-slow`   | `motion.duration.slow`   | `200ms`                                | Legal links, floating trigger                   |
-| `--c15t-easing`          | `motion.easing`          | `cubic-bezier(0.4, 0, 0.2, 1)`         | Banner fade, switches, accordions               |
-| `--c15t-easing-out`      | `motion.easingOut`       | `cubic-bezier(0.215, 0.61, 0.355, 1)`  | Preference dialog, floating trigger hover       |
-| `--c15t-easing-in-out`   | `motion.easingInOut`     | `cubic-bezier(0.645, 0.045, 0.355, 1)` | Floating trigger snapping to a corner           |
-| `--c15t-easing-spring`   | `motion.easingSpring`    | `cubic-bezier(0.34, 1.56, 0.64, 1)`    | The banner's slide in and the dialog's scale in |
+| CSS variable             | Theme key                | Default                                  | Used by                                                        |
+| ------------------------ | ------------------------ | ---------------------------------------- | -------------------------------------------------------------- |
+| `--c15t-duration-fast`   | `motion.duration.fast`   | `80ms`                                   | Banner fade out, buttons, tabs                                 |
+| `--c15t-duration-normal` | `motion.duration.normal` | `150ms`                                  | Preference dialog, late banner fade in, switches, accordions   |
+| `--c15t-duration-slow`   | `motion.duration.slow`   | `200ms`                                  | Legal links, floating trigger                                  |
+| `--c15t-easing`          | `motion.easing`          | `cubic-bezier(0.4, 0, 0.2, 1)`           | Switches, accordions                                           |
+| `--c15t-easing-out`      | `motion.easingOut`       | `cubic-bezier(0.215, 0.61, 0.355, 1)`    | Preference dialog, late banner fade in, floating trigger hover |
+| `--c15t-easing-in`       | `motion.easingIn`        | `cubic-bezier(0.55, 0.055, 0.675, 0.19)` | Banner fade out                                                |
+| `--c15t-easing-in-out`   | `motion.easingInOut`     | `cubic-bezier(0.645, 0.045, 0.355, 1)`   | Floating trigger snapping to a corner                          |
+| `--c15t-easing-spring`   | `motion.easingSpring`    | `cubic-bezier(0.34, 1.56, 0.64, 1)`      | The dialog's scale in                                          |
 
-This theme slows the dialog down and removes the banner's overshoot:
+This theme slows the dialog down and removes its overshoot:
 
 ```ts title="consent-theme.ts"
 export const theme = {
@@ -32,6 +33,14 @@ export const theme = {
 };
 ```
 
+The banner never slides in. When it shows with the page, it is part of the
+first paint and appears on its first frame. When it arrives more than 100ms
+after the page first painted, such as after a slow script or a client-side
+init, it fades in over `--c15t-duration-normal` instead, and its root and
+backdrop carry `data-entry="late"`. A banner rendered on the server always
+shows at once. When it hides, Vue, Svelte and the script tag fade it out over
+`--c15t-duration-fast`.
+
 The theme goes where your framework's other tokens go. See
 [theme tokens](./tokens.md) and your framework's customize page.
 In Vue and Nuxt, set `tokens` with the variable name without the leading
@@ -39,8 +48,8 @@ In Vue and Nuxt, set `tokens` with the variable name without the leading
 
 ## Turn animations off
 
-`disableAnimation` removes the enter and exit transitions of the banner and
-dialogs, and the hover and snap transitions of the floating
+`disableAnimation` removes the banner's fades, the enter and exit
+transitions of the dialogs, and the hover and snap transitions of the floating
 `ConsentDialogTrigger`. Set it once for every surface, then override it for one
 surface where your framework allows:
 

package/docs/customization/tokens.md

@@ -130,6 +130,7 @@ easing tokens.
 | `--c15t-duration-slow`        | `motion.duration.slow`           | `200ms`                                         |
 | `--c15t-easing`               | `motion.easing`                  | `cubic-bezier(0.4, 0, 0.2, 1)`                  |
 | `--c15t-easing-out`           | `motion.easingOut`               | `cubic-bezier(0.215, 0.61, 0.355, 1)`           |
+| `--c15t-easing-in`            | `motion.easingIn`                | `cubic-bezier(0.55, 0.055, 0.675, 0.19)`        |
 | `--c15t-easing-in-out`        | `motion.easingInOut`             | `cubic-bezier(0.645, 0.045, 0.355, 1)`          |
 | `--c15t-easing-spring`        | `motion.easingSpring`            | `cubic-bezier(0.34, 1.56, 0.64, 1)`             |
 

package/docs/frameworks/react/components/consent-banner.md

@@ -12,20 +12,25 @@ The [quickstart](../quickstart.md) mounts both in
 `src/consent.tsx`:
 
 ```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
+import { consentManifest } from './c15t-manifest';
 import { scripts } from './scripts';
 
 import 'c15t/react/styles.css';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = manifest({
+	backendURL:
+		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+	manifest: consentManifest,
+});
 
 export const Consent = ({ children }: { children: ReactNode }) => (
 	<ConsentProvider options={{ mode, scripts }}>

package/docs/frameworks/react/components/consent-dialog.md

@@ -14,20 +14,25 @@ group: frameworks
 code.
 
 ```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
+import { consentManifest } from './c15t-manifest';
 import { scripts } from './scripts';
 
 import 'c15t/react/styles.css';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = manifest({
+	backendURL:
+		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+	manifest: consentManifest,
+});
 
 export const Consent = ({ children }: { children: ReactNode }) => (
 	<ConsentProvider options={{ mode, scripts }}>

package/docs/frameworks/react/components/consent-provider.md

@@ -14,20 +14,25 @@ The [quickstart](../quickstart.md) does this in
 `src/consent.tsx`:
 
 ```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
+import { consentManifest } from './c15t-manifest';
 import { scripts } from './scripts';
 
 import 'c15t/react/styles.css';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = manifest({
+	backendURL:
+		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+	manifest: consentManifest,
+});
 
 export const Consent = ({ children }: { children: ReactNode }) => (
 	<ConsentProvider options={{ mode, scripts }}>
@@ -41,9 +46,11 @@ export const Consent = ({ children }: { children: ReactNode }) => (
 );
 ```
 
-`hosted({ url })` points the provider at your Inth backend. Replace
-`https://your-project.inth.app` with the URL from your Inth project. The
-Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
+`manifest()` from `@c15t/browser/headless` resolves the policy from the
+snapshot the build bundled, and sends consent choices to `backendURL`. Replace
+the demo project URL with the URL from your Inth project, or set
+`VITE_C15T_BACKEND_URL`. To fetch the policy from the backend on every page
+load instead, pass `hosted({ url })` from `c15t/react`. The Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
 this provider and passes it server-resolved state.
 
 ## Provider options
@@ -56,34 +63,35 @@ the provider to change them. `scripts`, `vendors`, `networkBlocker`,
 `iframeBlocker`, `consentCategories`, `overrides`, `user`, `callbacks` and
 `enabled` apply when they change.
 
-| Option                        | Purpose                                                                                                                               |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`                        | Required. `hosted({ url })` for a backend, `offline()` for local policies, or `custom()` for your own transport                       |
-| `prefetch`                    | Server-resolved state, or a promise of it, from a framework adapter's server helper                                                   |
-| `scripts`                     | Consent-gated vendor scripts. See [scripts and embeds](../scripts.md)                                                                 |
-| `vendors`                     | Vendors listed under their category with their own switch. See [vendor consent](../vendor-consent.md)                                 |
-| `scriptLoader`                | Options for the script loader module                                                                                                  |
-| `networkBlocker`              | Rules that hold `fetch` and `XMLHttpRequest` calls until their category is allowed, or `false`                                        |
-| `iframeBlocker`               | Gates DOM iframes that carry `data-category`. On by default; `false` turns it off                                                     |
-| `persistence`                 | Stores the visitor's choice in a cookie and localStorage. On by default                                                               |
-| `storageConfig`               | Storage key and cookie settings for the stored choice                                                                                 |
-| `clearOnRevocation`           | Cookies and storage keys to delete when a category is denied                                                                          |
-| `reloadOnConsentRevoked`      | Reload the page after the visitor turns off a granted category or vendor. Defaults to `true`                                          |
-| `consentCategories`           | Categories the preference dialog offers alongside those your scripts use, within the policy's scope                                   |
-| `overrides`                   | Force the country, region or language the policy is resolved for, for testing                                                         |
-| `user`                        | Link consent records to a signed-in user                                                                                              |
-| `callbacks`                   | Choice, permission and error events                                                                                                   |
-| `i18n`                        | Languages and message overrides                                                                                                       |
-| `legalLinks`                  | Privacy policy and other links shown in the banner and dialog                                                                         |
-| `theme`                       | `consentActions` and slot styles. Tokens go through `ConsentTheme`; see [customize](../customize.md)                                  |
-| `components`                  | Slot attributes per component part                                                                                                    |
-| `presentation`                | Banner and dialog shape, position and blocking                                                                                        |
-| `experiment`                  | A/B test of `presentation`, read once at mount. See [banner experiments](../../../guides/banner-experiments.md)                       |
-| `colorScheme`                 | `'light'`, `'dark'`, `'system'`, or `null` to leave the `c15t-dark` class alone                                                       |
-| `noStyle`, `disableAnimation` | Drop the built-in styles, or turn off animations                                                                                      |
-| `preloadDialog`               | When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](./consent-dialog.md#behavior) |
-| `nonce`                       | Content Security Policy nonce for script elements c15t inserts                                                                        |
-| `enabled`                     | Set `false` only when you deliberately bypass consent enforcement                                                                     |
+| Option                        | Purpose                                                                                                                                                                          |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                        | Required. `hosted({ url })` for a backend, `manifest()` from `@c15t/browser/headless` for a bundled policy, `offline()` for local policies, or `custom()` for your own transport |
+| `prefetch`                    | Server-resolved state, or a promise of it, from a framework adapter's server helper                                                                                              |
+| `scripts`                     | Consent-gated vendor scripts. See [scripts and embeds](../scripts.md)                                                                                                            |
+| `vendors`                     | Vendors listed under their category with their own switch. See [vendor consent](../vendor-consent.md)                                                                            |
+| `scriptLoader`                | Options for the script loader module                                                                                                                                             |
+| `networkBlocker`              | Rules that hold `fetch` and `XMLHttpRequest` calls until their category is allowed, or `false`                                                                                   |
+| `iframeBlocker`               | Gates DOM iframes that carry `data-category`. On by default; `false` turns it off                                                                                                |
+| `persistence`                 | Stores the visitor's choice in a cookie and localStorage. On by default                                                                                                          |
+| `storageConfig`               | Storage key and cookie settings for the stored choice                                                                                                                            |
+| `clearOnRevocation`           | Cookies and storage keys to delete when a category is denied                                                                                                                     |
+| `reloadOnConsentRevoked`      | Reload the page after the visitor turns off a granted category or vendor. Defaults to `true`                                                                                     |
+| `consentCategories`           | Categories the preference dialog offers alongside those your scripts use, within the policy's scope                                                                              |
+| `overrides`                   | Force the country, region or language the policy is resolved for, for testing                                                                                                    |
+| `user`                        | Link consent records to a signed-in user                                                                                                                                         |
+| `callbacks`                   | Choice, permission and error events                                                                                                                                              |
+| `i18n`                        | Languages and message overrides                                                                                                                                                  |
+| `legalLinks`                  | Privacy policy and other links shown in the banner and dialog                                                                                                                    |
+| `theme`                       | `consentActions` and slot styles. Tokens go through `ConsentTheme`; see [customize](../customize.md)                                                                             |
+| `components`                  | Slot attributes per component part                                                                                                                                               |
+| `presentation`                | Banner and dialog shape, position and blocking                                                                                                                                   |
+| `experiment`                  | A/B test of `presentation`, read once at mount. See [banner experiments](../../../guides/banner-experiments.md)                                                                  |
+| `journey`                     | Random id that links each `/init` to the save that follows. See [session reports](../../../concepts/data-fetching.md#link-an-init-to-the-save-that-follows)                      |
+| `colorScheme`                 | `'light'`, `'dark'`, `'system'`, or `null` to leave the `c15t-dark` class alone                                                                                                  |
+| `noStyle`, `disableAnimation` | Drop the built-in styles, or turn off animations                                                                                                                                 |
+| `preloadDialog`               | When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](./consent-dialog.md#behavior)                                            |
+| `nonce`                       | Content Security Policy nonce for script elements c15t inserts                                                                                                                   |
+| `enabled`                     | Set `false` only when you deliberately bypass consent enforcement                                                                                                                |
 
 `enabled: false` grants categories and allows gated loading while suppressing
 consent UI. It is not a way to fix failed initialization or hide a banner in

package/docs/frameworks/react/components.md

@@ -36,20 +36,25 @@ Most apps start with four components. `ConsentProvider` holds the runtime,
 one file:
 
 ```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
+import { consentManifest } from './c15t-manifest';
 import { scripts } from './scripts';
 
 import 'c15t/react/styles.css';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = manifest({
+	backendURL:
+		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+	manifest: consentManifest,
+});
 
 export const Consent = ({ children }: { children: ReactNode }) => (
 	<ConsentProvider options={{ mode, scripts }}>

package/docs/frameworks/react/quickstart.md

@@ -7,10 +7,11 @@ group: frameworks
 
 ## Before you start
 
-This guide sets up a client-rendered React app built with Vite. The browser
-loads the page, resolves the visitor's policy, then shows the banner or runs
-the scripts the visitor allowed. The build-time step bundles the public
-policy; regional policies may still need a backend location request.
+This guide sets up a client-rendered React app built with Vite. The build
+bundles your project's public policy. The browser loads the page, resolves the
+visitor's policy from that bundle, then shows the banner or runs the scripts
+the visitor allowed. Regional policies may still need a backend location
+request.
 
 * **Next.js or TanStack Start?** Use that framework's guide from the
   [framework list](https://c15t.com/docs/frameworks). Their adapters resolve consent on the
@@ -27,21 +28,65 @@ the backend URL.
 [Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
 covers self-hosting and offline mode.
 
-Build-time manifests are the recommended production setup. Complete the
-[build-time manifest step](#bundle-the-manifest-during-builds) before
-deploying, and rebuild after changing policies, translations or vendors.
+Bundling the policy at build time is the recommended production setup.
+Rebuild after changing policies, translations or vendors.
 
 ## Install c15t
 
-| Package manager | Command                                           |
-| :-------------- | :------------------------------------------------ |
-| npm             | `npm install c15t@alpha @c15t/integrations@alpha` |
-| pnpm            | `pnpm add c15t@alpha @c15t/integrations@alpha`    |
-| yarn            | `yarn add c15t@alpha @c15t/integrations@alpha`    |
-| bun             | `bun add c15t@alpha @c15t/integrations@alpha`     |
+| Package manager | Command                                                               |
+| :-------------- | :-------------------------------------------------------------------- |
+| npm             | `npm install c15t@alpha @c15t/browser@alpha @c15t/integrations@alpha` |
+| pnpm            | `pnpm add c15t@alpha @c15t/browser@alpha @c15t/integrations@alpha`    |
+| yarn            | `yarn add c15t@alpha @c15t/browser@alpha @c15t/integrations@alpha`    |
+| bun             | `bun add c15t@alpha @c15t/browser@alpha @c15t/integrations@alpha`     |
 
-`c15t` contains the React adapter at `c15t/react`. `@c15t/integrations` holds the
-vendor loaders used below.
+`c15t` contains the React adapter at `c15t/react` and the Vite plugin at
+`c15t/build`. `@c15t/browser` resolves the bundled policy in the browser.
+`@c15t/integrations` holds the vendor loaders used below.
+
+## Bundle your policy
+
+Add `consentManifest` to `vite.config.ts`:
+
+```ts title="vite.config.ts"
+import react from '@vitejs/plugin-react';
+import { consentManifest } from 'c15t/build';
+import { defineConfig, loadEnv } from 'vite';
+
+export default defineConfig(({ mode }) => {
+	const env = loadEnv(mode, process.cwd(), 'VITE_');
+	return {
+		plugins: [
+			react(),
+			// Downloads the policy and writes src/c15t-manifest.ts.
+			consentManifest({
+				backendURL:
+					env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+			}),
+		],
+	};
+});
+```
+
+`https://benchmarks-inth.inth.app` is a demo project, so the snippet runs as
+is. Replace it with your project's backend URL, exactly as Inth shows it,
+including any path prefix, or set `VITE_C15T_BACKEND_URL` when you build.
+
+`consentManifest` downloads your project's public policy from `/manifest` when
+`vite build` or `vite dev` starts, and writes it to `src/c15t-manifest.ts`.
+Add that file to `.gitignore`.
+
+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 fails the build.
+* Consent choices still go to the backend.
+
+Run `vite build` or `vite dev` before a standalone `tsc`, `vue-tsc` or
+`svelte-check`; the generated file doesn't exist on a fresh checkout. Both
+commands fetch the manifest when they start, so both need the backend.
+`vite preview` serves the last build without fetching.
 
 ## Register your vendor scripts
 
@@ -77,20 +122,25 @@ asks for them, and `ConsentDialogLink` keeps preferences reachable after the
 banner closes.
 
 ```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
+import { consentManifest } from './c15t-manifest';
 import { scripts } from './scripts';
 
 import 'c15t/react/styles.css';
 
-const mode = hosted({ url: 'https://your-project.inth.app' });
+const mode = manifest({
+	backendURL:
+		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
+	manifest: consentManifest,
+});
 
 export const Consent = ({ children }: { children: ReactNode }) => (
 	<ConsentProvider options={{ mode, scripts }}>
@@ -104,8 +154,17 @@ export const Consent = ({ children }: { children: ReactNode }) => (
 );
 ```
 
-Replace `https://your-project.inth.app` with your project's backend URL,
-exactly as Inth shows it, including any path prefix.
+`manifest()` resolves the policy from the bundled snapshot in the browser,
+with no `/manifest` request. Use the same backend URL as in
+`vite.config.ts`: consent choices go to it, and so does an `/init` request
+when the policy depends on the visitor's country or region and the browser
+does not know it. That request returns the backend's current policy, which can
+be newer than the snapshot. Vite reads `VITE_C15T_BACKEND_URL` at build time
+for both files, so set it before you build, not when you serve the files.
+
+To apply policy edits without rebuilding, remove `consentManifest` and use
+`hosted({ url })` from `c15t/react` as the mode. The browser then requests the
+policy from `/init` on every page load.
 
 Wrap your app with it in `src/main.tsx`:
 
@@ -131,66 +190,6 @@ router, render the router inside `Consent` so navigation does not remount the
 provider. The stylesheet import in `src/consent.tsx` styles the banner and
 dialog; import it once.
 
-## Bundle the manifest during builds
-
-The build fetches your public policy once and bundles it, so the server never
-fetches it at runtime.
-
-Add `consentManifest` to your existing Vite plugin list:
-
-```ts title="vite.config.ts (plugins option)"
-import { consentManifest } from 'c15t/build';
-
-export default {
-	plugins: [
-		// Keep your existing framework plugins here.
-		consentManifest({ backendURL: 'https://your-project.inth.app' }),
-	],
-};
-```
-
-Vite writes `src/c15t-manifest.ts` before compiling, including at development
-startup. Keep the generated file out of Git. Install `@c15t/browser@alpha` for
-its browser manifest transport. In the quickstart's `src/consent.tsx`, replace
-the `hosted()` mode with this factory:
-
-```tsx title="src/consent.tsx"
-import { manifest } from '@c15t/browser/headless';
-
-import { consentManifest } from './c15t-manifest';
-
-const mode = manifest({
-	backendURL: 'https://your-project.inth.app',
-	manifest: consentManifest,
-});
-```
-
-Keep passing `mode` to `ConsentProvider`. The browser resolves the snapshot
-without `/manifest` when it has the geography the policy needs, or the policy
-does not depend on geography. Supply known country and region through `inputs`
-or overrides to keep regional resolution on the snapshot.
-
-When the required country or region is missing, the transport calls backend
-`/init` and uses its resolved policy and translations. That response can use
-newer backend policy than the build snapshot. This is a full consent resolution,
-so these visitors still wait for a backend round trip.
-
-Policy and resolver code are part of the browser bundle.
-
-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 fails the build.
-* Consent choices still go to the backend.
-
-Run `vite build` or `vite dev` before a standalone `tsc`, `vue-tsc` or
-`svelte-check`; the generated file doesn't exist on a fresh checkout.
-
-For policy updates without a rebuild, keep the original `hosted()` factory
-and omit the build plugin. That setup resolves policy through the backend
-`/init` on each page load.
-
 ## Gate your own features
 
 Read a category's permission with `useConsent` inside the provider:
@@ -215,8 +214,8 @@ Build and preview the production bundle with `vite build` and `vite preview`,
 then open the site in a private window with DevTools open on the Network tab.
 Test under a policy that asks for a choice, such as an EU opt-in policy.
 
-1. **Before a choice.** The banner shows. There are no requests to
-   `posthog.com`.
+1. **Before a choice.** The banner shows, with no `/manifest` request. There
+   are no requests to `posthog.com`.
 2. **Reject All.** The banner closes and the vendor requests stay absent.
 3. **Reload.** The banner stays closed and the vendor requests stay absent.
 4. **Privacy settings.** The footer link opens the dialog with **Analytics** (the