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

package/docs/guides/banner-experiments.md

@@ -107,6 +107,20 @@ the arm names in `arm` and `split`. The callbacks forward each impression and
 choice to `window.dataLayer`; see
 [send the events to your own analytics](#send-the-events-to-your-own-analytics-too).
 
+Your flag provider returns a plain string. To check it before passing it as
+`arm`, type it with `ExperimentArmName` from `c15t`, which is `control` plus
+the experiment's arm names:
+
+```ts
+import type { ExperimentArmName } from 'c15t';
+
+// 'control' | 'wall'
+type BannerArm = ExperimentArmName<typeof bannerExperiment>;
+
+const armFromFlag = (value: string | undefined): BannerArm | undefined =>
+	value === 'control' || value === 'wall' ? value : undefined;
+```
+
 Omit `arm` to let c15t pick, and set `split` to weight the arms:
 
 ```ts
@@ -137,6 +151,14 @@ no effect; remount the provider (a `key` in React) to switch experiments.
 Assignment and arm validation load as a separate chunk, only on pages that
 set `experiment`. A site without an experiment does not download them.
 
+An experiment compares choices, so the banner has to ask about at least one
+category. Under a rule with `scopeMode: 'permissive'`, the banner asks only
+about the categories your site declares through `consentCategories`,
+`scripts` or `vendors`. With none declared, it asks about none: accepting or rejecting records a notice
+acknowledgement instead of a choice, `onChoiceRecorded` never fires, and the
+experiment counts impressions without choices. Outside production, c15t logs
+a warning the first time the banner shows an arm in that state.
+
 ### Astro
 
 The Astro banner is server-rendered HTML that the browser only shows or
@@ -229,8 +251,7 @@ keeps their arm when you change the weights.
 Resolve the flag where consent resolves and pass the experiment to
 `resolveConsent`. The server reports the arm with `/init`, and the returned
 state carries the experiment to `ConsentRoot`, so the client needs no
-`experiment` option of its own. The Next.js example does this in the root
-layout of its `/experiment` route:
+`experiment` option of its own. In Next.js, do this in the root layout:
 
 ```tsx title="app/layout.tsx"
 import { resolveConsent } from 'c15t/next/server';
@@ -268,8 +289,8 @@ const RootLayout = ({ children }: { children: ReactNode }) => (
 export default RootLayout;
 ```
 
-In the example, `lib/flags.ts` stands in for the flag above and reads the arm
-from the URL. `ExperimentConsent` is the `Consent` wrapper from the
+`@/lib/flags` exports the flag above. `ExperimentConsent` is the `Consent`
+wrapper from the
 [App Router guide](https://c15t.com/docs/frameworks/next/app-router) with the event callbacks
 from [send the events to your own analytics](#send-the-events-to-your-own-analytics-too)
 in `options`. The layout awaits consent inside `<Suspense>`, as in
@@ -622,7 +643,7 @@ arm by the visitors whose reports carry that arm.
 
 ## Try it
 
-Every example app under `examples/` runs this experiment outside the pages
+Every example app under `internals/fixtures/` runs this experiment outside the pages
 the docs publish. Each page shows the assigned arm and the events the
 callbacks sent. Adding `arm=wall` sets the arm the way a flag would, so the
 page shows `assignedBy: host`. Run each command in the example's directory.

package/docs/guides/troubleshooting.md

@@ -11,8 +11,9 @@ group: guides
 Most problems show up in one of these places. Run them before changing code.
 
 1. **Which c15t is running.** In the browser console, run `window.c15t`. v3
-   prints `{ version, pkg, mode }`, for example `mode: 'manifest'` from
-   `@c15t/nextjs`. `undefined` means no c15t provider has mounted on this
+   prints `{ version, pkg, mode, hosting }`, for example `mode: 'manifest'`
+   from `@c15t/nextjs`. `hosting` is `'inth'` or `'self-hosted'` once the
+   backend has answered `/init`, and `null` before then or without a backend. `undefined` means no c15t provider has mounted on this
    page. A `window.c15tStore` object means the page runs v2. With the script
    tag, `window.c15t` is the full browser API instead.
 2. **The backend request.** In DevTools Network, filter by your backend URL.

package/docs/integrations/overview.md

@@ -47,33 +47,34 @@ kernel to control its DOM lifecycle. Embeds do not require `@c15t/integrations`.
 
 ## Analytics
 
-| Integration                                               | Helper                   | Category                     | Loading behavior                                                             |
-| --------------------------------------------------------- | ------------------------ | ---------------------------- | ---------------------------------------------------------------------------- |
-| [Google Tag](./google-tag.md)                             | `gtag`                   | `measurement` or `marketing` | Always loads; signals Google consent                                         |
-| [Ahrefs Analytics](./ahrefs-analytics.md)                 | `ahrefsAnalytics`        | `measurement`                | Waits for effective permission                                               |
-| [Adobe Analytics](./adobe-analytics.md)                   | `adobeAnalytics`         | `measurement`                | Waits for effective permission                                               |
-| [Amplitude](./amplitude.md)                               | `amplitude`              | `measurement`                | Waits for effective permission; opts the SDK out on revocation               |
-| [Cloudflare Web Analytics](./cloudflare-web-analytics.md) | `cloudflareWebAnalytics` | `measurement`                | Waits for effective permission                                               |
-| [Clearbit](./clearbit.md)                                 | `clearbit`               | `marketing`                  | Waits for effective permission                                               |
-| [Microsoft Clarity](./microsoft-clarity.md)               | `clarity`                | `measurement`                | Gated initially; keeps the SDK and signals storage consent                   |
-| [Databuddy](./databuddy.md)                               | `databuddy`              | `measurement`                | Always loads; switches the SDK's disabled flag                               |
-| [Fathom Analytics](./fathom-analytics.md)                 | `fathomAnalytics`        | `measurement`                | Waits for effective permission                                               |
-| [Heap](./heap.md)                                         | `heap`                   | `measurement`                | Waits for effective permission                                               |
-| [Matomo Analytics](./matomo-analytics.md)                 | `matomoAnalytics`        | `measurement`                | Gated by default; optional consent mode                                      |
-| [Mixpanel](./mixpanel-analytics.md)                       | `mixpanelAnalytics`      | `measurement`                | Always loads; calls opt-in and opt-out APIs                                  |
-| [OneDollarStats](./one-dollar-stats.md)                   | `oneDollarStats`         | `measurement`                | Waits for effective permission                                               |
-| [Hotjar](./hotjar.md)                                     | `hotjar`                 | `measurement`                | Waits for effective permission                                               |
-| [Hightouch](./hightouch.md)                               | `hightouch`              | `measurement`                | Waits for effective permission                                               |
-| [LogRocket](./logrocket.md)                               | `logRocket`              | `measurement`                | Waits for effective permission                                               |
-| [Plausible Analytics](./plausible-analytics.md)           | `plausibleAnalytics`     | `measurement`                | Waits for effective permission                                               |
-| [PostHog](./posthog.md)                                   | `posthog`                | `measurement`                | Configurable; defaults to always loading and calling opt-in and opt-out APIs |
-| [Promptwatch](./promptwatch.md)                           | `promptwatch`            | `measurement`                | Waits for effective permission                                               |
-| [Pirsch](./pirsch.md)                                     | `pirsch`                 | `measurement`                | Waits for effective permission                                               |
-| [RudderStack](./rudderstack.md)                           | `rudderstack`            | `measurement`                | Gated by default; optional destination consent mode                          |
-| [Segment](./segment.md)                                   | `segment`                | `measurement`                | Waits for effective permission                                               |
-| [Rybbit Analytics](./rybbit-analytics.md)                 | `rybbitAnalytics`        | `measurement`                | Waits for effective permission                                               |
-| [Umami Analytics](./umami-analytics.md)                   | `umamiAnalytics`         | `measurement`                | Waits for effective permission                                               |
-| [Vercel Analytics](./vercel-analytics.md)                 | `vercelAnalytics`        | `measurement`                | Waits for effective permission                                               |
+| Integration                                               | Helper                   | Category                                        | Loading behavior                                                             |
+| --------------------------------------------------------- | ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Google Tag](./google-tag.md)                             | `gtag`                   | `measurement` or `marketing`                    | Always loads; signals Google consent                                         |
+| [Ahrefs Analytics](./ahrefs-analytics.md)                 | `ahrefsAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
+| [Adobe Analytics](./adobe-analytics.md)                   | `adobeAnalytics`         | `measurement`                                   | Waits for effective permission                                               |
+| [Amplitude](./amplitude.md)                               | `amplitude`              | `measurement`                                   | Waits for effective permission; opts the SDK out on revocation               |
+| [Cloudflare Web Analytics](./cloudflare-web-analytics.md) | `cloudflareWebAnalytics` | `measurement`                                   | Waits for effective permission                                               |
+| [Clearbit](./clearbit.md)                                 | `clearbit`               | `marketing`                                     | Waits for effective permission                                               |
+| [Microsoft Clarity](./microsoft-clarity.md)               | `clarity`                | `measurement`                                   | Gated initially; keeps the SDK and signals storage consent                   |
+| [Databuddy](./databuddy.md)                               | `databuddy`              | `measurement`                                   | Always loads; switches the SDK's disabled flag                               |
+| [Fathom Analytics](./fathom-analytics.md)                 | `fathomAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
+| [Heap](./heap.md)                                         | `heap`                   | `measurement`                                   | Waits for effective permission                                               |
+| [Matomo Analytics](./matomo-analytics.md)                 | `matomoAnalytics`        | `measurement`                                   | Gated by default; optional consent mode                                      |
+| [Mixpanel](./mixpanel-analytics.md)                       | `mixpanelAnalytics`      | `measurement`                                   | Always loads; calls opt-in and opt-out APIs                                  |
+| [OneDollarStats](./one-dollar-stats.md)                   | `oneDollarStats`         | `measurement`                                   | Waits for effective permission                                               |
+| [Hotjar](./hotjar.md)                                     | `hotjar`                 | `measurement`                                   | Waits for effective permission                                               |
+| [Hightouch](./hightouch.md)                               | `hightouch`              | `measurement`                                   | Waits for effective permission                                               |
+| [LogRocket](./logrocket.md)                               | `logRocket`              | `measurement`                                   | Waits for effective permission                                               |
+| [Plausible Analytics](./plausible-analytics.md)           | `plausibleAnalytics`     | `measurement`                                   | Waits for effective permission                                               |
+| [PostHog](./posthog.md)                                   | `posthog`                | `measurement`                                   | Configurable; defaults to always loading and calling opt-in and opt-out APIs |
+| [Promptwatch](./promptwatch.md)                           | `promptwatch`            | `measurement`                                   | Waits for effective permission                                               |
+| [Pirsch](./pirsch.md)                                     | `pirsch`                 | `measurement`                                   | Waits for effective permission                                               |
+| [RudderStack](./rudderstack.md)                           | `rudderstack`            | `measurement`                                   | Gated by default; optional destination consent mode                          |
+| [Segment](./segment.md)                                   | `segment`                | `measurement`                                   | Waits for effective permission                                               |
+| [Sentry](./sentry.md)                                     | `sentry`                 | `necessary`; Replay and user data `measurement` | Configurable; defaults to always loading and loads Replay after permission   |
+| [Rybbit Analytics](./rybbit-analytics.md)                 | `rybbitAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
+| [Umami Analytics](./umami-analytics.md)                   | `umamiAnalytics`         | `measurement`                                   | Waits for effective permission                                               |
+| [Vercel Analytics](./vercel-analytics.md)                 | `vercelAnalytics`        | `measurement`                                   | Waits for effective permission                                               |
 
 ## Chat and support
 

package/docs/integrations/posthog.md

@@ -1,8 +1,8 @@
 ---
 title: PostHog
 description: Load PostHog before or after measurement consent with the c15t
-  posthog helper, choose its cookieless behavior, and sync consent with an SDK
-  you already initialize.
+  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
 ---
@@ -257,15 +257,20 @@ A kernel you create yourself needs a loader from
 
 ## Options
 
-| Option        | Default                                                    | Behavior                                                                                                                                                        |
-| ------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`          | Required                                                   | Project token, starting with `phc_`. The helper trims it. Empty or whitespace-only values throw.                                                                |
-| `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.                                                                                                                        |
-| `initOptions` | `{ cookieless_mode: 'on_reject', defaults: '2026-01-30' }` | Options passed to `posthog.init`, merged over the defaults. The helper sets `api_host` and `ui_host` after your values, so change hosts with the options above. |
+| Option                  | Default                                                    | Behavior                                                                                                                                                                       |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                    | Required                                                   | Project token, starting with `phc_`. The helper trims it. Empty or whitespace-only values throw.                                                                               |
+| `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
 
@@ -283,6 +288,78 @@ project; see
 Set `cookieless_mode: 'never'`, as in the example, if a refusal must stop
 capture.
 
+## Turn off features you do not use
+
+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:
+
+```ts
+posthog({
+	id: 'phc_YOUR_PROJECT_TOKEN',
+	region: 'eu',
+	loadMode: 'after-consent',
+	features: {
+		surveys: false,
+		heatmaps: false,
+		deadClicks: false,
+		webVitals: false,
+		featureFlags: false,
+	},
+});
+```
+
+| 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
@@ -338,6 +415,11 @@ 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
@@ -355,6 +437,12 @@ 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: