@c15t/react 3.0.0-alpha.9 → 3.0.0

package/docs/frameworks/react/iab.md

@@ -53,8 +53,7 @@ Global Vendor List response before changing rendering conditions.
 
 IAB presentation follows `presentation.prompt.blocking` and
 `presentation.preferences.blocking`. A blocking dialog needs focus management,
-scroll locking and a backdrop together. See [migration](../../upgrade-v3.md) for
-legacy option behavior.
+scroll locking and a backdrop together.
 
 ## Mount IABProvider for every IAB policy
 
@@ -68,6 +67,25 @@ your error boundary or the framework's error overlay shows it. Render `IABProvid
 `c15t/react/iab` for those visitors, or remove the `iab` model from the
 policy.
 
+## When the dialog loads
+
+`IABConsentDialog` loads its code on demand, so the first page load
+carries the banner without the preference center. The code downloads at
+the first of:
+
+* The browser's first idle period after the page's `load` event, while
+  the IAB banner is shown.
+* Hover or focus on the banner's Customize button or partners link.
+* The dialog opening.
+
+A visitor who opens the dialog before the download finishes waits for
+it. `open={true}` and `showTrigger` load it on mount, under a model the
+dialog's `models` prop lists. Under another model, `showTrigger` loads
+only the trigger. Set
+`preloadDialog: 'intent'` in the consent provider options to skip the
+idle download. Idle loading is also skipped with Save-Data on, on `2g`
+and `slow-2g` connections, and while offline.
+
 ## Verify vendor and purpose choices
 
 Test category choices alongside vendor, purpose, legitimate-interest and special

package/docs/frameworks/react/quickstart.md

@@ -7,11 +7,10 @@ group: frameworks
 
 ## Before you start
 
-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.
+This guide sets up a client-rendered React app built with Vite. The browser
+loads the page and asks your consent backend for the visitor's policy, then
+shows the banner or runs the scripts the visitor allowed. The backend reads the
+visitor's location from the request, so regional policies need no extra setup.
 
 * **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
@@ -28,93 +27,52 @@ the backend URL.
 [Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
 covers self-hosting and offline mode.
 
-Bundling the policy at build time is the recommended production setup.
-Rebuild after changing policies, translations or vendors.
+The guide uses `hosted()` mode. Policy, translation and vendor edits in your
+project reach visitors on their next page load, without a rebuild.
 
 ## Install c15t
 
-| 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`     |
+| Package manager | Command                               |
+| :-------------- | :------------------------------------ |
+| npm             | `npm install c15t @c15t/integrations` |
+| pnpm            | `pnpm add c15t @c15t/integrations`    |
+| yarn            | `yarn add c15t @c15t/integrations`    |
+| bun             | `bun add c15t @c15t/integrations`     |
 
 `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.
+`c15t/build`. `@c15t/integrations` holds the vendor loaders used below.
 
-## Bundle your policy
+## Add the Vite plugin
 
 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 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.
-
-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.
+import { defineConfig } from 'vite';
 
-## Register your vendor scripts
-
-Create `src/scripts.ts`. PostHog waits for measurement permission, so your
-policy must include that category. Remove any other PostHog loader from your
-app so PostHog loads once.
+export default defineConfig({ plugins: [react(), consentManifest()] });
+```
 
-```ts title="src/scripts.ts"
-import { posthog } from '@c15t/integrations/posthog';
+The plugin reads `VITE_C15T_BACKEND_URL`. Set it to your project's backend URL,
+exactly as Inth shows it, including any path prefix, in `.env` or wherever you
+build:
 
-export const scripts = [
-	posthog({
-		id: 'phc_your_project_key',
-		initOptions: { cookieless_mode: 'never' },
-		loadMode: 'after-consent',
-	}),
-];
+```sh title=".env"
+VITE_C15T_BACKEND_URL=https://your-project.inth.app
 ```
 
-Replace `phc_your_project_key` with your PostHog project key. PostHog uses its
-EU host; add `region: 'us'` for a US project.
+If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
+too. When both are set, `VITE_C15T_BACKEND_URL` wins.
 
-`loadMode: 'after-consent'` keeps the PostHog SDK off the page until the
-visitor allows measurement. `cookieless_mode: 'never'` turns off PostHog's
-cookieless capture. See [integrations](../../integrations/overview.md) for other
-vendors.
+`consentManifest` hands the backend URL to `hosted()` through
+`c15t/generated`. No file is written into your project. Without the plugin,
+pass the URL as `hosted({ backendURL })`.
+
+The plugin also adds a small script to `index.html` that sends `/init` while
+your JavaScript downloads, so the banner shows sooner.
+[Rendering](./rendering.md#send-init-before-the-app-loads)
+covers when to turn it off.
 
 ## Mount the provider
 
@@ -124,26 +82,30 @@ asks for them, and `ConsentDialogLink` keeps preferences reachable after the
 banner closes.
 
 ```tsx title="src/consent.tsx"
-import { manifest } from '@c15t/browser/headless';
+import { posthog } from '@c15t/integrations/posthog';
 import {
 	ConsentBanner,
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
-import { consentManifest } from './c15t-manifest';
-import { scripts } from './scripts';
-
-const mode = manifest({
-	backendURL:
-		import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://benchmarks-inth.inth.app',
-	manifest: consentManifest,
-});
+const options = {
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
+	scripts: [
+		posthog({
+			id: 'phc_your_project_key',
+			initOptions: { cookieless_mode: 'never' },
+			loadMode: 'after-consent',
+		}),
+	],
+};
 
 export const Consent = ({ children }: { children: ReactNode }) => (
-	<ConsentProvider options={{ mode, scripts }}>
+	<ConsentProvider options={options}>
 		{children}
 		<ConsentBanner />
 		<ConsentDialog />
@@ -154,17 +116,21 @@ export const Consent = ({ children }: { children: ReactNode }) => (
 );
 ```
 
-`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.
+`hosted()` makes one `/init` request to your backend, started early by the
+script in `index.html`. The backend picks the policy from the visitor's
+location and language and returns its current version. Consent choices go to
+the same backend. Vite reads `VITE_C15T_BACKEND_URL` at build time, 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.
+PostHog waits for measurement permission, so your policy must include that
+category. Replace `phc_your_project_key` with your PostHog project key.
+PostHog uses its EU host; add `region: 'us'` for a US project. Remove any
+other PostHog loader from your app so PostHog loads once.
+
+`loadMode: 'after-consent'` keeps the PostHog SDK off the page until the
+visitor allows measurement. `cookieless_mode: 'never'` turns off PostHog's
+cookieless capture. See [integrations](../../integrations/overview.md) for other
+vendors.
 
 Wrap your app with it in `src/main.tsx`:
 
@@ -214,7 +180,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, with no `/manifest` request. There
+1. **Before a choice.** One `/init` request goes to your backend URL, starting
+   before your JavaScript finishes downloading, and the banner shows. 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.
@@ -223,8 +190,7 @@ Test under a policy that asks for a choice, such as an EU opt-in policy.
    save. PostHog's `array.js` loads.
 5. **Turn Analytics off again.** The page reloads and PostHog does not load.
 
-If the banner never appears, check the generated policy and any location
-request to `/init` on your backend URL. [Troubleshooting](./troubleshooting.md)
+If the banner never appears, check the `/init` request to your backend URL. [Troubleshooting](./troubleshooting.md)
 covers the common causes. [Verify consent](../../guides/verify-consent.md) has the
 full release checklist.
 

package/docs/frameworks/react/rendering.md

@@ -23,92 +23,50 @@ read the visitor's cookie and location on the server, so the banner can be in
 the first HTML. [Choose your setup](../../concepts/choose-your-setup.md#server-rendering-or-browser-rendering)
 explains the difference in general terms.
 
-## Bundle the manifest during Vite builds
-
-The [quickstart](./quickstart.md) and `examples/react` in
-the c15t repository use this setup.
-
-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 `src/consent.tsx`, create the provider's
-mode with `manifest()` instead of `hosted()`:
-
-```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 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.
-
-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.
-
-For policy updates without a rebuild, use `hosted({ url })` from `c15t/react`
-as the mode and omit the build plugin. That setup resolves policy through the
-backend `/init` on each page load.
-
 ## Client-rendered apps
 
-The recommended [quickstart](./quickstart.md) bundles the
-manifest and resolves it in the browser. See [build-time manifests](#bundle-the-manifest-during-vite-builds).
-
-For policy updates without rebuilding, use `hosted({ url })` from
-`c15t/react` as the mode. That runtime path works as follows:
+The [quickstart](./quickstart.md) and `examples/react` in
+the c15t repository use `hosted()` from `c15t/react`. It reads the backend URL
+`consentManifest` read from `VITE_C15T_BACKEND_URL` or
+`VITE_INTH_PROJECT_URL`; without the plugin, pass `hosted({ backendURL })`.
+Policy edits apply on the next page load, without a rebuild. The page loads
+like this:
 
 1. The page loads with no consent state. Every optional category is denied.
-2. `ConsentProvider` requests `GET /init` from your backend URL while it first
-   renders, before the page paints. The backend picks the visitor's policy
-   from their location. With an `experiment`, the request waits until the
-   provider mounts, because it carries the visitor's arm.
+2. The browser requests `GET /init` from your backend URL. A
+   [script in `index.html`](#send-init-before-the-app-loads) sends it while
+   the JavaScript downloads. The backend picks the visitor's policy from their
+   location. With an `experiment`, pass it to the plugin as
+   `initPrefetch: { experiment }` so the early request carries the visitor's
+   arm. Without that, the provider sends its own `/init` when it mounts.
 3. The provider applies the policy and any stored choice. It shows the banner
    if the policy asks for one, and loads the scripts the visitor allowed.
 
 Until step 3 finishes, gated scripts and `ConsentGate` embeds stay blocked. If
 the backend request fails, they stay blocked and no banner shows.
 
+### Send `/init` before the app loads
+
+`consentManifest()` adds a small inline script to the `<head>` of
+`index.html`. It sends `/init` while the browser downloads your JavaScript,
+and `hosted()` uses that response instead of sending its own. The banner
+usually shows 50 to 250 ms sooner. There is nothing to configure.
+
+The early request can't read your app's options, so in a few setups it won't
+match and the app sends a second `/init`. Pass `initPrefetch: false` when the
+app uses `offline()` or gives `hosted()` its own `backendURL`, `fetch`,
+`initURL` or `headers`. With its own `fetch`, `hosted()` sends `/init` through
+it and ignores the early response. If it sets `credentials`, `overrides`, `storageKey`, an
+`experiment`, or `journey: false`, pass the same values as
+`initPrefetch: { credentials, experiment, journey, overrides, storageKey }`.
+With `journey: 'tab'`, passing it too makes a tab's first `/init` report the
+`'tab'` scope instead of `'page'`. It doesn't save a request.
+Pass `experiment` only when c15t assigns the arm. If a feature flag picks
+it, leave it out, or the script sends an arm the visitor may never see.
+The dev server adds the script even to a `manifest()` app, which then sends
+one `/init` per page load that it doesn't use. A production build leaves it
+out.
+
 ## React Router, Remix and other server-rendered apps
 
 React Router framework mode, Remix and similar frameworks have no c15t adapter.
@@ -119,23 +77,26 @@ around the outlet. In React Router framework mode that is `app/root.tsx`.
 browser takes over after hydration:
 
 * The server HTML contains your page but no banner and no consent state.
-* After hydration the browser resolves the bundled manifest, then shows the
-  banner if the policy asks for one. When required country or region is
-  missing, it calls `/init` and uses the backend's current policy and
-  translations, which can differ from the build snapshot. With `hosted()`,
-  it always calls `/init`.
+* After hydration the browser calls `/init`, then shows the banner if the
+  policy asks for one.
 * The server render and the first browser render agree, so hydration does not
   warn or change a stored choice.
 
 The Vite setup needs no change. The banner renders in the browser and brings
 its own `<style>` element, so there is no stylesheet to import.
 
+These frameworks render their own HTML, so the Vite plugin can't add the
+early `/init` script. Put `buildPrefetchScript({ backendURL })` from `c15t` in
+a `<script>` in the root `<head>` instead, unless your loader supplies
+`initialData` as described below. The two are alternatives: with
+`initialData` the provider never reads the script's response.
+
 ### Skip the browser's first init request
 
 This is optional. `fetchSSRData` from `c15t/react/server` calls the backend's
 `/init` from your server loader, forwarding the visitor's location and
 language headers. Pass the result to the browser, wrap it in a promise and give
-it to `hosted({ url, initialData })`. The provider's first init then uses that
+it to `hosted({ backendURL, initialData })`. The provider's first init then uses that
 response instead of a network request.
 
 Know its limits before you add it:
@@ -171,9 +132,9 @@ browser path.
 ## Static and prerendered pages
 
 A prerendered page is the same HTML for every visitor, so it cannot contain one
-visitor's consent. Use the quickstart's build-time snapshot. Consent saves and
-any `/init` requests go to the backend URL directly, so the static host
-needs no server route. Add the site's
+visitor's consent. Use the quickstart's setup. `/init` requests and consent
+saves go to the backend URL directly, so the static host needs no server
+route. Add the site's
 origin to the trusted origins in your Inth project.
 
 Do not cache a response that contains a visitor's consent in a CDN or a shared
@@ -182,17 +143,13 @@ cache.
 
 ## Where the browser sends requests
 
-With `hosted({ url })`, the browser calls two backend endpoints:
+With `hosted()`, the browser calls two backend endpoints:
 
 | Request               | When                                       |
 | --------------------- | ------------------------------------------ |
 | `GET {url}/init`      | Once per page load, to resolve the policy  |
 | `POST {url}/subjects` | When the visitor accepts, rejects or saves |
 
-With a bundled manifest, `manifest({ backendURL })` sends the same
-`/subjects` request, and requests `/init` only when the policy depends on a
-country or region the browser does not know.
-
 These requests go to the backend's origin, so it must list your site as a
 trusted origin.
 [Data fetching](../../concepts/data-fetching.md) compares this with proxies and
@@ -203,9 +160,126 @@ custom transports.
 1. Open the page in a private window and view the page source. In a
    server-rendered app the HTML contains your content and no element with
    `data-testid="consent-banner-root"`.
-2. In DevTools Network, confirm there is no `/manifest` request with a
-   build-time snapshot. A regional policy may still need an `/init` request
-   to resolve consent when geography is missing. With `hosted()`, one `/init`
-   request runs unless you supply `initialData`.
+2. In DevTools Network, confirm one `/init` request runs, unless you supply
+   `initialData`.
 3. The banner appears once the policy resolves. Vendor requests stay absent
    until you allow their category.
+
+## Bundle the policy at build time
+
+`manifest()` resolves the policy in the browser from a snapshot the build
+downloaded. It saves the `/init` request only in these cases:
+
+* The policy has no location rules, or every location gets the same banner.
+* The page already knows the visitor's location, for example from an edge
+  worker, and passes it as `inputs`.
+* You run a same-origin `geoURL` route that returns the location.
+
+Otherwise the browser still calls `/init` on a first visit and uses the
+backend's answer, so the bundle adds bytes without saving a request.
+`consentManifest` warns during the build when that happens. The resolver adds
+about 3 KB gzipped to the bundle, and policy edits need a rebuild. The browser
+sends no `/init`, so the backend doesn't count visitors it resolves this way.
+
+The build fetches your public policy once and bundles it, so the server never
+fetches it at runtime.
+
+Keep `consentManifest` in your 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' }),
+	],
+};
+```
+
+Without `backendURL`, the plugin reads `VITE_C15T_BACKEND_URL`, then
+`VITE_INTH_PROJECT_URL`. The plugin
+fetches the policy during `vite build`, or in `vite dev` when the app first
+loads it, and serves it as `snapshot` from `c15t/generated`. A build fetches
+only when the app uses `manifest()`. In `src/consent.tsx`, create the
+provider's mode with `manifest()` from `c15t/react` instead of `hosted()`. It
+reads the snapshot and the backend URL from `c15t/generated`:
+
+```tsx title="src/consent.tsx"
+import { manifest } from 'c15t/react';
+
+const mode = manifest();
+```
+
+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 build has no snapshot, as in `vite dev` after a failed fetch,
+`snapshot` is `undefined`, and the browser fetches
+`${backendURL}/manifest` instead.
+
+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. `ConsentProvider` sends that
+request while it first renders, before the page mounts, unless the visitor has
+a stored choice.
+
+The browser cannot guess the banner from the snapshot alone when locations
+differ. With a European opt-in rule and no banner elsewhere, a banner shown
+before `/init` answers would vanish for most of the world. The exception is a
+policy whose country and region rules all show the same banner, with a default
+rule that covers everywhere else: the browser resolves it at once.
+
+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.
+* 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](../../concepts/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](../../concepts/modes.md#what-happens-when-the-download-fails)
+lists every case.
+
+`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
+serves the last build without fetching. The plugin writes no file into your
+app, so there is nothing to keep out of Git. `c15t/generated` ships its own
+types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
+a build first.
+
+The plugin can't see the options your app passes to `manifest()`. When the
+app passes `source: 'runtime'` or `manifestURL`, set
+`consentManifest({ source: 'runtime' })` too. The build then downloads no
+manifest, so it doesn't fail when the backend's `/manifest` is down.

package/docs/frameworks/react/scripts.md

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