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

package/dist-types/index.d.ts

@@ -32,31 +32,30 @@
  *   module wiring around a single per-mount kernel.
  */
 export type { ConsentKernel, ConsentSnapshot, ConsentState, HostedTransportOptions, InitContext, InitResponse, InitResult, KernelConfig, KernelEvent, KernelOverrides, KernelTransport, KernelUser, Listener, HostedModeOptions, ProviderTransportContext, ProviderTransportFactory, ProviderTransportKind, SavePayload, SaveResult, Unsubscribe, } from '@c15t/core';
-export { createConsentKernel, custom, hosted } from '@c15t/core';
 export type { OfflineModeOptions } from './transports/offline.js';
-export { offline } from './transports/offline.js';
-export { ConsentDialog, ConsentWidget } from './aggregate-components.js';
 export type { ConsentBannerButton, ConsentBannerLayout, ConsentBannerProps, ConsentBannerRight, ConsentBannerRightLinkProps, ConsentBannerRightsProps, ConsentBannerSurface, } from './components/prompt/index.js';
-export { ConsentBanner, type ConsentBannerCompoundComponent, useConsentBannerSurface, } from './components/prompt/index.js';
 export type { ConsentDialogCompoundComponent, ConsentDialogProps, } from './components/panel/index.js';
 export type { ConsentDialogLinkProps } from './components/panel-link/index.js';
-export { ConsentDialogLink } from './components/panel-link/index.js';
 export type { ConsentDialogTriggerProps, ConsentDialogTriggerToolbarAction, ConsentDialogTriggerToolbarPreferences, ConsentDialogTriggerToolbarProps, TriggerOrientation, } from './components/panel-trigger/index.js';
-export { ConsentDialogTrigger, ConsentDialogTriggerToolbar, } from './components/panel-trigger/index.js';
 export type { ConsentWidgetCompoundComponent, ConsentWidgetProps, } from './components/preferences/index.js';
 export type { ConsentGateProps, FrameProps } from './components/consent-gate/index.js';
-export { ConsentGate, Frame } from './components/consent-gate/index.js';
 export type { ConsentDraftHandle, ConsentDraftProviderProps, VendorDraftHandle, } from './draft.js';
-export { ConsentDraftProvider, useConsentDraft, useVendorDraft } from './draft.js';
-export { useTranslations } from './component-hooks/use-translations.js';
-export { useActiveUI, useBranding, useConsent, useConsents, useExperiment, useHasConsentPolicy, useHasConsentPreferences, useHasConsentUI, useIABEnabled, useIABSnapshot, useIdentify, useInit, useLocation, useModel, useOverrides, usePromptPresentation, usePolicyCategories, usePreferencesPresentation, useResolvedPresentation, useResolvedTheme, usePolicyScopeMode, usePurposeConsent, useRegisterConsentCategories, useSaveConsents, useSetActiveUI, useSetLanguage, useSetOverrides, useSnapshot, useSpecialFeatureOptIn, useSubscribeToConsentChanges, useTCString, useUser, useDeclaredVendors, useVendorAllowed, useVendorChoice, useVendorConsent, } from './hooks.js';
 export type { UseIframeBlockerOptions, UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions, } from './module-hooks.js';
-export { useIframeBlocker, useNetworkBlocker, usePersistence, useScriptLoader, } from './module-hooks.js';
 export type { ConsentProviderOptions, ConsentProviderCallbacks, ConsentProviderPrefetch, ConsentProviderProps, ExternalRuntimeProviderOptions, ExternalRuntimeProviderProps, OwnedRuntimeProviderProps, } from './provider.js';
-export { ConsentProvider } from './provider.js';
-export { ConsentTheme } from './consent-theme.js';
 export type { ConsentThemeProps } from './consent-theme.js';
+export type { Theme } from './types/theme/index.js';
+export type { ConsentBannerCompoundComponent } from './components/prompt/index.js';
 export type { ReactUIOptions } from './types/manager.js';
