@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/posthog.md

@@ -1,258 +1,397 @@
 ---
 title: PostHog
-description: PostHog is an open-source product analytics platform for tracking
-  user behavior, session replays, feature flags, and A/B testing. It supports
-  cookieless tracking, allowing analytics to continue even without cookie
-  consent.
-icon: posthog
+description: Choose PostHog loading and cookieless behavior, configure the
+  region, and synchronize v3 permissions.
 group: integrations
 ---
-PostHog is an open-source product analytics platform that helps you understand user behavior, track events, and analyze product usage. Unlike traditional analytics tools, PostHog supports both cookieless and cookie-based tracking. This means you can sync c15t with PostHog and, when your PostHog project is configured for cookieless tracking, continue collecting privacy-preserving analytics after a user rejects measurement consent.
 
-c15t exposes two integration patterns for PostHog. Pick the one that matches how you already load the SDK:
+## Configure PostHog
 
-* **PostHog SDK** — your app loads `posthog-js` itself; c15t only synchronizes consent. Recommended for most React apps.
-* **PostHog Script** — c15t loads PostHog's array bootstrap as a managed `Script`.
+Use the browser project token beginning with `phc_`. Select the region matching
+your PostHog project. This example waits for measurement permission before
+requesting the SDK.
 
-## Integrate with c15t
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-### SDK pattern
+```ts title="src/consent-scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
 
-This is the recommended approach if you're using the PostHog JS SDK; it's commonly used in React projects.
+export const scripts = [
+  posthog({
+    id: 'phc_YOUR_PROJECT_TOKEN',
+    region: 'eu',
+    loadMode: 'after-consent',
+    initOptions: { cookieless_mode: 'never' },
+  }),
+];
+```
 
-1. **Enable cookieless tracking in PostHog** Before using `cookieless_mode`, enable **Cookieless server hash mode** in your PostHog project under **Project Settings** > **Web analytics**. PostHog ignores cookieless events unless this project setting is enabled.
+The helper initializes PostHog. Remove a separate `posthog-js` initializer,
+framework plugin or array snippet before using this setup.
 
-2. **Initialize PostHog** When you initialize PostHog, set `cookieless_mode` to `on_reject`. This keeps PostHog from writing cookies or local/session storage until the user grants measurement consent. If the user rejects measurement consent, c15t calls `opt_out_capturing()` and PostHog switches to cookieless capture.
+## Register the scripts
 
-   ```ts
-   posthog.init("phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", {
-     api_host: "https://eu.i.posthog.com",
-     defaults: "2026-01-30",
-     cookieless_mode: 'on_reject'
-   })
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry so c15t owns loading once.
 
-   posthog.opt_out_capturing() // Avoids cookie-based capture until c15t syncs consent
-   ```
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
 
-3. **Sync settled consent once, then subscribe to real changes** The recommended PostHog SDK approach uses two phases: run one initial sync after c15t has finished resolving consent, then subscribe to future real preference changes with `subscribeToConsentChanges()`.
+**Next.js**
 
-   With cookieless\_mode: 'on\_reject', denied measurement consent does not mean "no events." It means PostHog records cookieless events without browser persistence. If your product needs denied consent to stop all PostHog event capture, do not use cookieless mode; load or call PostHog only after consent is granted.
+Import the configuration into the client boundary from your router guide:
 
-   > ⚠️ Warning:
-   > Do not use posthog.has\_opted\_in\_capturing() or posthog.has\_opted\_out\_capturing() to decide whether to show your banner. In recent PostHog versions, has\_opted\_in\_capturing() can return true when consent is still pending. Use c15t's consent store as the source of truth, or use PostHog's get\_explicit\_consent\_status() when you specifically need PostHog's stored consent state.
-   >
-   > ℹ️ Info:
-   > To wrap this in your framework, pass the callbacks option to your ConsentManagerProvider the same way you would pass scripts — see the JavaScript, React, or Next.js script loader guide.
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
 
