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

package/docs/integrations/posthog.md

@@ -1,220 +1,164 @@
 ---
 title: PostHog
-description: Choose PostHog loading and cookieless behavior, configure the
-  region, and synchronize v3 permissions.
+description: Load PostHog before or after measurement consent with the c15t
+  posthog helper, choose its cookieless behavior, turn off PostHog modules you
+  do not use, and sync consent with an SDK you already initialize.
+icon: posthog
 group: integrations
 ---
 
 ## Configure PostHog
 
-Use the browser project token beginning with `phc_`. Select the region matching
-your PostHog project. This example waits for measurement permission before
-requesting the SDK.
+Use the project token that starts with `phc_`, and the region of your PostHog
+project. This example waits for measurement permission before requesting the
+SDK, and turns off cookieless capture after a refusal.
 
-| Package manager | Command                     |
-| :-------------- | :-------------------------- |
-| npm             | `npm install @c15t/scripts` |
-| pnpm            | `pnpm add @c15t/scripts`    |
-| yarn            | `yarn add @c15t/scripts`    |
-| bun             | `bun add @c15t/scripts`     |
+| Package manager | Command                                |
+| :-------------- | :------------------------------------- |
+| npm             | `npm install @c15t/integrations@alpha` |
+| pnpm            | `pnpm add @c15t/integrations@alpha`    |
+| yarn            | `yarn add @c15t/integrations@alpha`    |
+| bun             | `bun add @c15t/integrations@alpha`     |
 
 ```ts title="src/consent-scripts.ts"
-import { posthog } from '@c15t/scripts/posthog';
+import { posthog } from '@c15t/integrations/posthog';
 
 export const scripts = [
-  posthog({
-    id: 'phc_YOUR_PROJECT_TOKEN',
-    region: 'eu',
-    loadMode: 'after-consent',
-    initOptions: { cookieless_mode: 'never' },
-  }),
+	posthog({
+		id: 'phc_YOUR_PROJECT_TOKEN',
+		region: 'eu',
+		loadMode: 'after-consent',
+		initOptions: { cookieless_mode: 'never' },
+	}),
 ];
 ```
 