-export { defineTheme, type Theme } from './types/theme/index.js';
-export { useExplicitChoice, useEffectivePermissions, usePromptRequirement, useNoticeDismissal, usePrivacySignals, usePolicyResolution, usePolicyRule, useRestrictions, useDismissNotice, } from './hooks.js';
 export type { ConsentPresentation, PromptPresentation, PreferencesPresentation, PresentationAction, PromptPosition, PromptVariant, ResolvedConsentPresentation, } from '@c15t/core';
+export * from './index-parts/core.js';
+export * from './index-parts/consent-dialog.js';
+export * from './index-parts/consent-banner.js';
+export * from './index-parts/consent-dialog-link.js';
+export * from './index-parts/consent-dialog-trigger.js';
+export * from './index-parts/consent-gate.js';
+export * from './index-parts/draft.js';
+export * from './index-parts/translations.js';
+export * from './index-parts/module-hooks.js';
+export * from './index-parts/provider.js';
+export * from './index-parts/theme.js';
+export * from './index-parts/hooks.js';

package/dist-types/kernel-selector.d.ts

@@ -56,11 +56,3 @@ export declare const useCategoryAllowed: (category: AllConsentNames) => boolean;
  * @internal
  */
 export declare const useTranslationLanguage: () => string;
-/**
- * Categories the preference surface lists: `necessary` plus the recorded
- * choice scope, or the policy scope when no choice scope applies.
- *
- * @returns A list whose identity changes only when the scope does.
- * @internal
- */
-export declare const useDisplayedCategories: () => readonly AllConsentNames[];

package/dist-types/module-hooks/iframe-blocker.d.ts

@@ -1,5 +1,5 @@
 import type { ConsentKernel } from '@c15t/core';
-import type { IframeBlockerHandle } from '@c15t/core/modules/iframe-blocker';
+import type { IframeBlockerHandle, IframeBlockerOptions } from '@c15t/core/modules/iframe-blocker';
 export interface UseIframeBlockerOptions {
     disableAutomaticBlocking?: boolean;
 }
@@ -21,13 +21,18 @@ export declare const useIframeBlocker: (options?: UseIframeBlockerOptions) => If
  */
 export declare const watchGatedIframes: (kernel: ConsentKernel, onFound: () => void) => () => void;
 /**
- * The provider's default iframe blocker. Loads the blocker module when the
- * first gated iframe (`data-category` or `data-vendor`) is on the page
- * instead of on every mount, so pages without one never download it.
+ * The provider's iframe blocker. Loads the blocker module when the first
+ * gated iframe (`data-category` or `data-vendor`) is on the page instead of
+ * on every mount, so pages without one never download it. Until then it
+ * pauses gated frames that arrive with a `src` consent does not allow.
  *
- * @param options - Blocker options. With `disableAutomaticBlocking` the
- * module loads at once, as it did before.
+ * Passed to the provider runtime as its `createIframeBlocker` module.
+ *
+ * @param options - The kernel and blocker options. With
+ * `disableAutomaticBlocking` the module loads at once.
+ * @returns A handle; `processAllIframes()` reaches the blocker once it has
+ * loaded.
  * @internal
  */
-export declare const useIframeBlockerOnDemand: (options?: UseIframeBlockerOptions) => void;
+export declare const createIframeBlockerOnDemand: ({ disableAutomaticBlocking, kernel, }: IframeBlockerOptions) => IframeBlockerHandle;
 export type { IframeBlockerHandle };

package/dist-types/provider.d.ts

