@posthog/browser-common 0.2.3 → 0.2.5

package/README.md

@@ -6,26 +6,22 @@ runtime, but it is not a public API surface and does not provide compatibility
 guarantees outside PostHog SDK packages.
 
 The shared extension contract includes the interface an extension implements
-(`Extension`), the host services it is handed (`Client`), the core analytics
-capability (`CoreExtension`), and small shared runtime primitives such as
-`Publisher`.
+(`Extension`), the host adapter it receives (`Client`), and small shared runtime
+primitives such as `Publisher`.
 
 This contract is designed so an extension can run unchanged across major
 versions of the web SDK. Concrete host adapters remain owned by their SDK
 packages; browser-v1 and browser-v2 composition and loading integration are
 separate from this shared runtime.
 
-A conforming SDK provides a _client adapter_ that implements `Client` over its
-own internals, so extension code never depends on a specific SDK.
-
 ## Concepts
 
 ### `Extension`
 
-What you implement. The host calls only `setup` and `dispose`:
+What you implement. The host calls `setup` once and optional `dispose` for final cleanup:
 
 ```ts
-import { CoreExtension, type Disposable, type Extension } from '@posthog/browser-common'
+import type { Disposable, Extension } from '@posthog/browser-common'
 
 export function webContext(): Extension {
     let removeProperties: Disposable | undefined
@@ -33,11 +29,7 @@ export function webContext(): Extension {
     return {
         name: 'webContext',
         setup(client) {
-            const core = client.getExtension(CoreExtension)
-            if (!core) {
-                throw new Error('CoreExtension is required')
-            }
-            removeProperties = core.registerDynamicEventProperties(() => ({
+            removeProperties = client.registerDynamicEventProperties(() => ({
                 $current_url: window.location.href,
             }))
         },
@@ -48,93 +40,63 @@ export function webContext(): Extension {
 }
 ```
 
-`setup(client)` may be async (read async state before you're ready); `dispose()`
-may be async (final flush). Static config the app sets goes in your constructor,
-not on the `Client`.
+`setup(client)` may be async to read state before the extension is ready. Async
+extensions must guard work after each `await` so cleanup cannot be followed by
+late listener or timer installation. `dispose()` is synchronous, optional,
+idempotent, and best-effort. Static app config goes in the constructor, not on
+`Client`.
 
 Anything in `setup` that returns a `Disposable` must be held by the extension
 and disposed in `dispose()`. Use `createDisposable(teardown)` when adapting a
-callback into idempotent teardown.
+synchronous callback into idempotent teardown.
 
 ### `Client`
 
-What an extension is given in `setup` — the host's extension services:
-
-- **transport**: `projectToken`, `sendRequest(path, init?)`
-- **registry**: `getExtension(token)`
-- **storage & logging**: `kv`, `logger`
-
-### `CoreExtension`
+What an extension is given in `setup` — the adapter shared by extensions on that host SDK instance:
 
-A conforming host must register one `CoreExtension` before setting up product
-extensions. Resolve it through `client.getExtension(CoreExtension)` for behavior
-owned by the PostHog client's analytics core:
-
-- **identity & session**: `distinctId`, `anonymousId`, `groups`, `session`
+- **identity and session**: `distinctId`, `anonymousId`, `groups`, `session`
 - **events**: `capture(...)`, `registerDynamicEventProperties(...)`, `onEvent(...)`
-- **lifecycle**: `onNewSession(...)`
-- **server config**: `getRemoteConfig()` (current), `onRemoteConfig(...)` (changes)
+- **server config**: `getRemoteConfig()` and `onRemoteConfig(...)`
+- **transport**: `projectToken`, `sendRequest(path, init?)`
+- **storage and logging**: `kv`, `logger`
 
 Identity, session, and the public project token are always-ready synchronous
-reads. Operations that perform I/O, including `capture`, `sendRequest`, `kv`,
-and `getRemoteConfig`, are awaitable.
+reads. Operations that may perform I/O, including `capture`, `sendRequest`,
+`kv`, and `getRemoteConfig`, are awaitable. Extensions that want a named log
+prefix can create a child with `client.logger.createLogger('[myExtension]')`.
 
 ### Host runtime
 
 PostHog browser SDK implementations share extension registration and teardown
 through `ExtensionRuntime`, imported from the dedicated
-`@posthog/browser-common/extension-runtime` subpath. It reserves names and
-capability tokens during setup, publishes providers only after successful
-readiness, and disposes extensions once in reverse registration order. Concrete
-SDKs still own the `Client` adapter, Core implementation, and SDK lifecycle
-hooks.
+`@posthog/browser-common/extension-runtime` subpath. It reserves extension names
+during setup, rolls back failed setup, and disposes extensions once in reverse
+registration order without waiting for pending setup. Concrete SDKs still own
+their `Client` adapter and SDK lifecycle hooks.
 
 `ExtensionRuntime` is host infrastructure, not part of the extension-author
 surface exported from the package root.
 
 ### `Publisher`
 
-Use `Publisher<T>` when an extension provides its own event stream to other
-extensions or to app-facing controls. Keep the publisher private, expose only its
-`listener`, and dispose it when the extension is torn down:
+Use `Publisher<T>` when an extension exposes an event stream. Keep the publisher
+private, expose only its listener, and dispose it with the extension:
 
 ```ts
 import { Publisher, type Listener } from '@posthog/browser-common'
 
-const changes = new Publisher<FeatureFlagsChange>()
+const changes = new Publisher<{ enabled: boolean }>()
+export const onChange: Listener<{ enabled: boolean }> = changes.listener
 
-export const onChange: Listener<FeatureFlagsChange> = changes.listener
-
-changes.publish({ flag: 'beta-ui', value: true })
+changes.publish({ enabled: true })
 changes.dispose()
 ```
 
-## Cross-extension dependencies
-
-Extensions depend on one another through tokens, never implementation imports:
-
-```ts
-import { FeatureFlags } from './feature-flags/token'
-
-const flags = client.getExtension(FeatureFlags) // FeatureFlagsExtension | undefined
-if (flags && (await flags.getFeatureFlag('beta-ui'))) {
-    /* … */
-}
-```
-
-A token is an implementation-free branded string, so importing it never pulls
-the provider's code into your bundle — each extension stays independently
-tree-shakable and lazily loadable. Use a package-qualified runtime string, such
-as `posthog.featureFlags`, that is globally unique and stable so separately
-compiled scripts resolve the same capability. An extension that provides a
-capability declares its token(s) in `provides`.
-
 ## Utilities
 
 Reusable browser utilities are exposed through `utils/*` subpaths, but they are
 intentionally not re-exported from the package root or a utility barrel. Import
-the exact file you need so lazy extension bundles do not pull in unrelated
-helpers:
+the exact file needed so lazy extension bundles do not pull in unrelated helpers:
 
 ```ts
 import { createLogger } from '@posthog/browser-common/utils/logger'
@@ -145,13 +107,10 @@ import { formDataToQuery } from '@posthog/browser-common/utils/request-utils'
 
 See the **`develop-extension`** skill
 ([`.agents/skills/develop-extension/SKILL.md`](./.agents/skills/develop-extension/SKILL.md))
-for the full guide: the capability cheatsheet, the rules (enrichers are
-synchronous, dispose your disposables, design for asynchronous readiness,
-cross-extension state goes through `getExtension`, not shared storage), and the
-v1 → `Client` porting map.
+for the complete authoring and browser-v1 porting guide.
 
 ## Status
 
-Early and internal. The package currently defines the extension contract, the
-core analytics capability, a shared host runtime, shared lifecycle helpers, and
-directly imported browser utilities under `utils/*` subpaths.
+Early and internal. The package currently defines the extension and client
+contracts, a shared host runtime, lifecycle helpers, and directly imported
+browser utilities under `utils/*` subpaths.

package/dist/client.d.ts

@@ -1,6 +1,40 @@
 import type { Logger } from '@posthog/core';
+import type { Properties } from '@posthog/types';
+import type { Disposable } from './disposable';
 import type { KeyValueStore } from './persistence';
-import type { ExtensionToken } from './token';
+import type { Listener } from './pubsub';
+import type { RemoteConfig } from './types/remote-config';
+/** Recursively marks object properties as readonly while preserving callable values. */
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/** The current session, stamped on events to tie them to a session and a browser tab. */
+export interface SessionContext {
+    /** The stable session identifier attached to events captured during this session. */
+    readonly sessionId: string;
+    /** The logical browser tab/window identifier attached alongside the session id. */
+    readonly windowId: string;
+    /** When the session started, as a Unix timestamp in milliseconds. */
+    readonly sessionStartTimestamp: number;
+}
+/** A captured event, as observed by `onEvent`. */
+export interface CapturedEventInfo {
+    /** The finalized captured event name. */
+    readonly event: string;
+    /** The final event properties after client defaults and dynamic properties are applied. */
+    readonly properties: DeepReadonly<Record<string, unknown>>;
+}
+/** Per-call capture overrides, mirroring the client's public capture options. */
+export interface CaptureOptions {
+    /** Override the event timestamp sent to PostHog. */
+    timestamp?: Date;
+    /** Override the event UUID used for de-duplication. */
+    uuid?: string;
+    /** Person properties to set, emitted as `$set`. */
+    set?: Record<string, unknown>;
+    /** Person properties to set if unset, emitted as `$set_once`. */
+    setOnce?: Record<string, unknown>;
+}
 /** A minimal response from {@link Client.sendRequest}. */
 export interface ApiResponse {
     /** The HTTP status code returned by the transport, or a client-defined best-effort status for sendBeacon sends. */
@@ -34,28 +68,33 @@ export interface SendRequestInit {
     timeoutMs?: number;
 }
 /**
- * The host SDK's capability surface as seen by an extension — the client an
- * extension is handed in `setup`. A conforming host provides it as an adapter
- * over its own internals.
- *
- * Host services that may do I/O are awaitable; a host can complete them
- * synchronously when its underlying implementation supports that. Core
- * analytics behavior is provided separately by the core extension.
+ * The host SDK surface handed to an extension in `setup`. A conforming host
+ * provides it as an adapter over its own analytics, transport, persistence,
+ * event, and remote-config internals.
  */
 export interface Client {
+    /** The id events are currently attributed to. */
+    readonly distinctId: string;
+    /** The anonymous device id carried across identify calls. */
+    readonly anonymousId: string;
+    /** Active group memberships attached to events as `$groups`. */
+    readonly groups: DeepReadonly<Record<string, string>>;
+    /** The current session, created on first read if needed. */
+    readonly session: SessionContext;
+    /** Records an analytics event through the client's normal pipeline. */
+    capture(event: string, properties?: Properties | null, options?: CaptureOptions): Promise<void>;
+    /** Registers a synchronous producer of properties merged into every captured event. */
+    registerDynamicEventProperties(producer: () => Record<string, unknown>): Disposable;
+    /** Fires for every captured event through a deeply readonly view. */
+    readonly onEvent: Listener<CapturedEventInfo>;
+    /** Resolves with the current remote config, awaiting the first outcome when necessary. */
+    getRemoteConfig(): Promise<DeepReadonly<RemoteConfig> | undefined>;
+    /** Fires when server-provided config arrives or changes successfully. */
+    readonly onRemoteConfig: Listener<DeepReadonly<RemoteConfig>>;
     /** Public project token used to authenticate endpoint-specific requests. */
     readonly projectToken: string;
-    /**
-     * Sends a request through the host SDK's transport. The extension owns the
-     * endpoint-specific path, method, authentication shape, body, and headers.
-     */
+    /** Sends a request through the host SDK's transport. */
     sendRequest(path: string, init?: SendRequestInit): Promise<ApiResponse>;
-    /**
-     * Resolves another registered extension by a capability token it provides, or
-     * `undefined` if nothing registered provides it (not installed, or not loaded
-     * yet). Lets one extension use another without importing its implementation.
-     */
-    getExtension<T>(token: ExtensionToken<T>): T | undefined;
     /** Awaitable key-value storage backed by the host client's persistence. */
     readonly kv: KeyValueStore;
     /** Logger that follows the host client's debug/noise policy. */

package/dist/config.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     default: ()=>__WEBPACK_DEFAULT_EXPORT__
 });
-const packageVersion = "0.2.3";
+const packageVersion = "0.2.5";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/config.mjs

@@ -1,4 +1,4 @@
-const packageVersion = "0.2.3";
+const packageVersion = "0.2.5";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/disposable.d.ts

@@ -1,15 +1,7 @@
-/**
- * Something with an async-capable teardown. `dispose` may be async so
- * teardown can do final work — e.g. a last flush of buffered data — that the
- * client can await before it finishes shutting down.
- */
+/** A resource handle with idempotent, best-effort cleanup. */
 export interface Disposable {
-    /**
-     * Release resources owned by this object. Implementations should be
-     * idempotent so callers can safely dispose during both extension teardown
-     * and client shutdown.
-     */
-    dispose(): void | Promise<void>;
+    /** Release resources owned by this object. */
+    dispose(): void;
 }
-/** Invokes teardown at most once and returns its first result to every caller. */
-export declare function createDisposable(dispose: () => void | Promise<void>): Disposable;
+/** Invokes teardown at most once without awaiting Promise results. */
+export declare function createDisposable(dispose: () => void): Disposable;

package/dist/disposable.js

@@ -26,16 +26,16 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     createDisposable: ()=>createDisposable
 });
