@c15t/scripts 3.0.0-alpha.3 → 3.0.0-alpha.4

package/AGENTS.md

@@ -143,7 +143,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Pinterest Tag](./docs/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](./docs/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](./docs/integrations/plausible-analytics.md): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
-- [PostHog](./docs/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](./docs/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](./docs/integrations/promptwatch.md): Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.
 - [Reddit Pixel](./docs/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](./docs/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/README.md

@@ -143,7 +143,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/astro/scripts.md

@@ -65,6 +65,15 @@ c15t({
 
 Scripts from `astro.config.mjs` and from the client entrypoint both load.
 
+## What a site without scripts skips
+
+The script loader is part of the page's boot script only when the site
+configures `scripts` in `astro.config.mjs` or sets a `clientEntrypoint`, which
+may add some. A site with neither never downloads it, about 4 KB gzip less on
+every page. The [network blocker](./network-blocker.md) works the same way: it
+ships in the boot script when the integration options have `networkBlocker`
+rules, and loads as its own chunk when only the client entrypoint sets them.
+
 ## Gate an inline script
 
 For a script that has to stay in the page's markup, make it inert and label it

package/docs/frameworks/javascript/scripts.md

@@ -52,6 +52,24 @@ const scripts = [
 [script loader](https://c15t.com/docs/frameworks/javascript/modules/script-loader) page lists
 every field and callback.
 
+## When the script loader downloads
+
+With `@c15t/browser` from npm, the script loader and the network blocker
+share a separate chunk. It loads when c15t starts, and only if `scripts` is
+not empty or `networkBlocker` has rules, so a page with neither never
+downloads it. On a page with either, the browser requests it after your
+JavaScript has run, which delays a returning visitor's consented scripts and
+held requests by one request.
+
+Your bundler names that chunk, so c15t cannot link it from your HTML. To
+start the download earlier, add a `<link rel="modulepreload">` for the chunk
+your build emits for `@c15t/core/dist/modules/loader-and-blocker.js`. With
+Vite, `.vite/manifest.json` lists it under that path when `build.manifest` is
+on. Give the link `fetchpriority="low"`. c15t needs the chunk only when it
+starts, and at the default priority the preload can delay your app's own
+chunks over HTTP/1.1. The script-tag build, `c15t.js`, already contains the
+loader.
+
 ## Gate a snippet in your HTML
 
 `@c15t/browser` also runs `<script type="text/plain" data-c15t-category>`

package/docs/frameworks/svelte/scripts.md

@@ -28,6 +28,13 @@ export const scripts = [
 
 Replace the placeholder PostHog project key and X Pixel ID with your own.
 
+The provider loads the script loader as a separate chunk, shared with the
+[network blocker](./network-blocker.md), and only when `scripts` is not empty or
+the blocker has rules, so an app with neither never downloads it. A
+single-page app has no server render to link the chunk from, so the browser
+requests it after your app's JavaScript has run. A SvelteKit app can preload
+it from the server-rendered page; the SvelteKit scripts guide shows how.
+
 ## How registered scripts load
 
 The provider's `scripts` prop takes an array of script configurations. Each

package/docs/frameworks/sveltekit/network-blocker.md

@@ -140,6 +140,16 @@ Open DevTools, clear site data for your origin and reload:
 `fetch('https://www.google-analytics.com/g/collect')` in the console returns a
 response with status `451` while measurement is denied.
 
+## Preload the blocker
+
+The blocker shares a separate chunk with the script loader. The chunk loads
+only on pages with `networkBlocker` rules or `scripts`, and matching requests
+wait until it has loaded. Add the `c15tPreload()` Vite plugin so `c15tHandle`
+links the chunk from the page's `<head>` and the browser fetches it with the
+app's own code.
+[Preload the script loader](./scripts.md#preload-the-script-loader) shows the
+setup.
+
 ## Server requests are not blocked
 
 The network blocker runs in the browser. A `fetch` in a SvelteKit `load`,

package/docs/frameworks/sveltekit/scripts.md

@@ -32,6 +32,37 @@ configurations hold functions, which a server load cannot send to the
 browser. Scripts load only in the browser, after hydration, so they never
 appear in server HTML.
 
+## Preload the script loader
+
+The provider loads the script loader only on pages whose `scripts` array is
+not empty or that have [network blocker](./network-blocker.md) rules. The loader
+and the blocker share one separate chunk. Pages with neither never download
+it. On a page with either, the browser would otherwise request the chunk after
+the app's JavaScript has run, and a returning visitor's consented scripts and
+held requests would wait for that extra request.
+
+Add the `c15tPreload()` Vite plugin so `c15tHandle` can link the chunk from
+the page's `<head>` with `<link rel="modulepreload">`:
+
+```ts title="vite.config.ts (partial)"
+import { c15tPreload } from '@c15t/svelte/vite';
+
+export default defineConfig({ plugins: [sveltekit(), c15tPreload()] });
+```
+
+SvelteKit builds the server before the client, so the server cannot know the
+chunk's file name. After the client build, the plugin writes the chunk URL
+into the server output, before SvelteKit prerenders pages and before the
+adapter copies the build. Then `c15tHandle` adds one link to every page whose
+provider has scripts or blocker rules, prerendered pages included. The link
+carries the provider's `nonce`, or else the nonce SvelteKit put on its own
+scripts. It asks for low priority (`fetchpriority="low"`): the
+runtime needs the chunk only after hydration, so the browser fetches your
+app's own chunks first. It does nothing in `vite dev`.
+
+Without the plugin, or without `c15tHandle` in `hooks.server.ts`, scripts
+still load, one request later.
+
 ## How registered scripts load
 
 The provider's `scripts` prop takes an array of script configurations. Each

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:
 

package/docs/upgrade-v3.md

@@ -431,10 +431,31 @@ npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply
 ```
 
 The migrator recognizes the v2 schema, adopts it, and adds the v3 tables and
-columns. [Database setup](https://c15t.com/docs/self-host/guides/database-setup#upgrade-a-v2-backend)
+columns. Apply it before the v3 backend serves traffic: v3 records policy
+decisions without the v2 `jurisdiction` label, which the migration makes
+nullable. [Database setup](https://c15t.com/docs/self-host/guides/database-setup#upgrade-a-v2-backend)
 covers the details, and the [backend quickstart](https://c15t.com/docs/self-host/quickstart)
 shows a complete v3 config and route.
 
+### Remove `disableGeoLocation`
+
+v3 removes the `disableGeoLocation` manifest option. Policy rules decide by
+country and region. To show every visitor the same banner, configure one rule
+with `match: { isDefault: true }`. It applies wherever the visitor is, so the
+browser can resolve it without asking the backend for a location.
+
+To test one region's rule from anywhere, set the country in the client's
+`overrides`, for example `overrides: { country: 'US' }`. See
+[runtime options](https://c15t.com/docs/frameworks/javascript/api/runtime).
+
+### Stop reading `jurisdiction`
+
+`/init` responses, session reports and `sessions.onReport` no longer carry a
+`jurisdiction` label such as `GDPR`. Read the matched policy from
+`policyResolution` instead, or the report's `policy`, `country` and `region`.
+The backend still accepts `jurisdiction` in a v2 client's save request and
+ignores it.
+
 ## Update the Node.js SDK
 
 Install `@c15t/node-sdk@alpha`. The v2 client is gone: create one with

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/scripts",
-	"version": "3.0.0-alpha.3",
+	"version": "3.0.0-alpha.4",
 	"description": "Deprecated v3 compatibility package for @c15t/integrations. Migrate before v4.",
 	"homepage": "https://c15t.com/docs/upgrade-v3#rename-the-integrations-dependency",
 	"bugs": {
@@ -41,7 +41,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@c15t/integrations": "3.0.0-alpha.3"
+		"@c15t/integrations": "3.0.0-alpha.4"
 	},
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1",