-The helper initializes PostHog. Remove a separate `posthog-js` initializer,
-framework plugin or array snippet before using this setup.
+The helper initializes PostHog itself. Remove any `posthog-js` initializer,
+framework plugin or array snippet that also does, or follow
+[use an existing PostHog SDK](#use-an-existing-posthog-sdk) instead.
 
 ## Register the scripts
 
-Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+Complete your [framework quickstart](https://v3.c15t.com/docs/frameworks) first. Keep its Inth
 endpoint, policy, styles and consent UI. Remove the vendor's original script,
-SDK initializer or tag-manager entry so c15t owns loading once.
+SDK initializer or tag-manager entry, so the vendor loads only through c15t.
 
-The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
-initializer. Add it to your existing consent owner using the registration point
-below. These are partial edits to that owner, not additional providers.
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
+in the Next.js guide, add the helper to that array instead of creating a
+second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
 
 **Next.js**
 
-Import the configuration into the client boundary from your router guide:
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
 
-```ts
-import { ConsentRoot } from 'c15t/next';
-import { scripts } from './consent-scripts';
-```
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
 
-Keep the server-resolved `state` and shared `consentConfig` from your
-router guide. Its manifest, init and save URLs stay in effect. Add
-`scripts` as a top-level prop on the existing root:
-
-```tsx
-<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
-  {children}
-</ConsentRoot>
+export default defineConsentConfig({ scripts });
 ```
 
-For a Pages Router or static-export setup using `ConsentProvider`, add
-`scripts` to its existing `options` instead. Keep the router-specific setup
-from [Next.js script loading](https://c15t.com/docs/frameworks/next/script-loader).
+Keep the rest of your config, such as `mode` and `routePrefix`, in the
+same call. `ConsentRoot` reads the config in the browser, so the layout
+keeps passing only `state`. App Router, Pages Router and static export all
+read the same file. See
+[Next.js scripts and embeds](https://v3.c15t.com/docs/frameworks/next/scripts).
 
 **TanStack Start**
 
-In your existing root route component, import the scripts alongside
-`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader from the
+[TanStack Start quickstart](https://v3.c15t.com/docs/frameworks/tanstack-start/quickstart):
 
-```tsx
-import { Outlet } from '@tanstack/react-router';
-import { ConsentRoot } from 'c15t/tanstack-start';
+```tsx title="src/routes/__root.tsx"
 import { scripts } from '../consent-scripts';
 
-function Root() {
-  const state = Route.useLoaderData();
-  return (
-    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
-      <Outlet />
-      {/* Keep your consent banner, dialog and preferences link here. */}
-    </ConsentRoot>
-  );
-}
+<ConsentRoot state={consent} scripts={scripts}>
 ```
 
-This edits the existing route. `Route` and `backendURL` come from its setup;
-keep the document shell and head components if they are part of your root.
-`initRoute={false}` keeps the quickstart's direct-backend initialization.
-If your app mounts a consent server route, retain its existing `initRoute`
-instead. Do not return script callbacks from a server function or route loader.
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](https://v3.c15t.com/docs/frameworks/tanstack-start/scripts).
 
 **React**
 
-Import the scripts into your existing provider component:
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
 
-```ts
-import { ConsentProvider } from 'c15t/react';
+```tsx title="src/consent.tsx"
 import { scripts } from './consent-scripts';
-```
 
-Keep the existing options and add `scripts`:
-
-```tsx
-<ConsentProvider options={{ ...consentOptions, scripts }}>
-  {children}
-</ConsentProvider>
+<ConsentProvider options={{ mode, scripts }}>
 ```
 
-Here `consentOptions` is your existing configuration, including
-`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
-link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
+`mode` is the `manifest()` value from the
+[React quickstart](../frameworks/react/quickstart.md). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
 
 **Nuxt**
 
-Attach one loader from the root `app.vue`, after the Nuxt module has
-started its browser runtime. This keeps vendor callbacks in application code rather
-than serialized `nuxt.config.ts` runtime configuration.
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
 
-```vue title="app/app.vue"
-<script setup lang="ts">
-import { onUnmounted } from 'vue';
-import { createScriptLoader } from 'c15t/modules/script-loader';
+```ts title="app/app.config.ts"
 import { scripts } from '../src/consent-scripts';
 
-const nuxtApp = useNuxtApp();
-const kernel = useConsentKernel();
-let loader: ReturnType<typeof createScriptLoader> | undefined;
-
-const removeMountedHook = nuxtApp.hook('app:mounted', () => {
-  loader = createScriptLoader({ kernel, scripts });
-});
-onUnmounted(() => {
-  removeMountedHook();
-  loader?.dispose();
+export default defineAppConfig({
+  c15t: { scripts },
 });
-</script>
-
-<template>
-  <ConsentRoot />
-  <NuxtPage />
-</template>
 ```
 
-Merge the setup code into your root and retain its footer and preferences
-link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
-relative script import if your `app.vue` is at the project root. This loader
-waits until the module has applied browser persistence and privacy signals,
-then reads the current snapshot and observes future changes. Do not also register these scripts
-in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](https://v3.c15t.com/docs/frameworks/nuxt/scripts).
 
 **Vue**
 
-Use the kernel already provided by the Vue plugin. Merge this setup into
-`App.vue`, whose lifetime covers the application:
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
 
-```vue title="src/App.vue"
-<script setup lang="ts">
-import { onMounted, onUnmounted } from 'vue';
-import { createScriptLoader } from 'c15t/modules/script-loader';
-import { useConsentKernel } from 'c15t/vue/vue-plugin';
-import ConsentRoot from 'c15t/vue/consent-root';
+```ts title="src/main.ts"
+import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
 import { scripts } from './consent-scripts';
 
-const kernel = useConsentKernel();
-let loader: ReturnType<typeof createScriptLoader> | undefined;
-
-onMounted(() => {
-  loader = createScriptLoader({ kernel, scripts });
+app.use(c15tVue, {
+  mode: manifest(),
+  scripts,
 });
-onUnmounted(() => loader?.dispose());
-</script>
-
-<template>
-  <ConsentRoot />
-  <main>Your application</main>
-</template>
 ```
 
-Keep your existing page content and preferences link. The plugin still owns
-the kernel and persistence; this component owns only the vendor loader.
-Do not register the same scripts in plugin configuration as well. See the
-[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
+Keep your existing `mode` and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](https://v3.c15t.com/docs/frameworks/vue/scripts).
 
 **Astro**
 
-Point the existing Astro integration at a client module. Keep its `mode`,
-`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
-Import `fileURLToPath` in your Astro configuration:
-
-```js title="astro.config.mjs"
-import { fileURLToPath } from 'node:url';
-```
-
-Add this option to the existing `c15t({ ... })` call. Resolve the path from
-the configuration file because Astro injects the import into a virtual module:
-
-```js
-clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
-```
-
-Export the scripts from that module:
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://v3.c15t.com/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
+which the integration finds on its own. Keep `astro.config.mjs` as it is.
+If the module already exports scripts, combine the two arrays.
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-The integration passes this extension to its shared browser runtime. Vendor
-helpers contain callbacks, so do not put them in the serialized `scripts`
-option in `astro.config.mjs`. Keep one runtime across consent islands and
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
 `ClientRouter` navigation.
 
 **Svelte**
@@ -224,174 +168,289 @@ pass them as a top-level prop:
 
 ```svelte title="src/App.svelte"
 <script lang="ts">
-  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { ConsentProvider, manifest } from '@c15t/svelte';
   import { scripts } from './consent-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 });
 </script>
 
-<ConsentManagerProvider {mode} {scripts}>
+<ConsentProvider mode={manifest()} {scripts}>
   <!-- Keep your application, consent UI and preferences link here. -->
-</ConsentManagerProvider>
+</ConsentProvider>
 ```
 
-Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+Retain the styles and consent UI from the [Svelte quickstart](https://v3.c15t.com/docs/frameworks/svelte/quickstart).
 The provider owns the loader and disposes it on unmount.
 
 **SvelteKit**
 
-Add the scripts to the existing root layout provider. Keep the server load
-and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
+handle and the layout load from the [SvelteKit quickstart](https://v3.c15t.com/docs/frameworks/sveltekit/quickstart).
 
 ```svelte title="src/routes/+layout.svelte"
 <script lang="ts">
-  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { ConsentRoot } from '@c15t/svelte';
   import { scripts } from '../consent-scripts';
 
   let { children, data } = $props();
-  const mode = hosted({ url: data.backendURL });
 </script>
 
-<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+<ConsentRoot state={data.consent} {scripts}>
   {@render children()}
   <!-- Keep your consent UI and preferences link here. -->
-</ConsentManagerProvider>
+</ConsentRoot>
 ```
 
-Import vendor helpers in the layout component, not in `+layout.server.ts`.
-For static hosting, keep your browser-only `mode` setup and omit request
-prefetch; the `scripts` prop stays the same. If you pass an externally owned
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
 `runtime` to the provider, register scripts when creating that runtime instead.
 
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](https://v3.c15t.com/docs/frameworks/html/scripts).
+
 **JavaScript**
 
-Attach the loader to your existing kernel before calling
-`kernel.commands.init()`:
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
 
 ```ts
-import { createScriptLoader } from 'c15t/modules/script-loader';
+import { init, manifest } from '@c15t/browser';
 import { scripts } from './consent-scripts';
 
-const loader = createScriptLoader({ kernel, scripts });
+const consent = init({
+  mode: manifest(),
+  scripts,
+});
 ```
 
-Call `loader.dispose()` when that application instance is destroyed.
-`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
-already has a loader; do not attach a second one. See
-[JavaScript script loading](https://c15t.com/docs/frameworks/javascript/script-loader).
+Keep the mode from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](https://v3.c15t.com/docs/frameworks/javascript/scripts).
+
+## Options
+
+| Option                  | Default                                                    | Behavior                                                                                                                                                                       |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                    | Required                                                   | Project token, starting with `phc_`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.                                           |
+| `region`                | `'eu'`                                                     | `'eu'` or `'us'`. Picks the API, UI and loader hosts when you do not set them.                                                                                                 |
+| `apiHost`               | `https://eu.i.posthog.com`                                 | API host for a proxy or self-hosted PostHog. Without `scriptUrl`, the loader URL becomes `<apiHost>/static/array.js`.                                                          |
+| `uiHost`                | The region's UI host                                       | UI host, for example `https://eu.posthog.com`. A custom `apiHost` with no `region` uses the API host.                                                                          |
+| `scriptUrl`             | `https://eu-assets.i.posthog.com/static/array.js`          | Loader URL override. A blank value falls back to the default.                                                                                                                  |
+| `loadMode`              | `'always'`                                                 | When the SDK loads. See the table below.                                                                                                                                       |
+| `features.surveys`      | Unset                                                      | `false` sets `disable_surveys: true` and skips `surveys.js`. See [turn off features you do not use](#turn-off-features-you-do-not-use).                                        |
+| `features.heatmaps`     | Unset, follows the project                                 | Sets `capture_heatmaps`.                                                                                                                                                       |
+| `features.deadClicks`   | Unset, follows the project                                 | Sets `capture_dead_clicks`.                                                                                                                                                    |
+| `features.webVitals`    | Unset, follows the project                                 | Sets `capture_performance: { web_vitals }`. Replay network timing keeps following the project.                                                                                 |
+| `features.featureFlags` | Unset, follows the project                                 | `false` sets `advanced_disable_feature_flags: true` and stops `/flags` requests.                                                                                               |
+| `initOptions`           | `{ cookieless_mode: 'on_reject', defaults: '2026-01-30' }` | Options passed to `posthog.init`, merged over the defaults and `features`. The helper sets `api_host` and `ui_host` after your values, so change hosts with the options above. |
+
+## Loading and revocation
+
+| `loadMode`        | When PostHog loads                | Consent sync                                                                |
+| ----------------- | --------------------------------- | --------------------------------------------------------------------------- |
+| `'always'`        | On every page, before consent     | Calls `opt_in_capturing` or `opt_out_capturing` at load and on every change |
+| `'after-consent'` | Only while measurement is allowed | Calls `opt_in_capturing` at load and `opt_out_capturing` on revocation      |
+| `'disabled'`      | Never                             | None. The helper returns an empty callback-only script                      |
+
+`posthog` uses the `measurement` category. With the default
+`cookieless_mode: 'on_reject'`, PostHog keeps capturing without cookies after a
+refusal. That mode needs cookieless server hashing turned on in your PostHog
+project; see
+[PostHog's cookieless guide](https://posthog.com/tutorials/cookieless-tracking).
+Set `cookieless_mode: 'never'`, as in the example, if a refusal must stop
+capture.
 
-## Choose loading and capture behavior separately
+## Turn off features you do not use
 
-| `loadMode`                     | SDK loading                           | Consent handling                                                |
-| ------------------------------ | ------------------------------------- | --------------------------------------------------------------- |
-| `'after-consent'`              | Waits for measurement permission      | Calls PostHog opt-in and opt-out APIs after load and on changes |
-| `'always'`, the helper default | Loads even while permission is denied | Calls the same consent APIs                                     |
-| `'disabled'`                   | Does not load PostHog                 | Does not synchronize consent with an SDK loaded elsewhere       |
+After `array.js` loads, PostHog reads your `posthog.init` options and the
+project's remote config, then decides which extra modules to download and
+whether to request `/flags`. Set a `features` switch to `false` for each
+feature your site does not use:
 
-The helper defaults `initOptions.cookieless_mode` to `'on_reject'`. In that
-mode, PostHog can continue cookieless capture after denial. It requires the
-project's cookieless server hash setting. See
-[PostHog's cookieless guide](https://posthog.com/tutorials/cookieless-tracking).
+```ts
+posthog({
+	id: 'phc_YOUR_PROJECT_TOKEN',
+	region: 'eu',
+	loadMode: 'after-consent',
+	features: {
+		surveys: false,
+		heatmaps: false,
+		deadClicks: false,
+		webVitals: false,
+		featureFlags: false,
+	},
+});
+```
 
-The example overrides this with `'never'` so opting out is not a switch to
-cookieless capture. Loading after consent only controls the initial request;
-for later revocation, verify PostHog's opt-out behavior and stop application
-capture calls too. SDK code that already executed cannot be undone by removing
-its script element.
-
-## Configure hosts and initialization
-
-| Option                         | Behavior                                                                                 |
-| ------------------------------ | ---------------------------------------------------------------------------------------- |
-| `id`                           | Browser project token.                                                                   |
-| `region`                       | `'eu'` by default; use `'us'` for a US project.                                          |
-| `apiHost / uiHost / scriptUrl` | Explicit overrides for proxy or self-hosted PostHog deployments. Keep all hosts aligned. |
-| `loadMode`                     | Defaults to `'always'`; choose deliberately.                                             |
-| `initOptions`                  | Additional serializable SDK options, including the cookieless override.                  |
-
-The helper applies the resolved API and UI hosts after `initOptions`; use the
-top-level host fields to change them. A global `posthog` queue may exist before
-the SDK is ready. Neither API presence nor SDK readiness is a consent grant.
-
-## Keep application events behind permission
-
-With the script helper registered, a React client component can guard an event
-using the current effective permission:
-
-```tsx title="src/signup-event.tsx"
-'use client';
-
-import { useConsent } from 'c15t/react';
-
-export function SignupEvent() {
-  const allowed = useConsent('measurement');
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (allowed) window.posthog?.capture('signup_started');
-      }}
-    >
-      Start signup
-    </button>
-  );
+| Switch         | `false` sets                                 | What PostHog skips                                                          |
+| -------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
+| `surveys`      | `disable_surveys: true`                      | `surveys.js`, about 29 KB                                                   |
+| `heatmaps`     | `capture_heatmaps: false`                    | Heatmap capture. With `deadClicks: false` too, `dead-clicks-autocapture.js` |
+| `deadClicks`   | `capture_dead_clicks: false`                 | `dead-clicks-autocapture.js`, about 8 KB, once heatmaps are off too         |
+| `webVitals`    | `capture_performance: { web_vitals: false }` | `web-vitals-with-attribution.js`, about 6 KB                                |
+| `featureFlags` | `advanced_disable_feature_flags: true`       | `/flags` requests. The remote config still loads                            |
+
+Sizes are brotli-compressed, measured from posthog-js 1.436.1.
+
+An unset switch adds nothing to `posthog.init`. For heatmaps, dead clicks, web
+vitals and feature flags, PostHog then follows the setting in your PostHog
+project. `true` sets the opposite value and overrides the project. For
+`surveys` and `featureFlags`, `true` is PostHog's own default, so it behaves
+the same as unset.
+
+Surveys work differently. PostHog downloads `surveys.js` whenever the remote
+config includes a `surveys` value, even when surveys are off in the project.
+`surveys: false` is the only way to skip it.
+
+`initOptions` wins over a switch that sets the same key. A
+`capture_performance` value in `initOptions` replaces the whole object that
+`webVitals` builds.
+
+### Avoid PostHog's option traps
+
+These rules also apply when you pass PostHog options yourself, in
+`initOptions` or in your own `posthog.init`:
+
+* Use `advanced_disable_feature_flags: true` to stop `/flags`, not
+  `advanced_disable_flags: true`. The second also stops PostHog loading the
+  remote config, so session replay never starts and other features fall back to
+  local config.
+* With feature flags off, surveys that target a feature flag never show.
+  PostHog logs a warning about it. If you need those surveys, leave
+  `featureFlags` unset and pass
+  `advanced_only_evaluate_survey_feature_flags: true` instead. PostHog still
+  requests `/flags`, but evaluates only survey flags.
+* While heatmaps are on, in `posthog.init` or in the project, PostHog loads
+  `dead-clicks-autocapture.js` whatever `capture_dead_clicks` says. Turn off
+  both to skip it.
+* `capture_performance: false` turns off web vitals and session replay network
+  timing. `{ web_vitals: false }`, which `webVitals: false` sets, leaves network
+  timing to the project. `capture_performance: true` forces both on.
+
+Product tours (`product-tours.js`, about 36 KB) and exception autocapture
+(`exception-autocapture.js`, about 6 KB) load only when the project turns them
+on. To keep them off whatever the project says, pass
+`disable_product_tours: true` or `capture_exceptions: false` in `initOptions`.
+
+## Guard your own capture calls
+
+Events your code sends need their own permission check. The `posthog` global
+exists before the SDK loads, so its presence does not mean measurement is
+allowed:
+
+```ts title="src/track-signup.ts"
+export function trackSignupStarted(measurementAllowed: boolean) {
+	if (!measurementAllowed) return;
+	window.posthog?.capture('signup_started');
 }
 ```
 
-This is an event-call example, not a signup implementation. Next.js client
-components can import `useConsent` from `c15t/next`.
+Pass the current measurement permission from your framework, for example
+`useConsent('measurement')` in React.
 
 ## Use an existing PostHog SDK
 
-If your app already initializes `posthog-js`, keep that SDK owner and attach a
-callback-only script instead of the loading helper. Initialize your SDK with
-`opt_out_capturing_by_default: true` and `cookieless_mode: 'never'` before
-mounting c15t when denied permission must stop capture.
+If your app already initializes `posthog-js`, keep that setup and register a
+callback-only script instead of the helper. Initialize the SDK with
+`opt_out_capturing_by_default: true` and `cookieless_mode: 'never'` so it
+captures nothing before c15t reports a permission.
 
 ```ts title="src/posthog-consent.ts"
 import type { Script, ScriptCallbackInfo } from 'c15t/modules/script-loader';
 
 type PostHogConsentApi = {
-  opt_in_capturing: () => unknown;
-  opt_out_capturing: () => unknown;
+	opt_in_capturing: () => unknown;
+	opt_out_capturing: () => unknown;
 };
 
 export function posthogConsent(instance: PostHogConsentApi): Script {
-  const sync = ({ hasConsent }: ScriptCallbackInfo) => {
-    if (hasConsent) instance.opt_in_capturing();
-    else instance.opt_out_capturing();
-  };
-
-  return {
-    id: 'posthog-sdk-consent',
-    category: 'measurement',
-    callbackOnly: true,
-    alwaysLoad: true,
-    onBeforeLoad: sync,
-    onConsentChange: sync,
-  };
+	const sync = ({ hasConsent }: ScriptCallbackInfo) => {
+		if (hasConsent) instance.opt_in_capturing();
+		else instance.opt_out_capturing();
+	};
+
+	return {
+		id: 'posthog-sdk-consent',
+		category: 'measurement',
+		callbackOnly: true,
+		alwaysLoad: true,
+		onBeforeLoad: sync,
+		onConsentChange: sync,
+	};
 }
 ```
 
-Pass `posthogConsent(posthog)` in the existing provider's `scripts` array, using
-your initialized SDK instance. The callback-only entry synchronizes initial
-and changed effective permissions without loading a second SDK. It does not
-block the SDK import or its initial request. `loadMode: 'disabled'` on the
-loading helper is not a substitute, because it performs no synchronization.
-
-Keep c15t as the source of truth for the banner and saved choices. Effective
-permission can come from policy defaults; a synchronization callback is not
-proof that the visitor explicitly accepted. Do not reuse v2
-`getOrCreateConsentRuntime` or `onBannerFetched` examples with v3.
-
-## Verify the integration
-
-With the example above, a fresh opt-in session should make no PostHog SDK
-request until measurement is allowed. Grant, capture one test event, revoke,
-and confirm later application calls stop. Repeat with persisted consent and
-client navigation. If you choose cookieless capture, verify that behavior
-explicitly in the project rather than expecting silence after denial. See
-[consent verification](../guides/verify-consent.md).
+Add `posthogConsent(posthog)` to the `scripts` you register, passing your
+initialized SDK instance. `callbackOnly` means c15t inserts no script element.
+`alwaysLoad` makes `onBeforeLoad` run on the first page load even while
+measurement is denied, so the SDK is told to opt out. `onConsentChange` runs on
+every later change. This does not delay the SDK import or its first request.
+`loadMode: 'disabled'` is not a substitute, because it syncs nothing.
+
+`features` belongs to the helper, so it does nothing here. To skip modules you
+do not use, pass the PostHog options from
+[turn off features you do not use](#turn-off-features-you-do-not-use) to your
+own `posthog.init`, for example `disable_surveys: true`.
+
+## Measure opt-in rate
+
+If you run a banner experiment, the backend already counts visitors and
+choices per arm. To see the arm in PostHog as well, forward the `onSurfaceShown` and
+`onChoiceRecorded` callbacks, which carry `experiment: { id, arm }`. See
+[banner experiments](../guides/banner-experiments.md#send-the-events-to-your-own-analytics-too).
+
+## Verify PostHog
+
+These checks assume `loadMode: 'after-consent'` from the example. After you
+allow measurement, `array.js` loads and capture requests to your API host
+follow. Trigger one guarded event and check that it is sent.
+
+With `loadMode: 'always'`, `array.js` loads before a choice instead. Check that
+no capture request is sent while measurement is denied, unless you chose
+cookieless capture.
+
+If you turned features off, allow measurement and filter the DevTools Network
+panel by `posthog`. Reload the page. You should see `array.js`, the remote
+config and capture requests, but no `/flags` request with `featureFlags: false`
+and none of the modules you turned off, such as `surveys.js` or
+`dead-clicks-autocapture.js`.
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper sets `vendor` to its script ID, so once you declare that vendor a
+visitor can turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.