-   ```ts
-   import { getOrCreateConsentRuntime } from 'c15t';
-   import posthog from 'posthog-js';
-
-   function syncPostHogMeasurementConsent(hasMeasurementConsent: boolean) {
-     if (hasMeasurementConsent) {
-       posthog.opt_in_capturing();
-     } else {
-       posthog.opt_out_capturing();
-     }
-   }
-
-   const runtime = getOrCreateConsentRuntime({
-     mode: 'hosted',
-     callbacks: {
-       onBannerFetched() {
-         syncPostHogMeasurementConsent(
-           runtime.consentStore.getState().has('measurement')
-         );
-       },
-     },
-   });
-
-   runtime.consentStore
-     .getState()
-     .subscribeToConsentChanges(({ allowedCategories }) => {
-       syncPostHogMeasurementConsent(
-         allowedCategories.includes('measurement')
-       );
-     });
-   ```
-
-   > ℹ️ Info:
-   > Avoid using onConsentSet plus manual deduplication for PostHog. subscribeToConsentChanges() already gives you the exact change-only semantics most analytics SDKs need.
-
-### Script helper pattern
-
-If you want to load PostHog via a script tag, it's recommended to use this approach.
-
-1. **Choose a region and loading mode** The c15t helper seeds PostHog's initialization queue, loads the bootstrap script, and synchronizes consent through `posthog.opt_in_capturing()` / `posthog.opt_out_capturing()`. You do not need to call `posthog.init()` separately.
-
-   Use region to keep PostHog's API, UI, and bootstrap script hosts aligned. c15t defaults to region: 'eu'; set region: 'us' for PostHog Cloud US. You can still pass apiHost, uiHost, or scriptUrl for self-hosted or proxied setups.
-
-   The helper supports three loading modes:
-
-   * `loadMode: 'always'` — the backwards-compatible default. PostHog loads immediately and c15t synchronizes measurement consent through PostHog's APIs. Use this when you intentionally want PostHog cookieless behavior after rejection.
-   * `loadMode: 'after-consent'` — PostHog is not requested until measurement consent is granted. This is the recommended GDPR/EU cookie-banner default when your policy requires no PostHog network activity before consent.
-   * `loadMode: 'disabled'` — returns an inert callback-only script with no PostHog network request. Use this for environment flags or temporary rollouts.
-
-   > ℹ️ Info:
-   > For a privacy-first GDPR/EU cookie-banner setup, use region: 'eu' with loadMode: 'after-consent'. This keeps PostHog Cloud in the EU region and prevents any PostHog script request until measurement consent is granted.
-
-   The helper includes these PostHog init defaults:
-
-   ```ts
-   const initOptions = {
-     api_host: 'https://eu.i.posthog.com',
-     ui_host: 'https://eu.posthog.com',
-     defaults: '2026-01-30',
-     cookieless_mode: 'on_reject',
-   };
-   ```
-
-   You can still override any of these through initOptions. Keep cookieless\_mode: 'on\_reject' when you want PostHog to use cookieless capture after a consent rejection.
-
-2. **Enable cookieless tracking in PostHog** Enable **Cookieless server hash mode** in your PostHog project under **Project Settings** > **Web analytics** when you use `loadMode: 'always'` and want rejected-consent traffic to be recorded cookielessly. This is required by PostHog before cookieless events are accepted.
-
-3. **Add the script helper**
-
-   import \{ type ReactNode } from 'react';
-   import \{ ConsentManagerProvider } from '@c15t/react';
-   import \{ posthog } from '@c15t/scripts/posthog';
-
-   const scripts = \[
-    posthog(\{
-    id: 'phc\_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-    region: 'eu',
-    loadMode: 'after-consent',
-    }),
-   ];
-
-   export function ConsentProvider(\{ children }: \{ children: ReactNode }) \{
-    return (
-   &#x20;\<ConsentManagerProvider
-   &#x20;options=\{\{
-   &#x20;mode: 'hosted',
-   &#x20;backendURL: 'https\://your-instance.c15t.dev',
-   &#x20;scripts,
-   &#x20;}}
-   &#x20;\>
-   &#x20;\{children}
-   &#x20;\</ConsentManagerProvider>
-   &#x20;);
-   }'use client';
-
-   import \{ type ReactNode } from 'react';
-   import \{ ConsentManagerProvider } from '@c15t/nextjs';
-   import \{ posthog } from '@c15t/scripts/posthog';
-
-   const scripts = \[
-   &#x20;posthog(\{
-   &#x20;id: 'phc\_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-   &#x20;region: 'eu',
-   &#x20;loadMode: 'after-consent',
-   &#x20;}),
-   ];
-
-   export function ConsentProvider(\{ children }: \{ children: ReactNode }) \{
-   &#x20;return (
-   &#x20;\<ConsentManagerProvider
-   &#x20;options=\{\{
-   &#x20;mode: 'hosted',
-   &#x20;backendURL: '/api/c15t',
-   &#x20;scripts,
-   &#x20;}}
-   &#x20;\>
-   &#x20;\{children}
-   &#x20;\</ConsentManagerProvider>
-   &#x20;);
-   }import \{ getOrCreateConsentRuntime } from 'c15t';
-   import \{ posthog } from '@c15t/scripts/posthog';
-
-   getOrCreateConsentRuntime(\{
-   &#x20;mode: 'hosted',
-   &#x20;backendURL: 'https\://your-instance.c15t.dev',
-   &#x20;scripts: \[
-   &#x20;posthog(\{
-   &#x20;id: 'phc\_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-   &#x20;region: 'eu',
-   &#x20;loadMode: 'after-consent',
-   &#x20;}),
-   &#x20;],
-   });
-
-### No PostHog request before consent
-
-If your policy requires PostHog to be completely absent until the user grants measurement consent, use `loadMode: 'after-consent'`:
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
 
-```ts
-import { posthog } from '@c15t/scripts/posthog';
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-const scripts = [
-  posthog({
-    id: 'phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-    region: 'eu',
-    loadMode: 'after-consent',
-  }),
-];
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
+
+**TanStack Start**
+
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+function Root() {
+  const state = Route.useLoaderData();
+  return (
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
+  );
+}
 ```
 
-With this mode, c15t does not inject the PostHog script until `measurement` consent is granted. PostHog cannot record cookieless rejected-consent events because the SDK has not loaded.
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
 
-For PostHog Cloud US, switch the region:
+**React**
+
+Import the scripts into your existing provider component:
 
 ```ts
-posthog({
-  id: 'phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-  region: 'us',
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
+
+**Nuxt**
+
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
+```
+
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+
+**Vue**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
+
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
 });
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-## How c15t loads it
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
 