@@ -1,6 +1,7 @@
-import type { AllConsentNames, ClearOnRevocationConfig, ConsentExperiment, ExperimentState, ConsentPresentation, Callbacks, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
+import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentPresentation, ExperimentState, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
 import type { Script } from '@c15t/core/modules/script-loader';
-import type { ConsentControlOptions, ConsentRuntime } from '@c15t/core/runtime';
+import type { ConsentControlOptions } from '@c15t/core/runtime';
+import type { ConsentRuntime, ResolveStreamedInit } from '@c15t/core/runtime/provider';
 import type { ReactNode } from 'react';
 import type { DialogPreload } from './chunk-warming.js';
 import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from './module-hooks.js';
@@ -56,6 +57,12 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * ```
      */
     mode: ProviderTransportFactory;
+    /**
+     * Where the visitor's choice is stored. Read once, like `persistence`:
+     * the stored records and the data clearing that protects them stay at
+     * the location the provider mounted with. Outside production, a change
+     * logs a warning; remount the provider to move storage.
+     */
     storageConfig?: StorageConfig;
     user?: User | KernelUser;
     overrides?: KernelOverrides;
@@ -123,6 +130,10 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * is paused.
      */
     iframeBlocker?: UseIframeBlockerOptions | false;
+    /**
+     * Store the visitor's choice in a cookie and localStorage. On by default.
+     * Read once, when the provider mounts; see `storageConfig`.
+     */
     persistence?: boolean | UsePersistenceOptions;
     i18n?: Partial<I18nConfig>;
     /** Categories to offer alongside discovered integration categories, within policy scope. */
@@ -150,6 +161,16 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * @internal
      */
     __debugPkg?: string;
+    /**
+     * The code that applies a `prefetch` promise, from
+     * `@c15t/core/runtime/streamed-init`. Without it the provider loads that
+     * code once `prefetch` is a promise, so an app that never streams one
+     * doesn't download it. A framework root whose state is usually streamed
+     * (`ConsentRoot`) passes it, so the state applies as soon as it arrives
+     * instead of after one more request. Read once, at mount.
+     * @internal
+     */
+    __resolveStreamedInit?: ResolveStreamedInit;
 }
 /**
  * Options accepted when an external runtime supplies the kernel.
@@ -187,19 +208,21 @@ export type ConsentProviderProps = OwnedRuntimeProviderProps | ExternalRuntimePr
 /**
  * v3 ConsentProvider.
  *
- * Retains the enabled kernel while disabled mode uses a separate permissive
- * kernel, so toggling enabled preserves recorded choices. Provides the active
- * kernel via context and wires the curated v2-like options surface to v3
- * modules. It does not mirror the
- * snapshot into React state; selector hooks still subscribe directly to
- * the kernel through `useSyncExternalStore`.
+ * Builds one consent runtime (`createConsentProviderRuntime`) per mounted
+ * provider and renders its kernel: the kernel goes into context, and
+ * selector hooks subscribe to it through `useSyncExternalStore`. New
+ * options reach the runtime through `update()`, which applies only what
+ * changed; `mode`, `i18n`, `experiment`, `prefetch`, `persistence`,
+ * `storageConfig` and `clearOnRevocation` are read once. While `enabled` is
+ * `false` the runtime renders a separate permissive kernel, so toggling it
+ * keeps the visitor's records.
  *
  * Pass `runtime` to render a runtime someone else created. The provider
- * then borrows its kernel and mounts none of the side-effecting modules —
- * no second `init()`, no second persistence handle, no second `window.c15t`
- * — and does not dispose it on unmount. Handing it a different runtime
- * switches the tree to that runtime's kernel; switching between a borrowed
- * runtime and a provider-built kernel still needs a remount.
+ * then borrows its kernel and starts nothing — no second `init()`, no
+ * second persistence handle, no second `window.c15t` — and does not
+ * dispose it on unmount. Handing it a different runtime switches the tree
+ * to that runtime's kernel; switching between a borrowed runtime and a
+ * provider-built one still needs a remount.
  *
  * @example
  * ```tsx

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.4";
+export declare const version = "3.0.0-alpha.5";

package/docs/README.md

@@ -38,6 +38,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Content Security Policy](./frameworks/react/content-security-policy.md): Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.
 - [Customize](./frameworks/react/customize.md): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with the stylesheet, theme tokens, provider options and slots.
 - [Embeds](./frameworks/react/embeds.md): Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.
+- [IAB GPP](./frameworks/react/gpp.md): Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
 - [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
 - [Hooks](./frameworks/react/hooks.md): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
 - [IAB TCF](./frameworks/react/iab.md): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
@@ -111,7 +112,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Pinterest Tag](./integrations/pinterest-tag.md): Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.
 - [Pirsch](./integrations/pirsch.md): Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.
 - [Plausible Analytics](./integrations/plausible-analytics.md): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