+const core_namespaceObject = require("@posthog/core");
 function createDisposable(dispose) {
     let active = true;
-    let result;
     return {
         dispose: ()=>{
             if (active) {
                 active = false;
-                result = dispose();
+                const result = dispose();
+                if (result && (0, core_namespaceObject.isFunction)(result.then)) result.then(void 0, ()=>{});
             }
-            return result;
         }
     };
 }

package/dist/disposable.mjs

@@ -1,13 +1,13 @@
+import { isFunction } from "@posthog/core";
 function createDisposable(dispose) {
     let active = true;
-    let result;
     return {
         dispose: ()=>{
             if (active) {
                 active = false;
-                result = dispose();
+                const result = dispose();
+                if (result && isFunction(result.then)) result.then(void 0, ()=>{});
             }
-            return result;
         }
     };
 }

package/dist/extension-runtime.d.ts

@@ -2,33 +2,16 @@ import { type Logger } from '@posthog/core';
 import type { Client } from './client';
 import type { Disposable } from './disposable';
 import type { Extension } from './extension';
-import type { ExtensionToken } from './token';
-/**
- * Shared lifecycle and capability registry for browser extension hosts.
- *
- * Hosts provide the concrete Client adapter while this runtime coordinates
- * names, capability readiness, setup failures, and reverse-order teardown.
- */
+/** Shared setup and lifecycle registry for browser extension hosts. */
 export declare class ExtensionRuntime implements Disposable {
     private readonly _logger;
+    private readonly _client;
     private readonly _extensions;
-    private readonly _registrationOrder;
-    private readonly _providerReservations;
-    private readonly _providers;
-    private _disposePromise;
-    constructor(_logger: Logger);
-    /**
-     * Sets up an extension and publishes its capabilities once setup succeeds.
-     * Names and tokens remain reserved while asynchronous setup is pending.
-     */
-    add(extension: Extension, client: Client): Promise<void>;
-    /** Resolves a capability only after its provider has completed setup. */
-    getExtension<T>(token: ExtensionToken<T>): T | undefined;
-    /** Disposes every registered extension once, in reverse registration order. */
-    dispose(): Promise<void>;
-    private _disposeAll;
-    private _handleSetupFailure;
-    private _disposeRegistration;
-    private _removeRegistration;
-    private _publishRegistration;
+    private _disposed;
+    constructor(_logger: Logger, _client: Client);
+    /** Reserves an extension name and sets it up with the host client adapter. */
+    add(extension: Extension): Promise<void>;
+    /** Releases every registered extension once in reverse registration order without waiting for pending setup. */
+    dispose(): void;
+    private _disposeExtension;
 }