-* **Category:** `measurement` (Analytics)
-* **SDK pattern:** your app loads `posthog-js`; c15t synchronizes
-  measurement consent with PostHog opt-in and opt-out APIs.
-* **Script helper pattern:** by default, c15t loads PostHog on page start with
-  [`alwaysLoad`](/docs/frameworks/react/script-loader#always-load), then
-  switches PostHog between cookie-based and cookieless capture as consent
-  changes. Set `loadMode: 'after-consent'` to block the script request until
-  measurement consent is granted.
+**Astro**
 
-## Tracking events in your app
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
 
-The behavior depends on which pattern you chose:
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
 
-* **SDK Implementation** — your app loaded `posthog-js` itself, so `posthog.capture(...)` is available once your SDK setup has run. c15t calls `opt_in_capturing()` / `opt_out_capturing()` for you. Pending events before c15t syncs consent may be dropped; after denial, PostHog captures cookieless events.
-* **Script Implementation with `loadMode: 'always'`** — `window.posthog` is defined early as a queue. Calls to `posthog.capture(...)` before the bootstrap finishes are replayed after the SDK installs instead of being dropped. c15t queues the current consent decision ahead of those calls, then keeps calling `opt_in_capturing()` / `opt_out_capturing()` as consent changes. After denial, PostHog captures cookieless events when your PostHog project supports cookieless mode.
-* **Script Implementation with `loadMode: 'after-consent'`** — PostHog is unavailable until measurement consent is granted. Guard `posthog.capture(...)` calls or call them only after consent.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-> ⚠️ **Warning:**
-> PostHog may start a new session when a user moves between cookieless and cookie-based capture. This can split pre-consent and post-consent activity into separate sessions, which may inflate session counts or affect funnels around the consent boundary. Treat this as a PostHog analytics limitation, not a c15t consent sync issue. See the upstream PostHog session continuity issue.
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
 
-```ts
-posthog.capture('signup');
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
+
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-You do not need to guard these calls with `useConsentManager().has('measurement')` when cookieless measurement after rejection is acceptable. Add your own guard if denied consent should mean no PostHog event capture at all.
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
 
-## Consent and privacy
+**SvelteKit**
 
-PostHog's GDPR guidance recommends using PostHog Cloud EU for robust GDPR compliance, configuring consent clearly, and limiting what personal data is collected. Cookieless mode helps avoid browser persistence when measurement consent is rejected, but it does not replace your own legal basis, consent language, data minimization, IP capture settings, or right-to-be-forgotten process.
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
 
-## Types
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
 
-### PosthogConsentOptions
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`PosthogConsentOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/posthog.ts\`|
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
 
-\*ExtractedTypeTable: Could not extract "PosthogConsentOptions" from "./packages/scripts/src/vendors/analytics/posthog.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+**JavaScript**
 
-### Script
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
+
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
+
+## Choose loading and capture behavior separately
+
+| `loadMode`                     | SDK loading                           | Consent handling                                                |
+| ------------------------------ | ------------------------------------- | --------------------------------------------------------------- |
+| `'after-consent'`              | Waits for measurement permission      | Calls PostHog opt-in and opt-out APIs after load and on changes |
+| `'always'`, the helper default | Loads even while permission is denied | Calls the same consent APIs                                     |
+| `'disabled'`                   | Does not load PostHog                 | Does not synchronize consent with an SDK loaded elsewhere       |
+
+The helper defaults `initOptions.cookieless_mode` to `'on_reject'`. In that
+mode, PostHog can continue cookieless capture after denial. It requires the
+project's cookieless server hash setting. See
+[PostHog's cookieless guide](https://posthog.com/tutorials/cookieless-tracking).
+
+The example overrides this with `'never'` so opting out is not a switch to
+cookieless capture. Loading after consent only controls the initial request;
+for later revocation, verify PostHog's opt-out behavior and stop application
+capture calls too. SDK code that already executed cannot be undone by removing
+its script element.
+
+## Configure hosts and initialization
+
+| Option                         | Behavior                                                                                 |
+| ------------------------------ | ---------------------------------------------------------------------------------------- |
+| `id`                           | Browser project token.                                                                   |
+| `region`                       | `'eu'` by default; use `'us'` for a US project.                                          |
+| `apiHost / uiHost / scriptUrl` | Explicit overrides for proxy or self-hosted PostHog deployments. Keep all hosts aligned. |
+| `loadMode`                     | Defaults to `'always'`; choose deliberately.                                             |
+| `initOptions`                  | Additional serializable SDK options, including the cookieless override.                  |
+
+The helper applies the resolved API and UI hosts after `initOptions`; use the
+top-level host fields to change them. A global `posthog` queue may exist before
+the SDK is ready. Neither API presence nor SDK readiness is a consent grant.
+
+## Keep application events behind permission
+
+With the script helper registered, a React client component can guard an event
+using the current effective permission:
+
+```tsx title="src/signup-event.tsx"
+'use client';
+
+import { useConsent } from 'c15t/react';
+
+export function SignupEvent() {
+  const allowed = useConsent('measurement');
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (allowed) window.posthog?.capture('signup_started');
+      }}
+    >
+      Start signup
+    </button>
+  );
+}
+```
+
+This is an event-call example, not a signup implementation. Next.js client
+components can import `useConsent` from `c15t/next`.
+
+## Use an existing PostHog SDK
+
+If your app already initializes `posthog-js`, keep that SDK owner and attach a
+callback-only script instead of the loading helper. Initialize your SDK with
+`opt_out_capturing_by_default: true` and `cookieless_mode: 'never'` before
+mounting c15t when denied permission must stop capture.
+
+```ts title="src/posthog-consent.ts"
+import type { Script, ScriptCallbackInfo } from 'c15t/modules/script-loader';
+
+type PostHogConsentApi = {
+  opt_in_capturing: () => unknown;
+  opt_out_capturing: () => unknown;
+};
+
+export function posthogConsent(instance: PostHogConsentApi): Script {
+  const sync = ({ hasConsent }: ScriptCallbackInfo) => {
+    if (hasConsent) instance.opt_in_capturing();
+    else instance.opt_out_capturing();
+  };
+
+  return {
+    id: 'posthog-sdk-consent',
+    category: 'measurement',
+    callbackOnly: true,
+    alwaysLoad: true,
+    onBeforeLoad: sync,
+    onConsentChange: sync,
+  };
+}
+```
 
-\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Pass `posthogConsent(posthog)` in the existing provider's `scripts` array, using
+your initialized SDK instance. The callback-only entry synchronizes initial
+and changed effective permissions without loading a second SDK. It does not
+block the SDK import or its initial request. `loadMode: 'disabled'` on the
+loading helper is not a substitute, because it performs no synchronization.
+
+Keep c15t as the source of truth for the banner and saved choices. Effective
+permission can come from policy defaults; a synchronization callback is not
+proof that the visitor explicitly accepted. Do not reuse v2
+`getOrCreateConsentRuntime` or `onBannerFetched` examples with v3.
+
+## Verify the integration
+
+With the example above, a fresh opt-in session should make no PostHog SDK
+request until measurement is allowed. Grant, capture one test event, revoke,
+and confirm later application calls stop. Repeat with persisted consent and
+client navigation. If you choose cookieless capture, verify that behavior
+explicitly in the project rather than expecting silence after denial. See
+[consent verification](../guides/verify-consent.md).