-- [PostHog](./integrations/posthog.md): 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](./integrations/posthog.md): 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.
 - [Promptwatch](./integrations/promptwatch.md): Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.
 - [Reddit Pixel](./integrations/reddit-pixel.md): Load the Reddit Pixel only after marketing consent with the c15t redditPixel helper, guard rdt conversion calls, and check it in DevTools.
 - [RudderStack](./integrations/rudderstack.md): Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.

package/docs/concepts/consent-state.md

@@ -31,8 +31,9 @@ feature, stay blocked.
 
 A save records the choice in the browser first and sends it to the backend
 afterwards. The stock banner, preference dialog and IAB surfaces in every
-framework adapter, and the browser client's `acceptAll()`, `rejectAll()`
-and `save()`, close without waiting for the backend. In order:
+framework adapter, and the `acceptAll()`, `rejectAll()` and `save()` methods
+of the browser and Astro clients, close without waiting for the backend. In
+order:
 
 1. In the click task, the explicit choice and effective permissions change,
    `onChoiceRecorded` and `onPermissionsChanged` run, gated scripts, iframes
@@ -52,9 +53,10 @@ and `save()`, close without waiting for the backend. In order:
 
 A failed request does not reopen the surface or roll the choice back. The
 kernel emits `command:error`, which reaches the `onError` callback in adapters
-that accept one, and queues the payload in localStorage. The queue is replayed
-after the next successful initialization and when the browser comes back
-online, up to 10 attempts over 7 days. A replay carries the original action
+that accept one, and queues the payload in localStorage. Where localStorage is
+unavailable, the queue lives in memory until the page unloads. The queue is
+replayed after the next successful initialization and when the browser comes
+back online, up to 10 attempts over 7 days. A replay carries the original action
 time and policy snapshot token, so the backend records when the visitor
 decided, and a duplicate submission resolves to the same consent record. A
 backend that signs policy snapshot tokens rejects a replay made after the
@@ -66,6 +68,14 @@ after its TC string is encoded, which can wait for the TCF library to load.
 If that local step records nothing, for example because the vendor list
 failed to load, the surface comes back so the visitor can try again.
 
+Every adapter leaves the same surface after a save: the banner while the
+policy still owes a choice or a notice, and nothing once no prompt is owed,
+while the policy is still loading, or after it failed to resolve. A banner
+the visitor reopened closes too. A save that records nothing new, such as an
+unchanged selection, closes the surface when it resolves successfully. Opening
+or closing a surface, or starting another save, before then leaves the surface
+as the visitor set it.
+
 ## Preserve records during hydration
 
 Server helpers return records with policy information and evaluation time.
@@ -194,6 +204,10 @@ receive a stale TC string: c15t withdraws it, or holds it back, before
 
 ### Clearing records across tabs
 
+`clearRecords()` also drops every save queued for replay, with or without
+browser persistence, so nothing the visitor decided before the clear reaches
+the backend afterwards.
+
 `clearRecords()` removes every record and then stores the time of the clear,
 the clear epoch, under its own key: `c15t-epoch` in localStorage and a cookie
 of the same name (`<storageKey>-epoch` with a custom `storageKey`). Clearing

package/docs/customization/translations.md

@@ -68,8 +68,7 @@ The `ConsentGate` placeholder reads the `consentGate` section:
 | `consentGate.policyBlocked` | React and Vue show it in place of the title, with no button, when a strict policy leaves the category out of scope. |
 
 Earlier versions called this section `frame`. Copy under `frame` in
-`i18n.messages`, custom translations or an older backend's `/init` response
-still applies. c15t reads it as `consentGate`, a key set under `consentGate`
+`i18n.messages` or custom translations still applies. c15t reads it as `consentGate`, a key set under `consentGate`
 wins over the same key under `frame`, and c15t logs a warning once outside
 production. Rename the section to `consentGate` to remove the warning.
 

package/docs/frameworks/react/components/consent-provider.md

@@ -49,8 +49,12 @@ this provider and passes it server-resolved state.
 ## Provider options
 
 Keep the provider mounted across client navigation. It reads `mode`,
-`prefetch`, `persistence`, `clearOnRevocation` and the module options once,
-when it mounts. Remount the provider to change them.
+`prefetch`, `persistence`, `storageConfig`, `clearOnRevocation`, `i18n` and
+`experiment` once, when it mounts. Outside production, changing `mode`,
+`i18n`, `experiment`, `persistence` or `storageConfig` logs a warning. Remount
+the provider to change them. `scripts`, `vendors`, `networkBlocker`,
+`iframeBlocker`, `consentCategories`, `overrides`, `user`, `callbacks` and
+`enabled` apply when they change.
 
 | Option                        | Purpose                                                                                                                               |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |

package/docs/frameworks/react/components/dev-tools.md

@@ -95,7 +95,7 @@ explicit scope or policy categories, bulk saves cover all known categories.
 | ------------ | -------------------------------------------------------------------------------------------- |
 | **Consents** | Inspect and save categories, accept all, or reject optional categories                       |
 | **Scripts**  | Configured scripts, loading status, search, and external page resources                      |
-| **Location** | Detected jurisdiction, country, region, and consent model                                    |
+| **Location** | Resolved country and region, and location overrides                                          |
 | **Policy**   | Resolved policy and UI configuration                                                         |
 | **IAB**      | Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings |
 | **Events**   | Timeline of consent changes, kernel events, and script lifecycle events                      |

package/docs/frameworks/react/gpp.md

