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

package/docs/frameworks/react/quickstart.md

@@ -1,143 +1,261 @@
 ---
 title: Quickstart
-description: Connect a React application to Inth and add consent UI, persistence
-  and a preferences link.
+description: Add a consent banner, preferences dialog and consent-gated scripts
+  to a React single-page app built with Vite, using Inth as the consent backend.
 group: frameworks
 ---
 
-## Connect Inth
+## Before you start
 
-[Create an Inth project](https://inth.com), configure policy rules and the app's
-allowed origin, and copy its backend endpoint. This guide uses a client-rendered
-React app with Vite. Applications with a framework server should use that
-framework's adapter for request prefetch.
+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.
 
-| Package manager | Command                          |
-| :-------------- | :------------------------------- |
-| npm             | `npm install c15t @c15t/scripts` |
-| pnpm            | `pnpm add c15t @c15t/scripts`    |
-| yarn            | `yarn add c15t @c15t/scripts`    |
-| bun             | `bun add c15t @c15t/scripts`     |
+* **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
+  server.
+* **React Router framework mode, Remix or another server-rendered React app?**
+  This guide still works. The server renders the page without consent state and
+  the browser resolves it after hydration. Read
+  [rendering](./rendering.md#react-router-remix-and-other-server-rendered-apps)
+  for what that means for the first paint.
 
-Set `VITE_C15T_BACKEND_URL` to the endpoint from Inth. Vite embeds public values
-at build time, so rebuild when changing it. Keep management credentials out of
-public variables.
+You need an [Inth](https://inth.com) project. In the project, set the policy
+rules for your regions, add your site's origin to the trusted origins, and copy
+the backend URL.
+[Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
+covers self-hosting and offline mode.
 
-## Register consent-gated scripts
+Bundling the policy at build time is the recommended production setup.
+Rebuild after changing policies, translations or vendors.
 
-Include measurement and marketing categories in your policy for these vendors.
-Remove any existing loaders for them so each script loads once.
+## Install c15t
 
-This setup uses Vite's public environment variables. Set the Inth endpoint and
-add your PostHog project key, PostHog API host and X Pixel ID in `.env.local`:
+| 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`     |
 
-```dotenv title=".env.local"
-VITE_C15T_BACKEND_URL=
-VITE_POSTHOG_KEY=
-VITE_POSTHOG_HOST=
-VITE_X_PIXEL_ID=
+`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 `consentManifest` to `vite.config.ts`:
+
+```ts title="vite.config.ts"
+import react from '@vitejs/plugin-react';
+import { consentManifest } from 'c15t/build';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [react(), consentManifest()] });
 ```
 
-Copy the exact backend endpoint from Inth. The vendor IDs are optional: leaving
-an ID empty disables that integration. When enabling PostHog, fill in both its project key and the API host
-shown in your PostHog project. Restart Vite after editing these values and
-rebuild for deployment. Other bundlers need their own configuration mechanism.
-
-Create `src/scripts.ts`. PostHog waits for measurement permission with
-`loadMode: 'after-consent'` and disables cookieless capture with
-`cookieless_mode: 'never'`. X Pixel waits for marketing permission.
-
-```ts title="src/scripts.ts"
-import { posthog } from '@c15t/scripts/posthog';
-import { xPixel } from '@c15t/scripts/x-pixel';
-
-const posthogKey = import.meta.env.VITE_POSTHOG_KEY;
-const xPixelId = import.meta.env.VITE_X_PIXEL_ID;
-
-export const scripts = [
-	...(posthogKey
-		? [
-				posthog({
-					apiHost: import.meta.env.VITE_POSTHOG_HOST,
-					id: posthogKey,
-					initOptions: { cookieless_mode: 'never' },
-					loadMode: 'after-consent',
-				}),
-			]
-		: []),
-	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
-];
+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:
+
+```sh title=".env"
+VITE_C15T_BACKEND_URL=https://your-project.inth.app
 ```
 
-## Mount the provider and UI
+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.
+
+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.
+
+## Mount the provider
+
+Create `src/consent.tsx`. `ConsentProvider` creates the consent runtime and
+loads the scripts. `ConsentBanner` and `ConsentDialog` render when the policy
+asks for them, and `ConsentDialogLink` keeps preferences reachable after the
+banner closes.
 
 ```tsx title="src/consent.tsx"
-import type { ReactNode } from 'react';
+import { posthog } from '@c15t/integrations/posthog';
 import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogLink,
-  ConsentProvider,
-  hosted,
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	manifest,
 } from 'c15t/react';
-import 'c15t/react/styles.css';
-import { scripts } from './scripts';
-
-const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
-if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
-const mode = hosted({ url: backendURL });
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <footer><ConsentDialogLink>Privacy settings</ConsentDialogLink></footer>
-    </ConsentProvider>
-  );
-}
+import type { ReactNode } from 'react';
+
+const options = {
+	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
+	mode: manifest(),
+	scripts: [
+		posthog({
+			id: 'phc_your_project_key',
+			initOptions: { cookieless_mode: 'never' },
+			loadMode: 'after-consent',
+		}),
+	],
+};
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={options}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
 ```
 
+`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.
+
+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`:
+
 ```tsx title="src/main.tsx"
 import { createRoot } from 'react-dom/client';
-import App from './App';
+
+import { App } from './app';
 import { Consent } from './consent';
 
 const root = document.getElementById('root');
-if (!root) throw new Error('Missing #root element');
-createRoot(root).render(<Consent><App /></Consent>);
+if (!root) {
+	throw new Error('Missing #root element');
+}
+createRoot(root).render(
+	<Consent>
+		<App />
+	</Consent>
+);
 ```
 
-Keep `Consent` mounted across navigation. The banner appears when the resolved
-policy requires a prompt; not every region or returning visitor needs one.
-The dialog link keeps preferences reachable after the prompt closes.
+Keep `Consent` mounted for the life of the app. If you use a client-side
+router, render the router inside `Consent` so navigation does not remount the
+provider. There is no stylesheet to import: the banner and dialog render their
+own rules as `<style>` elements.
 
-## Gate optional functionality
+## Gate your own features
 
-```tsx
+Read a category's permission with `useConsent` inside the provider:
+
+```tsx title="src/marketing-banner.tsx"
 import { useConsent } from 'c15t/react';
 
-export function MarketingContent() {
-  return useConsent('marketing') ? <div>Optional marketing content</div> : null;
+export function MarketingBanner() {
+	return useConsent('marketing') ? <aside>Spring sale</aside> : null;
 }
 ```
 
-This controls the rendered component. Move vendor SDKs into the
-[script loader](./script-loader.md) too. An independently
-loaded analytics script does not wait merely because a consent provider exists.
+`useConsent` returns the permission right now. Under an opt-out policy it can be
+`true` before the visitor has chosen anything. Read
+[how consent works](../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice)
+before you record or report choices. For iframes, use
+[`ConsentGate`](./components/consent-gate.md).
+
+## Check that it works
 
-`useConsent` returns effective permission, not proof of an explicit grant.
-Read [consent state](../../guides/consent-state.md) when recording choice events.
+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.
 
-## Verify and customize
+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
+   `measurement` category) and **Marketing** off. Turn on **Analytics** and
+   save. PostHog's `array.js` loads.
+5. **Turn Analytics off again.** The page reloads and PostHog does not load.
 
-Reject under an opt-in policy, reload and confirm optional requests stay blocked.
-Reopen preferences, save a different choice and test navigation. Follow
-[verification](../../guides/verify-consent.md), then
-[customization](../../customization/overview.md) to apply your design.
+If the banner never appears, check the generated policy and any location
+request to `/init` on your backend URL. [Troubleshooting](./troubleshooting.md)
+covers the common causes. [Verify consent](../../guides/verify-consent.md) has the
+full release checklist.
 
-## Run the complete example
+## Next steps
 
-Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
-YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.
+* [Rendering](./rendering.md) for server-rendered React apps and
+  what the first paint contains.
+* [Scripts and embeds](./scripts.md) for more vendors, network
+  blocking and data cleanup.
+* [Customize](./customize.md) for colors, fonts, layout and copy.
+* [Components](./components/consent-provider.md) for
+  every provider option and component prop.
+* The runnable app in `examples/react` of the
+  [c15t repository](https://github.com/c15t/c15t) contains this setup.

package/docs/frameworks/react/rendering.md

@@ -0,0 +1,263 @@
+---
+title: Rendering and deployment
+description: How c15t resolves consent in client-rendered React apps, React
+  Router framework mode, Remix and other server-rendered React apps without a
+  c15t adapter.
+group: frameworks
+---
+
+## Pick your rendering path
+
+`c15t/react` resolves consent in the browser. That works for every React app,
+including server-rendered ones. What changes is what the first HTML contains.
+
+| Your app                                                                 | Where consent resolves          | Setup                                                                                                         |
+| ------------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Vite, or another client-rendered single-page app                         | Browser, after the bundle loads | [Quickstart](./quickstart.md)                                                                                 |
+| Prerendered or static HTML                                               | Browser, after the page loads   | [Quickstart](./quickstart.md), see [static pages](#static-and-prerendered-pages)                              |
+| React Router framework mode, Remix, or another server-rendered React app | Browser, after hydration        | [Quickstart](./quickstart.md), see [server-rendered apps](#react-router-remix-and-other-server-rendered-apps) |
+| Next.js or TanStack Start                                                | Server, per request             | That framework's guide in the [framework list](https://v3.c15t.com/docs/frameworks)                           |
+
+Pick the Next.js or TanStack Start adapter if you use those frameworks. They
+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' }),
+	],
+};
+```
+
+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. `consentManifest` warns
+during the build when it downloads such a policy, and suggests `hosted()`. 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. `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. To skip the
+round trip for location-specific rules, pass the country your CDN or edge
+already knows through `inputs`.
+
+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.
+
+For policy updates without a rebuild, use `hosted({ backendURL })` 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()` from `c15t/react` as
+the mode. It reads the backend URL `consentManifest` read from
+`VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`; without the plugin, pass
+`hosted({ backendURL })`.
+That runtime path works as follows:
+
+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.
+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.
+
+## React Router, Remix and other server-rendered apps
+
+React Router framework mode, Remix and similar frameworks have no c15t adapter.
+Use the quickstart's `Consent` component and render it in your root component,
+around the outlet. In React Router framework mode that is `app/root.tsx`.
+
+`ConsentProvider` renders on the server without touching browser APIs, and the
+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 the banner depends on a country or
+  region the browser does not know, 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`.
+* 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.
+
+### 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({ backendURL, initialData })`. The provider's first init then uses that
+response instead of a network request.
+
+Know its limits before you add it:
+
+* It saves the browser's round trip to the backend. It does not put the banner
+  in the server HTML; the banner still mounts after hydration.
+* Every page view makes a server-to-server `/init` request. Do not cache the
+  loader response, because it contains one visitor's policy.
+* It returns `undefined` when the request has no location or language headers,
+  and the browser then requests `/init` as usual.
+* `mode` is read once, when the provider mounts. Create the `hosted()` mode once
+  in the browser rather than on every render.
+* A relative `backendURL` resolves against the request's `host` header, over
+  `https` for a domain name and over `http` for `localhost`, an IP address or
+  a single-label host. `fetchSSRData` ignores `x-forwarded-host`,
+  `x-forwarded-proto` and `forwarded`, and does not send them to the backend.
+  Behind a proxy that overwrites those headers, pass
+  `trustForwardedHeaders: true` to use them.
+* If your server answers requests for any `Host` header, such as a Node server
+  exposed directly or a proxy that forwards `Host` from its default virtual
+  host, pass `fetchSSRData` an absolute `backendURL`. A relative one resolves
+  against whatever `Host` the request sent.
+
+### Render the banner in the server HTML
+
+c15t has no framework-neutral helper for this. `ConsentProvider` accepts a
+server-resolved `prefetch` state, but the Next.js and TanStack Start adapters
+build that state from the request's cookie, headers and a cached policy
+manifest. Building it by hand ties your app to internal shapes. If the banner
+must be part of the first paint, use one of those adapters. Otherwise keep the
+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
+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
+page cache. [Data fetching](../../concepts/data-fetching.md) covers what is safe to
+cache.
+
+## Where the browser sends requests
+
+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()` 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
+custom transports.
+
+## Check the rendering path
+
+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`.
+3. The banner appears once the policy resolves. Vendor requests stay absent
+   until you allow their category.