package/dist/extension-runtime.js

@@ -28,77 +28,43 @@ __webpack_require__.d(__webpack_exports__, {
 });
 const core_namespaceObject = require("@posthog/core");
 class ExtensionRuntime {
-    constructor(_logger){
+    constructor(_logger, _client){
         this._logger = _logger;
+        this._client = _client;
         this._extensions = new Map();
-        this._registrationOrder = [];
-        this._providerReservations = new Map();
-        this._providers = new Map();
+        this._disposed = false;
     }
-    async add(extension, client) {
-        if (this._disposePromise) throw new Error('Cannot add an extension to a disposed ExtensionRuntime');
+    async add(extension) {
+        if (this._disposed) throw new Error('Cannot add an extension to a disposed ExtensionRuntime');
         if (this._extensions.has(extension.name)) throw new Error(`Browser extension "${extension.name}" is already registered`);
-        for (const token of extension.provides ?? [])if (this._providerReservations.has(token)) throw new Error(`Browser extension token "${token}" is already registered`);
-        const registered = {
-            extension,
-            setupPromise: Promise.resolve()
-        };
-        this._extensions.set(extension.name, registered);
-        this._registrationOrder.push(registered);
-        for (const token of extension.provides ?? [])this._providerReservations.set(token, registered);
-        let setupResult;
+        this._extensions.set(extension.name, extension);
         try {
-            setupResult = extension.setup(client);
+            const setup = extension.setup(this._client);
+            if (setup) await setup;
         } catch (error) {
-            registered.setupPromise = this._handleSetupFailure(registered, error);
-            return registered.setupPromise;
+            const active = this._extensions.get(extension.name) === extension;
+            if (active) this._extensions.delete(extension.name);
+            this._logger.error(`Failed to set up browser extension "${extension.name}"`, error);
+            if (active) this._disposeExtension(extension);
         }
-        if (setupResult && (0, core_namespaceObject.isFunction)(setupResult.then)) registered.setupPromise = setupResult.then(()=>this._publishRegistration(registered)).catch((error)=>this._handleSetupFailure(registered, error));
-        else this._publishRegistration(registered);
-        return registered.setupPromise;
-    }
-    getExtension(token) {
-        return this._providers.get(token);
     }
     dispose() {
-        if (!this._disposePromise) this._disposePromise = this._disposeAll();
-        return this._disposePromise;
-    }
-    async _disposeAll() {
-        for (const registered of this._registrationOrder.slice().reverse()){
-            await registered.setupPromise;
-            await this._disposeRegistration(registered);
-        }
+        if (this._disposed) return;
+        this._disposed = true;
+        const extensions = Array.from(this._extensions.values()).reverse();
         this._extensions.clear();
-        this._registrationOrder.length = 0;
-        this._providerReservations.clear();
-        this._providers.clear();
+        for (const extension of extensions)this._disposeExtension(extension);
     }
-    async _handleSetupFailure(registered, error) {
-        this._removeRegistration(registered);
-        this._logger.error(`Failed to set up browser extension "${registered.extension.name}"`, error);
-        if (this._disposePromise) return;
-        await this._disposeRegistration(registered);
-        const index = this._registrationOrder.indexOf(registered);
-        if (-1 !== index) this._registrationOrder.splice(index, 1);
-    }
-    _disposeRegistration(registered) {
-        if (!registered.disposalPromise) registered.disposalPromise = Promise.resolve().then(()=>registered.extension.dispose()).catch((error)=>{
-            this._logger.error(`Failed to dispose browser extension "${registered.extension.name}"`, error);
-        });
-        return registered.disposalPromise;
-    }
-    _removeRegistration(registered) {
-        if (this._extensions.get(registered.extension.name) === registered) this._extensions.delete(registered.extension.name);
-        for (const token of registered.extension.provides ?? []){
-            if (this._providerReservations.get(token) === registered) this._providerReservations.delete(token);
-            if (this._providers.get(token) === registered.extension) this._providers.delete(token);
+    _disposeExtension(extension) {
+        try {
+            const result = extension.dispose?.();
+            if (result && (0, core_namespaceObject.isFunction)(result.then)) result.then(void 0, (error)=>{
+                this._logger.error(`Failed to dispose browser extension "${extension.name}"`, error);
+            });
+        } catch (error) {
+            this._logger.error(`Failed to dispose browser extension "${extension.name}"`, error);
         }
     }
-    _publishRegistration(registered) {
-        if (this._disposePromise || this._extensions.get(registered.extension.name) !== registered) return;
-        for (const token of registered.extension.provides ?? [])this._providers.set(token, registered.extension);
-    }
 }
 exports.ExtensionRuntime = __webpack_exports__.ExtensionRuntime;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [

package/dist/extension-runtime.mjs

@@ -1,75 +1,41 @@
 import { isFunction } from "@posthog/core";
 class ExtensionRuntime {
-    constructor(_logger){
+    constructor(_logger, _client){
         this._logger = _logger;
+        this._client = _client;
         this._extensions = new Map();
-        this._registrationOrder = [];
-        this._providerReservations = new Map();
-        this._providers = new Map();
+        this._disposed = false;
     }
-    async add(extension, client) {
-        if (this._disposePromise) throw new Error('Cannot add an extension to a disposed ExtensionRuntime');
+    async add(extension) {
+        if (this._disposed) throw new Error('Cannot add an extension to a disposed ExtensionRuntime');
         if (this._extensions.has(extension.name)) throw new Error(`Browser extension "${extension.name}" is already registered`);
-        for (const token of extension.provides ?? [])if (this._providerReservations.has(token)) throw new Error(`Browser extension token "${token}" is already registered`);
-        const registered = {
-            extension,
-            setupPromise: Promise.resolve()
-        };
-        this._extensions.set(extension.name, registered);
-        this._registrationOrder.push(registered);
-        for (const token of extension.provides ?? [])this._providerReservations.set(token, registered);
-        let setupResult;
+        this._extensions.set(extension.name, extension);
         try {
-            setupResult = extension.setup(client);
+            const setup = extension.setup(this._client);
+            if (setup) await setup;
         } catch (error) {
-            registered.setupPromise = this._handleSetupFailure(registered, error);
-            return registered.setupPromise;
+            const active = this._extensions.get(extension.name) === extension;
+            if (active) this._extensions.delete(extension.name);
+            this._logger.error(`Failed to set up browser extension "${extension.name}"`, error);
+            if (active) this._disposeExtension(extension);
         }
-        if (setupResult && isFunction(setupResult.then)) registered.setupPromise = setupResult.then(()=>this._publishRegistration(registered)).catch((error)=>this._handleSetupFailure(registered, error));
-        else this._publishRegistration(registered);
-        return registered.setupPromise;
-    }
-    getExtension(token) {
-        return this._providers.get(token);
     }
     dispose() {
-        if (!this._disposePromise) this._disposePromise = this._disposeAll();
-        return this._disposePromise;
-    }
-    async _disposeAll() {
-        for (const registered of this._registrationOrder.slice().reverse()){
-            await registered.setupPromise;
-            await this._disposeRegistration(registered);
-        }
+        if (this._disposed) return;
+        this._disposed = true;
+        const extensions = Array.from(this._extensions.values()).reverse();
         this._extensions.clear();
-        this._registrationOrder.length = 0;
-        this._providerReservations.clear();
-        this._providers.clear();
-    }
-    async _handleSetupFailure(registered, error) {
-        this._removeRegistration(registered);
-        this._logger.error(`Failed to set up browser extension "${registered.extension.name}"`, error);
-        if (this._disposePromise) return;
-        await this._disposeRegistration(registered);
-        const index = this._registrationOrder.indexOf(registered);
-        if (-1 !== index) this._registrationOrder.splice(index, 1);
+        for (const extension of extensions)this._disposeExtension(extension);
     }
-    _disposeRegistration(registered) {
-        if (!registered.disposalPromise) registered.disposalPromise = Promise.resolve().then(()=>registered.extension.dispose()).catch((error)=>{
-            this._logger.error(`Failed to dispose browser extension "${registered.extension.name}"`, error);
-        });
-        return registered.disposalPromise;
-    }
-    _removeRegistration(registered) {
-        if (this._extensions.get(registered.extension.name) === registered) this._extensions.delete(registered.extension.name);
-        for (const token of registered.extension.provides ?? []){
-            if (this._providerReservations.get(token) === registered) this._providerReservations.delete(token);
-            if (this._providers.get(token) === registered.extension) this._providers.delete(token);
+    _disposeExtension(extension) {
+        try {
+            const result = extension.dispose?.();
+            if (result && isFunction(result.then)) result.then(void 0, (error)=>{
+                this._logger.error(`Failed to dispose browser extension "${extension.name}"`, error);
+            });
+        } catch (error) {
+            this._logger.error(`Failed to dispose browser extension "${extension.name}"`, error);
         }
     }
-    _publishRegistration(registered) {
-        if (this._disposePromise || this._extensions.get(registered.extension.name) !== registered) return;
-        for (const token of registered.extension.provides ?? [])this._providers.set(token, registered.extension);
-    }
 }
 export { ExtensionRuntime };

package/dist/extension.d.ts

@@ -1,17 +1,13 @@
-import type { Disposable } from './disposable';
 import type { Client } from './client';
-import type { ExtensionToken } from './token';
 /**
- * A shared browser extension. The client calls only two things: `setup(client)`
- * to start it and `dispose()` (from {@link Disposable}) to stop it. Everything
- * an extension consumes flows the other way, through {@link Client}.
+ * A shared browser extension. The client calls `setup(client)` once to start it
+ * and optional `dispose()` once for final best-effort resource cleanup.
+ * Everything an extension consumes flows through {@link Client}.
  *
- * `setup` may be async so an extension can read async-KV state or remote config
- * before it is ready; the client awaits it. `name` is used for de-duplication
- * and diagnostics. The `Disposable`s an extension creates in `setup` —
- * enrichers, event listeners, timers — are its own to release: hold them and
- * dispose them in `dispose`. The host disposes the extension; it does not track
- * the extension's individual subscriptions.
+ * `setup` may be async so an extension can read async KV state or remote config
+ * before it is ready. Async extensions must guard work after each `await` so
+ * cleanup cannot be followed by late listener, timer, or patch installation.
+ * The disposables an extension creates in setup are its own to release.
  *
  * An extension that exposes app-facing controls extends `Extension` with named
  * methods that share its state, e.g.:
@@ -23,23 +19,15 @@ import type { ExtensionToken } from './token';
  *     isActive(): boolean
  * }
  * ```
- *
- * The client still only calls `setup` and `dispose`; the controls are for the
- * application that constructed the extension.
  */
-export interface Extension extends Disposable {
+export interface Extension {
     /** Stable extension name used for diagnostics and de-duplication within a client instance. */
     readonly name: string;
-    /**
-     * Capability tokens this extension answers to, so others can resolve it via
-     * `client.getExtension(token)`. The extension must be assignable to each
-     * token's provided type. Most extensions provide nothing.
-     */
-    readonly provides?: readonly ExtensionToken<unknown>[];
     /**
      * Start the extension with the host client's capability surface. Called once
-     * after construction; return a promise when setup needs asynchronous state
-     * such as persisted data or remote config.
+     * after construction; return a promise when setup needs asynchronous state.
      */
     setup(client: Client): void | Promise<void>;
+    /** Release final resources synchronously. Feature-level start/stop remains extension-owned. */
+    dispose?(): void;
 }

package/dist/index.d.ts

@@ -3,12 +3,9 @@
  * clients.
  */
 export type { Extension } from './extension';
-export { CoreExtension } from './core-extension';
-export type { DeepReadonly, SessionContext, NewSessionReason, NewSessionInfo, CapturedEventInfo, CaptureOptions, } from './core-extension';
 export * from './types';
 export { createDisposable, type Disposable } from './disposable';
-export type { ExtensionToken } from './token';
 export type { Listener } from './pubsub';
 export { Publisher } from './pubsub';
-export type { Client, ApiResponse, RequestTarget, RequestTransport, SendRequestInit } from './client';
+export type { Client, DeepReadonly, SessionContext, CapturedEventInfo, CaptureOptions, ApiResponse, RequestTarget, RequestTransport, SendRequestInit, } from './client';
 export type { KeyValueStore } from './persistence';

package/dist/index.js

@@ -1,8 +1,5 @@
 "use strict";
 var __webpack_modules__ = {
-    "./core-extension": function(module) {
-        module.exports = require("./core-extension.js");
-    },
     "./disposable": function(module) {
         module.exports = require("./disposable.js");
     },
@@ -57,30 +54,25 @@ var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
     __webpack_require__.d(__webpack_exports__, {
-        CoreExtension: ()=>_core_extension__WEBPACK_IMPORTED_MODULE_0__.CoreExtension,
-        Publisher: ()=>_pubsub__WEBPACK_IMPORTED_MODULE_3__.Publisher,
-        createDisposable: ()=>_disposable__WEBPACK_IMPORTED_MODULE_2__.createDisposable
+        Publisher: ()=>_pubsub__WEBPACK_IMPORTED_MODULE_2__.Publisher,
+        createDisposable: ()=>_disposable__WEBPACK_IMPORTED_MODULE_1__.createDisposable
     });
-    var _core_extension__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__("./core-extension");
-    var _types__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__("./types");
+    var _types__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__("./types");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_1__)if ([
-        "createDisposable",
+    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_0__)if ([
+        "Publisher",
         "default",
-        "CoreExtension",
-        "Publisher"
+        "createDisposable"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _types__WEBPACK_IMPORTED_MODULE_1__[key];
+        return _types__WEBPACK_IMPORTED_MODULE_0__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _disposable__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__("./disposable");
-    var _pubsub__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__("./pubsub");
+    var _disposable__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__("./disposable");
+    var _pubsub__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__("./pubsub");
 })();
-exports.CoreExtension = __webpack_exports__.CoreExtension;
 exports.Publisher = __webpack_exports__.Publisher;
 exports.createDisposable = __webpack_exports__.createDisposable;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "CoreExtension",
     "Publisher",
     "createDisposable"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];

package/dist/index.mjs

@@ -1,5 +1,4 @@
-import { CoreExtension } from "./core-extension.mjs";
 import { createDisposable } from "./disposable.mjs";
 import { Publisher } from "./pubsub.mjs";
 export * from "./types/index.mjs";
-export { CoreExtension, Publisher, createDisposable };
+export { Publisher, createDisposable };

package/dist/utils/prototype-utils.js

@@ -37,15 +37,26 @@ function getNativeImplementation(name, assignableWindow) {
     let impl = assignableWindow[name];
     if ((0, core_namespaceObject.isNativeFunction)(impl) && !(0, external_type_utils_js_namespaceObject.isAngularZonePresent)()) return cachedImplementations[name] = impl.bind(assignableWindow);
     const document = assignableWindow.document;
-    if (document && (0, core_namespaceObject.isFunction)(document.createElement)) try {
-        const sandbox = document.createElement('iframe');
-        sandbox.hidden = true;
-        document.head.appendChild(sandbox);
-        const contentWindow = sandbox.contentWindow;
-        if (contentWindow && contentWindow[name]) impl = contentWindow[name];
-        document.head.removeChild(sandbox);
-    } catch (e) {
-        external_logger_js_namespaceObject.logger.warn(`Could not create sandbox iframe for ${name} check, bailing to assignableWindow.${name}: `, e);
+    if (document && (0, core_namespaceObject.isFunction)(document.createElement)) {
+        let sandbox;
+        let keepSandboxAttached = false;
+        try {
+            sandbox = document.createElement('iframe');
+            sandbox.hidden = true;
+            document.head.appendChild(sandbox);
+            const contentWindow = sandbox.contentWindow;
+            if (contentWindow && contentWindow[name]) {
+                impl = contentWindow[name];
+                if ('MutationObserver' === name && (0, core_namespaceObject.isWebKit)(assignableWindow.navigator?.userAgent ?? '')) {
+                    sandbox.classList.add('rr-block', 'ph-no-capture');
+                    keepSandboxAttached = true;
+                }
+            }
+        } catch (e) {
+            external_logger_js_namespaceObject.logger.warn(`Could not create sandbox iframe for ${name} check, bailing to assignableWindow.${name}: `, e);
+        } finally{
+            if (!keepSandboxAttached && sandbox?.parentNode) sandbox.parentNode.removeChild(sandbox);
+        }
     }
     if (!impl || !(0, core_namespaceObject.isFunction)(impl)) return impl;
     return cachedImplementations[name] = impl.bind(assignableWindow);

package/dist/utils/prototype-utils.mjs

@@ -1,4 +1,4 @@
-import { isFunction, isNativeFunction } from "@posthog/core";
+import { isFunction, isNativeFunction, isWebKit } from "@posthog/core";
 import { logger } from "./logger.mjs";
 import { isAngularZonePresent } from "./type-utils.mjs";
 const cachedImplementations = {};
@@ -8,15 +8,26 @@ function getNativeImplementation(name, assignableWindow) {
     let impl = assignableWindow[name];
     if (isNativeFunction(impl) && !isAngularZonePresent()) return cachedImplementations[name] = impl.bind(assignableWindow);
     const document = assignableWindow.document;
-    if (document && isFunction(document.createElement)) try {
-        const sandbox = document.createElement('iframe');
-        sandbox.hidden = true;
-        document.head.appendChild(sandbox);
-        const contentWindow = sandbox.contentWindow;
-        if (contentWindow && contentWindow[name]) impl = contentWindow[name];
-        document.head.removeChild(sandbox);
-    } catch (e) {
-        logger.warn(`Could not create sandbox iframe for ${name} check, bailing to assignableWindow.${name}: `, e);
+    if (document && isFunction(document.createElement)) {
+        let sandbox;
+        let keepSandboxAttached = false;
+        try {
+            sandbox = document.createElement('iframe');
+            sandbox.hidden = true;
+            document.head.appendChild(sandbox);
+            const contentWindow = sandbox.contentWindow;
+            if (contentWindow && contentWindow[name]) {
+                impl = contentWindow[name];
+                if ('MutationObserver' === name && isWebKit(assignableWindow.navigator?.userAgent ?? '')) {
+                    sandbox.classList.add('rr-block', 'ph-no-capture');
+                    keepSandboxAttached = true;
+                }
+            }
+        } catch (e) {
+            logger.warn(`Could not create sandbox iframe for ${name} check, bailing to assignableWindow.${name}: `, e);
+        } finally{
+            if (!keepSandboxAttached && sandbox?.parentNode) sandbox.parentNode.removeChild(sandbox);
+        }
     }
     if (!impl || !isFunction(impl)) return impl;
     return cachedImplementations[name] = impl.bind(assignableWindow);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/browser-common",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Internal shared browser utilities and extension primitives for PostHog Browser SDKs",
   "license": "MIT",
   "repository": {
@@ -65,13 +65,14 @@
     }
   },
   "dependencies": {
-    "@posthog/core": "^1.45.1",
-    "@posthog/types": "^1.398.0"
+    "@posthog/core": "^1.45.3",
+    "@posthog/types": "^1.399.0"
   },
   "devDependencies": {
     "@rslib/core": "0.10.6",
     "@types/jest": "^29.5.14",
     "jest": "29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "ts-jest": "29.4.11",
     "typescript": "5.8.2",
     "@posthog-tooling/tsconfig-base": "1.1.1"

package/dist/core-extension.d.ts

@@ -1,80 +0,0 @@
-import type { JsonRecord, Properties } from '@posthog/types';
-import type { Disposable } from './disposable';
-import type { Extension } from './extension';
-import type { Listener } from './pubsub';
-import type { RemoteConfig } from './types/remote-config';
-import type { ExtensionToken } from './token';
-/** Recursively marks object properties as readonly while preserving callable values. */
-export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
-    readonly [K in keyof T]: DeepReadonly<T[K]>;
-} : T;
-/** The current session, stamped on events to tie them to a session and a browser tab. */
-export interface SessionContext {
-    /** The stable session identifier attached to events captured during this session. */
-    readonly sessionId: string;
-    /** The logical browser tab/window identifier attached alongside the session id. */
-    readonly windowId: string;
-    /** When the session started, as a Unix timestamp in milliseconds. */
-    readonly sessionStartTimestamp: number;
-}
-/** Why a new session started (a `reset` also starts a new session). */
-export type NewSessionReason = 'initial' | 'reset' | 'idleTimeout' | 'maxLength' | 'crossTabAdoption';
-/** Details emitted when the client starts or adopts a new session. */
-export interface NewSessionInfo extends SessionContext {
-    /** The condition that caused this session to begin. */
-    readonly reason: NewSessionReason;
-}
-/** A captured event, as observed by `onEvent`. */
-export interface CapturedEventInfo {
-    /** The finalized captured event name. */
-    readonly event: string;
-    /** The final event properties after client defaults and dynamic properties are applied. */
-    readonly properties: DeepReadonly<JsonRecord>;
-}
-/** Per-call capture overrides, mirroring the client's public capture options. */
-export interface CaptureOptions {
-    /** Override the event timestamp sent to PostHog. */
-    timestamp?: Date;
-    /** Override the event UUID used for de-duplication. */
-    uuid?: string;
-    /** Person properties to set, emitted as `$set`. */
-    set?: Record<string, unknown>;
-    /** Person properties to set if unset, emitted as `$set_once`. */
-    setOnce?: Record<string, unknown>;
-}
-/**
- * The host SDK's core analytics behavior, exposed as an extension so shared
- * extensions can depend on the event pipeline without depending on a concrete
- * PostHog client implementation.
- */
-export interface CoreExtension extends Extension {
-    /** The id events are currently attributed to. */
-    readonly distinctId: string;
-    /** The anonymous device id carried across identify calls. */
-    readonly anonymousId: string;
-    /** Active group memberships attached to events as `$groups`. */
-    readonly groups: DeepReadonly<Record<string, string>>;
-    /** The current session, created on first read if needed. */
-    readonly session: SessionContext;
-    /** Records an analytics event through the client's normal pipeline. */
-    capture(event: string, properties?: Properties | null, options?: CaptureOptions): Promise<void>;
-    /**
-     * Registers a producer of properties merged into every captured event.
-     * The producer runs inline while the event is built and must be synchronous.
-     */
-    registerDynamicEventProperties(producer: () => Record<string, unknown>): Disposable;
-    /** Fires for every captured event through a deeply readonly view. */
-    readonly onEvent: Listener<CapturedEventInfo>;
-    /** Fires when a new session starts, including on reset. */
-    readonly onNewSession: Listener<NewSessionInfo>;
-    /**
-     * Resolves with the current remote config, awaiting the first outcome when
-     * necessary. A failed outcome resolves to `undefined`; later successful
-     * changes are published through `onRemoteConfig`.
-     */
-    getRemoteConfig(): Promise<DeepReadonly<RemoteConfig> | undefined>;
-    /** Fires through a deeply readonly view when server-provided config arrives or changes successfully. */
-    readonly onRemoteConfig: Listener<DeepReadonly<RemoteConfig>>;
-}
-/** Capability token used to resolve the host SDK's core analytics extension. */
-export declare const CoreExtension: ExtensionToken<CoreExtension>;

package/dist/core-extension.js

@@ -1,36 +0,0 @@
-"use strict";
-var __webpack_require__ = {};
-(()=>{
-    __webpack_require__.d = (exports1, definition)=>{
-        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
-            enumerable: true,
-            get: definition[key]
-        });
-    };
-})();
-(()=>{
-    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
-})();
-(()=>{
-    __webpack_require__.r = (exports1)=>{
-        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
-            value: 'Module'
-        });
-        Object.defineProperty(exports1, '__esModule', {
-            value: true
-        });
-    };
-})();
-var __webpack_exports__ = {};
-__webpack_require__.r(__webpack_exports__);
-__webpack_require__.d(__webpack_exports__, {
-    CoreExtension: ()=>CoreExtension
-});
-const CoreExtension = 'posthog.core';
-exports.CoreExtension = __webpack_exports__.CoreExtension;
-for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "CoreExtension"
-].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
-Object.defineProperty(exports, '__esModule', {
-    value: true
-});

package/dist/core-extension.mjs

@@ -1,2 +0,0 @@
-const CoreExtension = 'posthog.core';
-export { CoreExtension };

package/dist/token.d.ts

@@ -1,22 +0,0 @@
-/** Phantom brand carrying the capability type without emitting runtime code. */
-declare const extensionTokenType: unique symbol;
-/**
- * A typed, implementation-free string for resolving an extension that provides
- * a capability. Declared as a shared `const` next to the providing extension's
- * interface:
- *
- * ```ts
- * export interface FeatureFlagsExtension extends Extension { … }
- * export const FeatureFlags = 'posthog.featureFlags' as ExtensionToken<FeatureFlagsExtension>
- * ```
- *
- * A token holds no implementation, so importing one never pulls the provider's
- * code into the consumer's bundle. Its generic brand lets `getExtension` infer
- * the provided type, while its runtime string value remains stable across
- * independently compiled scripts. Token strings must be globally unique and
- * stable for the lifetime of the capability contract.
- */
-export type ExtensionToken<T> = string & {
-    readonly [extensionTokenType]: T;
-};
-export {};

package/dist/token.js

@@ -1,18 +0,0 @@
-"use strict";
-var __webpack_require__ = {};
-(()=>{
-    __webpack_require__.r = (exports1)=>{
-        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
-            value: 'Module'
-        });
-        Object.defineProperty(exports1, '__esModule', {
-            value: true
-        });
-    };
-})();
-var __webpack_exports__ = {};
-__webpack_require__.r(__webpack_exports__);
-for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
-Object.defineProperty(exports, '__esModule', {
-    value: true
-});