@@ -0,0 +1,163 @@
+---
+title: IAB GPP
+description: Add the IAB Global Privacy Platform API (__gpp) to a React app with
+  ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the
+  TCF EU consent string.
+group: frameworks
+---
+
+## What GPP does
+
+`ConsentGPP` from `@c15t/react/gpp` installs `window.__gpp`, the GPP 1.1 CMP
+API, and keeps its GPP string in step with the visitor's choices. Prebid.js,
+Google Ad Manager and other ad tech read US privacy signals from it.
+
+## Turn on GPP
+
+Render `ConsentGPP` inside `ConsentProvider`:
+
+```tsx title="src/consent.tsx"
+import { ConsentGPP } from '@c15t/react/gpp';
+
+<ConsentProvider options={{ mode, scripts }}>
+	<ConsentGPP />
+	{children}
+</ConsentProvider>;
+```
+
+`ConsentGPP` renders nothing. It installs `__gpp` after it mounts and
+removes it when it unmounts. It lives in its own entry, like
+`@c15t/react/iab`, so apps that do not import it bundle none of the GPP
+code. `@c15t/react` already depends on `@c15t/iab`; with the `c15t`
+package, import from `c15t/react/gpp`.
+
+The props are the GPP options listed below, for example
+`<ConsentGPP usFallback="none" />`. It works the same with a runtime you
+pass to `ConsentProvider` as `runtime`.
+
+The GPP string follows the policy and location your backend resolves for the
+visitor, so a US visitor's state comes from the backend. With `offline()`
+mode, pass the state yourself, for example
+`overrides: { country: 'US', region: 'CA' }`.
+
+To add the TCF EU section for visitors under an `iab` policy, set up
+[IAB TCF](./iab.md) as well.
+
+## How the policy decides the section
+
+The policy rule c15t matched for the visitor decides whether a section
+applies. The visitor's location only picks which US section carries it.
+
+| Matched rule and visitor                                                                       | Section in the GPP string                                                  |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `iab` rule, with IAB TCF set up                                                                | `tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged               |
+| `iab` rule, any visitor, with `tcf: false`                                                     | None; `applicableSections` is `[-1]`                                       |
+| Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section | That state's section, such as `usca` (ID 8)                                |
+| The same rule, US visitor whose region is unknown or whose state has no section                | `usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'` |
+| The same rule, `usApproach: 'national'`                                                        | `usnat` for every US visitor                                               |
+| A rule without those rights, such as `none`                                                    | None                                                                       |
+| A visitor outside the US under any rule other than `iab`                                       | None                                                                       |
+
+Every `opt-in` and `opt-out` rule has the `preferences` right, and every
+`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
+them. A rule that gives the visitor no way to opt out produces no US
+section, even when the visitor sends a GPC signal.
+
+State sections exist for California, Colorado, Connecticut, Delaware, Florida,
+Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
+Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
+Island are not encoded yet: their published specifications start the section
+with a header that the IAB reference implementation does not encode. Visitors
+there get the fallback, `usnat` by default. So does a US visitor whose region
+the geo headers did not supply.
+
+The MSPA US National specification describes `usnat` for MSPA signatories
+that chose the national approach. Without `mspaMode`, c15t reports the
+fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction:
+2`), which still carries the opt-outs to vendors such as Prebid.js. If you
+reserve `usnat` for the national approach, set `usFallback: 'none'`; those
+visitors then get no section until their state resolves.
+
+## What the US sections report
+
+* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
+  out) when the `marketing` category is not permitted, otherwise `2`. A
+  refusal, a GPC signal the rule maps to `marketing` through
+  `privacySignals.gpc`, and an opt-in rule without a grant all count.
+* The opt-out notices: `1` (given), since the rule offers an opt-out.
+* The sharing or processing notice: `1` when the rule has the `disclosure`
+  right, otherwise `2`.
+* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
+  GPC subsection. It is reported even when the rule does not map GPC to a
+  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
+  should follow it too.
+* Sensitive data and known-child consents: `0` (not applicable). c15t has no
+  category for them, so the string states that you do not process sensitive
+  data or knowingly process children's data. If you do, GPP from c15t does
+  not describe your processing; collect and signal that consent separately.
+* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.
+
+The notice fields are your attestation, made through the rule's rights:
+c15t cannot see whether your privacy notice is on the page. Show the notices
+the rule promises, including a persistent opt-out control.
+
+## GPP options
+
+Every field is optional. Pass them in the `gpp` option, where `gpp: true`
+uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
+`@c15t/browser`.
+
+| Option             | Default                             | Effect                                                                                                                                                                                                                          |
+| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cmpId`            | the IAB CMP ID c15t holds, else `1` | CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.                       |
+| `usApproach`       | `'state'`                           | `'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.                                                           |
+| `usFallback`       | `'usnat'`                           | Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.                                                                                                         |
+| `mspaMode`         | unset                               | `'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable. |
+| `optOutCategories` | `['marketing']`                     | Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.                                                                                                                                          |
+| `tcf`              | `true`                              | Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.                                                                                                                                           |
+
+## Check the signal
+
+Open the browser console on a page with GPP on and call:
+
+```js
+__gpp('ping', (data) => console.log(data));
+```
+
+For a California visitor who has not opted out, the result includes
+`applicableSections: [8]`, `signalStatus: 'ready'` and
+`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
+`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
+returns the same value. Scripts in iframes reach the API through the
+`__gppLocator` frame and `postMessage`.
+
+Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
+IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
+`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
+as the IAB reference implementation does: TCF vendors read consent from
+events, not on demand.
+
+`signalStatus` stays `'not ready'` while the policy is pending, while the
+banner or dialog is open, while an `iab` rule has no confirmed TC String,
+and while a new TC String is decoded. Listeners added with
+`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
+and `sectionChange` events, then `signalStatus: 'ready'`.
+
+## Ad tags that load before c15t
+
+c15t installs `__gpp` in the browser once consent starts, after it loads the
+GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
+the calls and listeners a stub queued, whether the stub keeps listeners on
+`__gpp.events`, as the GPP specification's sample does, or returns them from
+`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
+`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
+When another stub already answers iframes, c15t leaves that to it, so each
+iframe call gets one reply.
+
+If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
+The `gpp` option reports the conflict to the `onError` callback,
+`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
+CMP per page.
+
+GPP signals what the visitor chose; it does not block scripts. Gate vendor
+scripts with c15t's script loading as well.

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: