@c15t/react 3.0.0-alpha.10 → 3.0.0-alpha.11

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?
 
@@ -53,7 +53,9 @@ 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:
@@ -133,7 +135,11 @@ 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.
 
@@ -161,6 +167,14 @@ 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.

package/docs/concepts/modes.md

@@ -15,15 +15,18 @@ 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://v3.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. Choices post to `/subjects`. | Most apps. Rebuild to ship policy changes, or set `source: 'runtime'`.                                           |
-| `hosted()`                | The backend's `GET /init`                                                                                           | One `/init` per page that resolves consent.              | Static hosting without a server, or a policy that changes without a rebuild and needs the backend's geolocation. |
-| `offline()`               | The browser, from rules in your bundle                                                                              | None. Choices stay in the browser.                       | Local development, tests and demos. Not recommended for production environments.                                 |
+| 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. Their quickstarts use `manifest()`. The script tag picks its
+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://v3.c15t.com/docs/frameworks/html/attributes-and-api#choose-a-mode).
 

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

@@ -18,13 +18,13 @@ import {
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	manifest,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
 const options = {
-	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
-	mode: manifest(),
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
 	scripts: [
 		posthog({
 			id: 'phc_your_project_key',

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

@@ -20,13 +20,13 @@ import {
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	manifest,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
 const options = {
-	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
-	mode: manifest(),
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
 	scripts: [
 		posthog({
 			id: 'phc_your_project_key',

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

@@ -20,13 +20,13 @@ import {
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	manifest,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
 const options = {
-	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
-	mode: manifest(),
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
 	scripts: [
 		posthog({
 			id: 'phc_your_project_key',
@@ -48,11 +48,14 @@ export const Consent = ({ children }: { children: ReactNode }) => (
 );
 ```
 
-`manifest()` from `c15t/react` resolves the policy from the snapshot
-`consentManifest()` bundled, and sends consent choices to the backend URL the
-plugin read from `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`. Set one
-to the backend URL from your Inth project. To fetch the policy from the backend on every page
-load instead, pass `hosted()` from `c15t/react`. The Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
+`hosted()` from `c15t/react` asks the backend's `/init` for the visitor's
+policy on each page load, and sends consent choices to the same backend. It
+uses the backend URL `consentManifest()` read from `VITE_C15T_BACKEND_URL` or
+`VITE_INTH_PROJECT_URL`. Set one to the backend URL from your Inth project. To
+resolve a bundled policy in the browser instead, pass `manifest()` from
+`c15t/react`; see
+[rendering](../rendering.md#bundle-the-policy-at-build-time).
+The Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
 this provider and passes it server-resolved state.
 
 ## Provider options
@@ -67,7 +70,7 @@ the provider to change them. `scripts`, `vendors`, `networkBlocker`,
 
 | Option                        | Purpose                                                                                                                                                                                                                         |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`                        | Required. `manifest()` for a bundled policy, `hosted()` for the backend's `/init`, `offline()` for local policies, all from `c15t/react`, or `custom()` for your own transport. See [consent modes](../../../concepts/modes.md) |
+| `mode`                        | Required. `hosted()` for the backend's `/init`, `manifest()` for a bundled policy, `offline()` for local policies, all from `c15t/react`, or `custom()` for your own transport. See [consent modes](../../../concepts/modes.md) |
 | `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)                                                                                                                           |

package/docs/frameworks/react/components.md

@@ -42,13 +42,13 @@ import {
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	manifest,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
 const options = {
-	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
-	mode: manifest(),
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
 	scripts: [
 		posthog({
 			id: 'phc_your_project_key',

package/docs/frameworks/react/content-security-policy.md

@@ -16,6 +16,7 @@ A React app with c15t adds these to the page, and your policy must allow them:
 | `c15t/react/styles.css`, only if you import it with `styles: false`                                             | `style-src 'self'`                                    |
 | The `<style id="c15t-theme">` element, if you render `ConsentTheme`                                             | `style-src` with a nonce or its hash                  |
 | `<script>` elements the script loader creates for `scripts` entries, both `src` and inline                      | `script-src` with each vendor's host, or a nonce      |
+| The inline `<script>` that `consentManifest()` adds to `index.html` to send `/init` early                       | `script-src` with a nonce or its hash                 |
 | With server rendering, the inline `<script>` before the banner's buttons that holds a tap made before hydration | `script-src` with a nonce or its hash                 |
 | Browser requests to your backend's `/init` and `/subjects`                                                      | `connect-src` with the backend origin                 |
 | Iframes inside `ConsentGate`, and the frames, images and requests your vendors load                             | `frame-src`, `img-src`, `connect-src` for each vendor |
@@ -70,8 +71,9 @@ entry takes precedence for that element. The stock components put it on the
 With Vite, set `html.cspNonce` to a placeholder in `vite.config.ts`, and have
 your server replace it with a new nonce on every response. Vite then adds
 `<meta property="csp-nonce" nonce="...">` to the page, and the browser keeps the
-value in the tag's `nonce` property. Read it where you create the provider, in
-the quickstart's `src/consent.tsx`:
+value in the tag's `nonce` property. Vite also stamps the nonce on the early
+`/init` script. Read it where you create the provider, in the
+quickstart's `src/consent.tsx`:
 
 ```tsx title="src/consent.tsx (partial)"
 const nonce =
@@ -88,6 +90,10 @@ The provider reads `options.nonce` once, when it mounts. A server-rendered
 React app, such as one built with React Router framework mode, reads the nonce
 from its own request and passes it the same way.
 
+On a static host, allow the early `/init` script by the hash in the browser's
+`Refused to execute inline script` error. If the policy blocks it, the app
+sends `/init` itself.
+
 ## Allow c15t's style elements
 
 The banner, dialog and other stock components render c15t's rules as

package/docs/frameworks/react/iab.md

@@ -67,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://v3.c15t.com/docs/frameworks). Their adapters resolve consent on the
@@ -28,8 +27,8 @@ 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
 
@@ -43,7 +42,7 @@ Rebuild after changing policies, translations or vendors.
 `c15t` contains the React adapter at `c15t/react` and the Vite plugin at
 `c15t/build`. `@c15t/integrations` holds the vendor loaders used below.
 
-## Bundle your policy
+## Add the Vite plugin
 
 Add `consentManifest` to `vite.config.ts`:
 
@@ -66,60 +65,14 @@ VITE_C15T_BACKEND_URL=https://your-project.inth.app
 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.
 
-`consentManifest` downloads your project's public policy from `/manifest`
-during `vite build`, or in `vite dev` when the app first loads it, and serves
-it to your app as `snapshot`
-from `c15t/generated`. No file is written into your project.
+`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 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.
+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
 
@@ -135,13 +88,13 @@ import {
 	ConsentDialog,
 	ConsentDialogLink,
 	ConsentProvider,
-	manifest,
+	hosted,
 } from 'c15t/react';
 import type { ReactNode } from 'react';
 
 const options = {
-	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
-	mode: manifest(),
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
 	scripts: [
 		posthog({
 			id: 'phc_your_project_key',
@@ -163,18 +116,11 @@ export const Consent = ({ children }: { children: ReactNode }) => (
 );
 ```
 
-`manifest()` resolves the policy from the bundled snapshot in the browser,
-with no `/manifest` request. It reads the snapshot and the backend URL from
-what `consentManifest` downloaded. Consent choices go to that backend, 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, so set it before you build, not when
-you serve the files.
-
-To apply policy edits without rebuilding, use `hosted()` from `c15t/react` as
-the mode. The browser then requests the policy from `/init` on every page load.
-[Consent modes](../../concepts/modes.md) compares the three modes.
+`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.
 
 PostHog waits for measurement permission, so your policy must include that
 category. Replace `phc_your_project_key` with your PostHog project key.
@@ -234,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.
@@ -243,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.