@c15t/react 3.0.0-alpha.5 → 3.0.0-alpha.7

package/docs/frameworks/react/rendering.md

@@ -23,14 +23,79 @@ 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 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.
+
 ## Client-rendered apps
 
-The [quickstart](./quickstart.md) setup runs entirely in the
-browser:
+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, keep `hosted({ url })`. 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. The backend
-   picks the visitor's policy from their location.
+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.
 
@@ -47,8 +112,11 @@ 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 requests `/init`, then shows the banner if the
-  policy asks for one.
+* 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`.
 * The server render and the first browser render agree, so hydration does not
   warn or change a stored choice.
 
@@ -96,8 +164,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 setup unchanged. The browser talks to the
-backend URL directly, so the static host needs no server route. Add the site's
+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
@@ -122,7 +191,9 @@ 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, filter by your backend URL. One `/init` request runs
-   after the JavaScript loads, or none if you pass `initialData`.
-3. The banner appears once that request finishes. Vendor requests stay absent
+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.

package/docs/frameworks/react/scripts.md

@@ -11,11 +11,10 @@ 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 and X Pixel this way:
+registers PostHog this way:
 
 ```ts title="src/scripts.ts"
 import { posthog } from '@c15t/integrations/posthog';
-import { xPixel } from '@c15t/integrations/x-pixel';
 
 export const scripts = [
 	posthog({
@@ -23,7 +22,6 @@ export const scripts = [
 		initOptions: { cookieless_mode: 'never' },
 		loadMode: 'after-consent',
 	}),
-	xPixel({ pixelId: 'your-pixel-id' }),
 ];
 ```
 
@@ -76,6 +74,13 @@ covers a vendor without one.
   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
+
+The script loader is a separate chunk, downloaded only when `scripts` is not
+empty. `ConsentProvider` loads it when it mounts. The Next.js and TanStack
+Start `ConsentRoot` start the download earlier, during their first render,
+when the visitor's consent already lets a script run.
+
 ## Embeds and other requests
 
 Scripts cover vendor code c15t loads for you. For the rest: