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

package/docs/frameworks/react/quickstart.md

@@ -8,8 +8,9 @@ group: frameworks
 ## Before you start
 
 This guide sets up a client-rendered React app built with Vite. The browser
-loads the page, asks the consent backend for the visitor's policy, then shows
-the banner or runs the scripts the visitor allowed.
+loads the page, resolves the visitor's policy, then shows the banner or runs
+the scripts the visitor allowed. The build-time step bundles the public
+policy; regional policies may still need a backend location request.
 
 * **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
@@ -26,6 +27,10 @@ the backend URL.
 [Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
 covers self-hosting and offline mode.
 
+Build-time manifests are the recommended production setup. Complete the
+[build-time manifest step](#bundle-the-manifest-during-builds) before
+deploying, and rebuild after changing policies, translations or vendors.
+
 ## Install c15t
 
 | Package manager | Command                                           |
@@ -40,14 +45,12 @@ vendor loaders used below.
 
 ## Register your vendor scripts
 
-Create `src/scripts.ts`. PostHog waits for measurement permission and X Pixel
-waits for marketing permission, so your policy must include both categories.
-Remove any other PostHog or X Pixel loader from your app so each vendor loads
-once.
+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.
 
 ```ts title="src/scripts.ts"
 import { posthog } from '@c15t/integrations/posthog';
-import { xPixel } from '@c15t/integrations/x-pixel';
 
 export const scripts = [
 	posthog({
@@ -55,13 +58,11 @@ export const scripts = [
 		initOptions: { cookieless_mode: 'never' },
 		loadMode: 'after-consent',
 	}),
-	xPixel({ pixelId: 'your-pixel-id' }),
 ];
 ```
 
-Replace `phc_your_project_key` with your PostHog project key and
-`your-pixel-id` with your X Pixel ID. PostHog uses its EU host; add
-`region: 'us'` for a US project. Remove the loader for a vendor you don't use.
+Replace `phc_your_project_key` with your PostHog project key. PostHog uses its
+EU host; add `region: 'us'` for a US project.
 
 `loadMode: 'after-consent'` keeps the PostHog SDK off the page until the
 visitor allows measurement. `cookieless_mode: 'never'` turns off PostHog's
@@ -130,6 +131,66 @@ router, render the router inside `Consent` so navigation does not remount the
 provider. The stylesheet import in `src/consent.tsx` styles the banner and
 dialog; import it once.
 
+## Bundle the manifest during builds
+
+The build fetches your public policy once and bundles it, so the server never
+fetches it at runtime.
+
+Add `consentManifest` to your existing Vite plugin list:
+
+```ts title="vite.config.ts (plugins option)"
+import { consentManifest } from 'c15t/build';
+
+export default {
+	plugins: [
+		// Keep your existing framework plugins here.
+		consentManifest({ backendURL: 'https://your-project.inth.app' }),
+	],
+};
+```
+
+Vite writes `src/c15t-manifest.ts` before compiling, including at development
+startup. Keep the generated file out of Git. Install `@c15t/browser@alpha` for
+its browser manifest transport. In the quickstart's `src/consent.tsx`, replace
+the `hosted()` mode with this factory:
+
+```tsx title="src/consent.tsx"
+import { manifest } from '@c15t/browser/headless';
+
+import { consentManifest } from './c15t-manifest';
+
+const mode = manifest({
+	backendURL: 'https://your-project.inth.app',
+	manifest: consentManifest,
+});
+```
+
+Keep passing `mode` to `ConsentProvider`. The browser resolves the snapshot
+without `/manifest` when it has the geography the policy needs, or the policy
+does not depend on geography. Supply known country and region through `inputs`
+or overrides to keep regional resolution on the snapshot.
+
+When the required country or region is missing, the transport calls backend
+`/init` and uses its resolved policy and translations. That response can use
+newer backend policy than the build snapshot. This is a full consent resolution,
+so these visitors still wait for a backend round trip.
+
+Policy and resolver code are part of the browser bundle.
+
+The snapshot is fixed at build time:
+
+* Rebuild after changing policies, translations or vendors. If your CI caches
+  build output, force a fresh build.
+* The build must reach the backend. A failed fetch fails the build.
+* Consent choices still go to the backend.
+
+Run `vite build` or `vite dev` before a standalone `tsc`, `vue-tsc` or
+`svelte-check`; the generated file doesn't exist on a fresh checkout.
+
+For policy updates without a rebuild, keep the original `hosted()` factory
+and omit the build plugin. That setup resolves policy through the backend
+`/init` on each page load.
+
 ## Gate your own features
 
 Read a category's permission with `useConsent` inside the provider:
@@ -155,16 +216,16 @@ then open the site in a private window with DevTools open on the Network tab.
 Test under a policy that asks for a choice, such as an EU opt-in policy.
 
 1. **Before a choice.** The banner shows. There are no requests to
-   `posthog.com` or `static.ads-twitter.com`.
+   `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 and
-   X Pixel stays absent.
+   `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.
 
-If the banner never appears, check the Network tab for the request to
-`/init` on your backend URL. [Troubleshooting](./troubleshooting.md)
+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.
 

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: