@nominalso/vibe-bridge 0.3.0 → 0.4.0

package/AGENTS.md

@@ -4,7 +4,7 @@ Instructions for AI coding agents (Claude Code, Cursor, Copilot, Lovable, etc.)
 
 ## What this package is
 
-`@nominalso/vibe-bridge` is the **iframe-side** SDK for a Nominal Vibe App — a standalone browser app (often built with Lovable) embedded in the Nominal platform via a cross-origin `<iframe>`. The app cannot call Nominal APIs directly; it talks to its Nominal host over a typed `postMessage` bridge. This package is that bridge. It is **browser-only** (uses `window`, `postMessage`, `crypto.randomUUID`) and has **zero runtime dependencies**.
+`@nominalso/vibe-bridge` is the **iframe-side** SDK for a Nominal Vibe App — a standalone browser app (often built with Lovable) embedded in the Nominal platform via a cross-origin `<iframe>`. The app cannot call Nominal APIs directly; it talks to its Nominal host over a typed `postMessage` bridge. This package is that bridge. It is **browser-only** (uses `window`, `postMessage`, `crypto.randomUUID`) and bundles **`posthog-js`** (its only runtime dependency) for host-enabled in-iframe session recording.
 
 The host counterpart is `@nominalso/vibe-host` (used by Nominal's own app — you do not install it in a Vibe App).
 
@@ -37,13 +37,16 @@ bridge.destroy() // on unmount
 - `upload(file: File, { entityType, entityId?, onProgress? }): Promise<{ attachmentId, name }>`.
 - `navigate`/`navigateTo`/`refresh` and `ui.setSideNav`/`ui.switchSubsidiary` — drive the host's chrome (router, side nav, subsidiary switcher); `invalidateCache(...)` busts host caches.
 - `reportSubroute(subroute, { replace? })`, `onSubrouteRequest(cb): () => void` — usually unnecessary; standard SPA navigation is auto-tracked.
+- `track(event: string, properties?): void` — capture a custom PostHog event. **No-op unless the host enabled recording** (see below); always safe to call.
 - `destroy()`.
 
+**Session recording (PostHog).** The bridge bundles `posthog-js` and, on `connect()`, initializes it **only if the host sent a `posthog` block with `enabled: true`** (cross-origin replay stitched into the host's recording, masking mirroring nom-ui — inputs unmasked, password fields masked — attributed to the same person via `identify`). If the host sends nothing, the bridge initializes nothing — `enabled` is the kill-switch. You configure nothing in the app; just call `track(...)` for custom events. If you serve the app yourself, allow `connect-src https://*.i.posthog.com https://us-assets.i.posthog.com` and `worker-src blob:` in its CSP (no `script-src` entry — posthog is bundled, not from a CDN).
+
 A failed operation throws a `BridgeError` (`extends Error`) with a machine-readable `code` (`'RATE_LIMITED'`, `'FILE_TOO_LARGE'`, `'TIMEOUT'`, …); branch on `err.code` rather than the message. A failed Nominal API call throws the `HttpBridgeError` subtype (`code: 'REQUEST_FAILED'`) carrying the HTTP `status` — branch on `err.status` (e.g. `404`).
 
-Exported values/types: `VibeAppBridge`, `BridgeError`, `BRIDGE_VERSION`, and types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
+Exported values/types: `VibeAppBridge`, `BridgeError`, `HttpBridgeError`, `BRIDGE_VERSION`, and types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `PostHogContext`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
 
-`ContextPayload` shape: `{ tenant, subsidiaryId, subsidiaries: { id, displayName }[], user: { id, displayName }, subroute?, lastClosedPeriodSlug?, hostVersion }`.
+`ContextPayload` shape: `{ tenant, subsidiaryId, subsidiaries: { id, displayName }[], user: { id, displayName }, subroute?, lastClosedPeriodSlug?, posthog?: { token, apiHost, distinctId, enabled }, hostVersion }`. The `posthog` block is supplied by the host only when recording is on.
 
 The full method/operation list is in `README.md` ("Operation catalog") and in `docs/data-fetching.md`. The detailed wire-up guides are in `docs/`.
 

package/README.md

@@ -10,7 +10,7 @@ Iframe-side SDK for building **Nominal Vibe Apps** — standalone web apps (typi
 npm install @nominalso/vibe-bridge
 ```
 
-Zero runtime dependencies. Ships ESM + CJS and self-contained TypeScript types.
+Bundles [`posthog-js`](https://posthog.com/docs/libraries/js) (its only runtime dependency) so the host can enable in-iframe session recording — see [Session recording & custom events](#session-recording--custom-events). Ships ESM + CJS and self-contained TypeScript types.
 
 ## Quickstart
 
@@ -118,9 +118,31 @@ Uploads a `File` through the host (converts to `ArrayBuffer` first — sandboxed
 
 Removes listeners, rejects pending requests, and restores patched history methods. Call on unmount.
 
+### Session recording & custom events
+
+The cross-origin iframe is invisible to the host's own session replay (same-origin policy), so the bridge bundles `posthog-js` and initializes it **itself** — but only when the host opts in. On `connect()`, if the resolved context carries a `posthog` block with `enabled: true`, the bridge:
+
+- inits `posthog-js` with `recordCrossOriginIframes: true` (so your replay is **stitched into the host's recording**) and masking that mirrors nom-ui — `maskAllInputs: false` with `maskInputOptions: { password: true }` (inputs unmasked for richer insight, password fields kept masked);
+- calls `identify()` with the host-resolved `distinctId`, so the recording and your events attribute to the **same PostHog person** as nom-ui;
+- if the host also passes its `sessionId` (its `posthog.get_session_id()`), seeds it via `bootstrap.sessionID` so `track()` events share the host's **`$session_id`** and line up with the stitched replay.
+
+The host is the single source of truth. **If it sends no `posthog` block (older host, or recording disabled for this env/app), the bridge initializes nothing** — `enabled` is the kill-switch even though `posthog-js` is bundled. You configure nothing in the app.
+
+#### `track(event, properties?)`
+
+Capture a custom product event. No-op until `connect()` has resolved with PostHog enabled by the host — so it's always safe to call.
+
+```ts
+bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+```
+
+Namespace your events (e.g. `vibe:<slug>:<action>`) so they stay filterable from the host's own events. Events are sent directly from the iframe's PostHog instance and tie to the same person via `identify()`. By default they carry the iframe instance's `$session_id`; when the host supplies its `sessionId` in the posthog context, the bridge seeds it so events share the host's `$session_id` and correlate with the stitched replay (best-effort — a one-time seed at connect, so a later host-session rotation can diverge).
+
+> **App-side CSP.** Whoever serves your app must allow, on the app's own origin, `connect-src https://*.i.posthog.com https://us-assets.i.posthog.com` and `worker-src blob:` (recording runs in a web worker). No `script-src` entry is needed — `posthog-js` is bundled into your app via the bridge, not loaded from a CDN.
+
 ### Exports
 
-`VibeAppBridge`, `BridgeError`, `BRIDGE_VERSION`, and the types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
+`VibeAppBridge`, `BridgeError`, `HttpBridgeError`, `BRIDGE_VERSION`, and the types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `PostHogContext`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
 
 ## Common recipes
 

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -28,7 +38,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -101,6 +111,9 @@ function isOriginAllowed(origin, allowlist, { allowPatterns }) {
   return false;
 }
 
+// src/VibeAppBridge.ts
+var import_posthog_js = __toESM(require("posthog-js"), 1);
+
 // src/data-methods.ts
 var BridgeDataMethods = class {
   // ---------------------------------------------------------------------------
@@ -418,6 +431,14 @@ function resolveRequestTimeout(type, requestTimeout) {
 }
 
 // src/VibeAppBridge.ts
+function resolvePosthog(mod) {
+  let candidate = mod;
+  while (candidate && typeof candidate.init !== "function" && candidate.default) {
+    candidate = candidate.default;
+  }
+  return candidate;
+}
+var posthog = resolvePosthog(import_posthog_js.default);
 var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
 var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
 function isPreviewSelfHost(hostname) {
@@ -481,6 +502,12 @@ var VibeAppBridge = class extends BridgeDataMethods {
     super();
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.context = null;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    this.posthogInitialized = false;
     this.connectPromise = null;
     this.connectPollInterval = null;
     this.connectTimeout = null;
@@ -611,6 +638,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         console.log(
           `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
         );
+        this.initPostHog(ctx);
         const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
         if (initialSubroute && initialSubroute !== "/") {
           this.withSubrouteSuppressed(() => {
@@ -715,6 +743,34 @@ var VibeAppBridge = class extends BridgeDataMethods {
   invalidateCache(payload) {
     return this.request("INVALIDATE_CACHE", payload);
   }
+  /**
+   * Captures a custom product event from inside the Vibe App, attributed to the
+   * same PostHog person as the host (via the `distinctId` the host supplied at
+   * connect).
+   *
+   * **No-op until {@link connect} has resolved with PostHog enabled by the
+   * host** — if the host didn't send a `posthog` block (older host, or recording
+   * disabled for this env/app), nothing is sent. App authors don't import
+   * `posthog-js` themselves; this is the supported event surface.
+   *
+   * The event is sent **directly** from the iframe's own PostHog instance (only
+   * the session *recording* is forwarded to the parent), so it carries the
+   * iframe instance's `$session_id` rather than the host's — events tie to the
+   * same person, but cross-boundary event↔replay timeline correlation is a known
+   * limitation.
+   *
+   * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+   *   keeps them filterable from the host's own events.
+   * @param properties Optional event properties.
+   * @example
+   * ```ts
+   * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+   * ```
+   */
+  track(event, properties) {
+    if (!this.posthogInitialized) return;
+    posthog.capture(event, properties);
+  }
   destroy() {
     this.teardownNavigationTracking();
     this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
@@ -725,6 +781,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
     }
     this.pendingRequests.clear();
     this.context = null;
+    this.posthogInitialized = false;
     this.connectPromise = null;
     this.onContextReceived = null;
     this.onContextError = null;
@@ -742,6 +799,59 @@ var VibeAppBridge = class extends BridgeDataMethods {
     }
     this.connectPollIds.clear();
   }
+  /**
+   * Initializes PostHog session recording + analytics from the host-supplied
+   * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+   *
+   * The host is the single source of truth: when it sends no `posthog` block
+   * (older nom-ui, or recording disabled for this env/app) or `enabled: false`,
+   * this does nothing — `enabled` is the kill-switch even though `posthog-js` is
+   * bundled into the bridge. Cross-origin replay needs `recordCrossOriginIframes`
+   * on both sides so the parent receives the iframe's rrweb frames into one
+   * stitched recording, and `identify()` ties the iframe's recording + events to
+   * the same person as the host. Wrapped in try/catch so a PostHog failure is
+   * best-effort and never blocks `connect()`.
+   */
+  initPostHog(ctx) {
+    const config = ctx.posthog;
+    if (!config?.enabled) return;
+    if (this.posthogInitialized) return;
+    if (typeof window === "undefined") return;
+    if (!config.token || !config.apiHost || !config.distinctId) {
+      console.warn(
+        "[vibe-bridge] PostHog enabled but token/apiHost/distinctId missing \u2014 skipping init."
+      );
+      return;
+    }
+    try {
+      posthog.init(config.token, {
+        api_host: config.apiHost,
+        // absolute ingestion host, NOT a relative /ingest proxy
+        person_profiles: "identified_only",
+        capture_pageview: false,
+        // the host owns pageviews; don't double-count
+        autocapture: false,
+        // opt-in events only, via track()
+        // Seed the host's session id so track() events share the host's
+        // $session_id and line up with the stitched replay. Replay stitching
+        // itself does not depend on this (recordCrossOriginIframes handles it).
+        ...config.sessionId ? { bootstrap: { sessionID: config.sessionId } } : {},
+        session_recording: {
+          recordCrossOriginIframes: true,
+          // REQUIRED so the parent receives our rrweb frames
+          // Mirror nom-ui's posture (PostHogProvider.tsx): unmask inputs for
+          // richer insight, but keep password fields masked.
+          maskAllInputs: false,
+          maskInputOptions: { password: true }
+        }
+      });
+      posthog.identify(config.distinctId);
+      this.posthogInitialized = true;
+      console.log("[vibe-bridge] PostHog session recording initialized");
+    } catch (err) {
+      console.warn("[vibe-bridge] PostHog init failed \u2014 continuing without recording.", err);
+    }
+  }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
    * auto-detect SPA navigation and report it to the host. Called after

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.3.0";
+var version = "0.4.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3182,6 +3182,54 @@ interface BridgeSubsidiary {
     id: number;
     displayName: string;
 }
+/**
+ * PostHog configuration the host supplies so the iframe can record a session
+ * replay (stitched into the host's recording via `recordCrossOriginIframes`)
+ * and emit custom events, all attributed to the **same PostHog person** as
+ * nom-ui.
+ *
+ * The host (nom-ui) is the single source of truth for these values — it knows
+ * the project key, the env-aware ingestion host, and the resolved person — and
+ * delivers them over the bridge so the iframe never hardcodes any of it. When
+ * the host omits the {@link ContextPayload.posthog} block entirely (older host,
+ * or recording disabled for this env/app), the bridge initializes nothing.
+ */
+interface PostHogContext {
+    /** Project API key — the same PostHog project the host (nom-ui) uses. */
+    token: string;
+    /**
+     * **Absolute** ingestion host, e.g. `"https://us.i.posthog.com"`.
+     *
+     * Must NOT be the host's relative `/ingest` reverse-proxy path: a relative
+     * path resolves against the iframe's *own* (cross-origin) host and 404s.
+     */
+    apiHost: string;
+    /**
+     * Host-resolved PostHog distinct id. The bridge calls `identify()` with it so
+     * the iframe's recording and events attribute to the same person as the host.
+     */
+    distinctId: string;
+    /**
+     * **Optional.** The host's current PostHog session id (from
+     * `posthog.get_session_id()`). When provided, the bridge seeds it as the
+     * iframe instance's session via `bootstrap.sessionID`, so custom events from
+     * `bridge.track()` share the **same `$session_id`** as the host — letting them
+     * line up with the stitched session replay on one timeline.
+     *
+     * Not needed for *replay* stitching itself (that works via
+     * `recordCrossOriginIframes` on both sides regardless). Must be a valid UUID
+     * v7 — PostHog session ids already are. It is a one-time seed at connect, so
+     * if the host's session later rotates the two can diverge; alignment is
+     * best-effort for the session in progress.
+     */
+    sessionId?: string;
+    /**
+     * Master switch, env- and/or app-gated by the host. The bridge only calls
+     * `posthog.init()` when this is `true`; it stays the kill-switch even though
+     * `posthog-js` is bundled into the bridge.
+     */
+    enabled: boolean;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3194,6 +3242,13 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
+    /**
+     * PostHog config for in-iframe session recording + custom events. **Absent
+     * when recording is off** (older host, or disabled for this env/app), in which
+     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
+     * compatible.
+     */
+    posthog?: PostHogContext;
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
@@ -3731,6 +3786,12 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    private posthogInitialized;
     private connectPromise;
     private connectPollInterval;
     private connectTimeout;
@@ -3841,8 +3902,47 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     invalidateCache(payload: InvalidateCachePayload): Promise<InvalidateResult>;
+    /**
+     * Captures a custom product event from inside the Vibe App, attributed to the
+     * same PostHog person as the host (via the `distinctId` the host supplied at
+     * connect).
+     *
+     * **No-op until {@link connect} has resolved with PostHog enabled by the
+     * host** — if the host didn't send a `posthog` block (older host, or recording
+     * disabled for this env/app), nothing is sent. App authors don't import
+     * `posthog-js` themselves; this is the supported event surface.
+     *
+     * The event is sent **directly** from the iframe's own PostHog instance (only
+     * the session *recording* is forwarded to the parent), so it carries the
+     * iframe instance's `$session_id` rather than the host's — events tie to the
+     * same person, but cross-boundary event↔replay timeline correlation is a known
+     * limitation.
+     *
+     * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+     *   keeps them filterable from the host's own events.
+     * @param properties Optional event properties.
+     * @example
+     * ```ts
+     * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+     * ```
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
     destroy(): void;
     private stopConnectPolling;
+    /**
+     * Initializes PostHog session recording + analytics from the host-supplied
+     * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `posthog` block
+     * (older nom-ui, or recording disabled for this env/app) or `enabled: false`,
+     * this does nothing — `enabled` is the kill-switch even though `posthog-js` is
+     * bundled into the bridge. Cross-origin replay needs `recordCrossOriginIframes`
+     * on both sides so the parent receives the iframe's rrweb frames into one
+     * stitched recording, and `identify()` ties the iframe's recording + events to
+     * the same person as the host. Wrapped in try/catch so a PostHog failure is
+     * best-effort and never blocks `connect()`.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3878,4 +3978,4 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private handleProgress;
 }
 
-export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };
+export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type PostHogContext, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-var version = "0.3.0";
+var version = "0.4.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3182,6 +3182,54 @@ interface BridgeSubsidiary {
     id: number;
     displayName: string;
 }
+/**
+ * PostHog configuration the host supplies so the iframe can record a session
+ * replay (stitched into the host's recording via `recordCrossOriginIframes`)
+ * and emit custom events, all attributed to the **same PostHog person** as
+ * nom-ui.
+ *
+ * The host (nom-ui) is the single source of truth for these values — it knows
+ * the project key, the env-aware ingestion host, and the resolved person — and
+ * delivers them over the bridge so the iframe never hardcodes any of it. When
+ * the host omits the {@link ContextPayload.posthog} block entirely (older host,
+ * or recording disabled for this env/app), the bridge initializes nothing.
+ */
+interface PostHogContext {
+    /** Project API key — the same PostHog project the host (nom-ui) uses. */
+    token: string;
+    /**
+     * **Absolute** ingestion host, e.g. `"https://us.i.posthog.com"`.
+     *
+     * Must NOT be the host's relative `/ingest` reverse-proxy path: a relative
+     * path resolves against the iframe's *own* (cross-origin) host and 404s.
+     */
+    apiHost: string;
+    /**
+     * Host-resolved PostHog distinct id. The bridge calls `identify()` with it so
+     * the iframe's recording and events attribute to the same person as the host.
+     */
+    distinctId: string;
+    /**
+     * **Optional.** The host's current PostHog session id (from
+     * `posthog.get_session_id()`). When provided, the bridge seeds it as the
+     * iframe instance's session via `bootstrap.sessionID`, so custom events from
+     * `bridge.track()` share the **same `$session_id`** as the host — letting them
+     * line up with the stitched session replay on one timeline.
+     *
+     * Not needed for *replay* stitching itself (that works via
+     * `recordCrossOriginIframes` on both sides regardless). Must be a valid UUID
+     * v7 — PostHog session ids already are. It is a one-time seed at connect, so
+     * if the host's session later rotates the two can diverge; alignment is
+     * best-effort for the session in progress.
+     */
+    sessionId?: string;
+    /**
+     * Master switch, env- and/or app-gated by the host. The bridge only calls
+     * `posthog.init()` when this is `true`; it stays the kill-switch even though
+     * `posthog-js` is bundled into the bridge.
+     */
+    enabled: boolean;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3194,6 +3242,13 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
+    /**
+     * PostHog config for in-iframe session recording + custom events. **Absent
+     * when recording is off** (older host, or disabled for this env/app), in which
+     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
+     * compatible.
+     */
+    posthog?: PostHogContext;
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
@@ -3731,6 +3786,12 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    private posthogInitialized;
     private connectPromise;
     private connectPollInterval;
     private connectTimeout;
@@ -3841,8 +3902,47 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     invalidateCache(payload: InvalidateCachePayload): Promise<InvalidateResult>;
+    /**
+     * Captures a custom product event from inside the Vibe App, attributed to the
+     * same PostHog person as the host (via the `distinctId` the host supplied at
+     * connect).
+     *
+     * **No-op until {@link connect} has resolved with PostHog enabled by the
+     * host** — if the host didn't send a `posthog` block (older host, or recording
+     * disabled for this env/app), nothing is sent. App authors don't import
+     * `posthog-js` themselves; this is the supported event surface.
+     *
+     * The event is sent **directly** from the iframe's own PostHog instance (only
+     * the session *recording* is forwarded to the parent), so it carries the
+     * iframe instance's `$session_id` rather than the host's — events tie to the
+     * same person, but cross-boundary event↔replay timeline correlation is a known
+     * limitation.
+     *
+     * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+     *   keeps them filterable from the host's own events.
+     * @param properties Optional event properties.
+     * @example
+     * ```ts
+     * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+     * ```
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
     destroy(): void;
     private stopConnectPolling;
+    /**
+     * Initializes PostHog session recording + analytics from the host-supplied
+     * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `posthog` block
+     * (older nom-ui, or recording disabled for this env/app) or `enabled: false`,
+     * this does nothing — `enabled` is the kill-switch even though `posthog-js` is
+     * bundled into the bridge. Cross-origin replay needs `recordCrossOriginIframes`
+     * on both sides so the parent receives the iframe's rrweb frames into one
+     * stitched recording, and `identify()` ties the iframe's recording + events to
+     * the same person as the host. Wrapped in try/catch so a PostHog failure is
+     * best-effort and never blocks `connect()`.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3878,4 +3978,4 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private handleProgress;
 }
 
-export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };
+export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type PostHogContext, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -72,6 +72,9 @@ function isOriginAllowed(origin, allowlist, { allowPatterns }) {
   return false;
 }
 
+// src/VibeAppBridge.ts
+import posthogDefault from "posthog-js";
+
 // src/data-methods.ts
 var BridgeDataMethods = class {
   // ---------------------------------------------------------------------------
@@ -389,6 +392,14 @@ function resolveRequestTimeout(type, requestTimeout) {
 }
 
 // src/VibeAppBridge.ts
+function resolvePosthog(mod) {
+  let candidate = mod;
+  while (candidate && typeof candidate.init !== "function" && candidate.default) {
+    candidate = candidate.default;
+  }
+  return candidate;
+}
+var posthog = resolvePosthog(posthogDefault);
 var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
 var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
 function isPreviewSelfHost(hostname) {
@@ -452,6 +463,12 @@ var VibeAppBridge = class extends BridgeDataMethods {
     super();
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.context = null;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    this.posthogInitialized = false;
     this.connectPromise = null;
     this.connectPollInterval = null;
     this.connectTimeout = null;
@@ -582,6 +599,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         console.log(
           `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
         );
+        this.initPostHog(ctx);
         const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
         if (initialSubroute && initialSubroute !== "/") {
           this.withSubrouteSuppressed(() => {
@@ -686,6 +704,34 @@ var VibeAppBridge = class extends BridgeDataMethods {
   invalidateCache(payload) {
     return this.request("INVALIDATE_CACHE", payload);
   }
+  /**
+   * Captures a custom product event from inside the Vibe App, attributed to the
+   * same PostHog person as the host (via the `distinctId` the host supplied at
+   * connect).
+   *
+   * **No-op until {@link connect} has resolved with PostHog enabled by the
+   * host** — if the host didn't send a `posthog` block (older host, or recording
+   * disabled for this env/app), nothing is sent. App authors don't import
+   * `posthog-js` themselves; this is the supported event surface.
+   *
+   * The event is sent **directly** from the iframe's own PostHog instance (only
+   * the session *recording* is forwarded to the parent), so it carries the
+   * iframe instance's `$session_id` rather than the host's — events tie to the
+   * same person, but cross-boundary event↔replay timeline correlation is a known
+   * limitation.
+   *
+   * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+   *   keeps them filterable from the host's own events.
+   * @param properties Optional event properties.
+   * @example
+   * ```ts
+   * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+   * ```
+   */
+  track(event, properties) {
+    if (!this.posthogInitialized) return;
+    posthog.capture(event, properties);
+  }
   destroy() {
     this.teardownNavigationTracking();
     this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
@@ -696,6 +742,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
     }
     this.pendingRequests.clear();
     this.context = null;
+    this.posthogInitialized = false;
     this.connectPromise = null;
     this.onContextReceived = null;
     this.onContextError = null;
@@ -713,6 +760,59 @@ var VibeAppBridge = class extends BridgeDataMethods {
     }
     this.connectPollIds.clear();
   }
+  /**
+   * Initializes PostHog session recording + analytics from the host-supplied
+   * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+   *
+   * The host is the single source of truth: when it sends no `posthog` block
+   * (older nom-ui, or recording disabled for this env/app) or `enabled: false`,
+   * this does nothing — `enabled` is the kill-switch even though `posthog-js` is
+   * bundled into the bridge. Cross-origin replay needs `recordCrossOriginIframes`
+   * on both sides so the parent receives the iframe's rrweb frames into one
+   * stitched recording, and `identify()` ties the iframe's recording + events to
+   * the same person as the host. Wrapped in try/catch so a PostHog failure is
+   * best-effort and never blocks `connect()`.
+   */
+  initPostHog(ctx) {
+    const config = ctx.posthog;
+    if (!config?.enabled) return;
+    if (this.posthogInitialized) return;
+    if (typeof window === "undefined") return;
+    if (!config.token || !config.apiHost || !config.distinctId) {
+      console.warn(
+        "[vibe-bridge] PostHog enabled but token/apiHost/distinctId missing \u2014 skipping init."
+      );
+      return;
+    }
+    try {
+      posthog.init(config.token, {
+        api_host: config.apiHost,
+        // absolute ingestion host, NOT a relative /ingest proxy
+        person_profiles: "identified_only",
+        capture_pageview: false,
+        // the host owns pageviews; don't double-count
+        autocapture: false,
+        // opt-in events only, via track()
+        // Seed the host's session id so track() events share the host's
+        // $session_id and line up with the stitched replay. Replay stitching
+        // itself does not depend on this (recordCrossOriginIframes handles it).
+        ...config.sessionId ? { bootstrap: { sessionID: config.sessionId } } : {},
+        session_recording: {
+          recordCrossOriginIframes: true,
+          // REQUIRED so the parent receives our rrweb frames
+          // Mirror nom-ui's posture (PostHogProvider.tsx): unmask inputs for
+          // richer insight, but keep password fields masked.
+          maskAllInputs: false,
+          maskInputOptions: { password: true }
+        }
+      });
+      posthog.identify(config.distinctId);
+      this.posthogInitialized = true;
+      console.log("[vibe-bridge] PostHog session recording initialized");
+    } catch (err) {
+      console.warn("[vibe-bridge] PostHog init failed \u2014 continuing without recording.", err);
+    }
+  }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
    * auto-detect SPA navigation and report it to the host. Called after

package/docs/connect-lifecycle.md

@@ -20,10 +20,20 @@ interface ContextPayload {
   user: { id: string; displayName: string }
   subroute?: string // initial deep-link path, if any
   lastClosedPeriodSlug?: string // e.g. "mar-2026"
+  posthog?: {
+    // present only when the host enables in-iframe recording
+    token: string
+    apiHost: string // absolute ingestion host, e.g. "https://us.i.posthog.com"
+    distinctId: string // host-resolved person id (so events tie to the same person)
+    sessionId?: string // host's posthog.get_session_id(); seeds bootstrap so track() events share the host session
+    enabled: boolean // master switch; false/absent → bridge initializes nothing
+  }
   hostVersion: string // version of @nominalso/vibe-host running in the host
 }
 ```
 
+When the resolved context carries `posthog.enabled === true`, the bridge auto-initializes `posthog-js` for cross-origin session recording (stitched into the host's recording) and exposes `bridge.track(event, properties?)` for custom events — see [Session recording & custom events](../README.md#session-recording--custom-events). If the host omits the `posthog` block, recording stays off.
+
 ## How it works
 
 The host pushes context to the iframe on load, but the iframe's listener may not be ready when that push arrives. `connect()` solves the race:

package/docs/getting-started.md

@@ -8,7 +8,7 @@
 npm install @nominalso/vibe-bridge
 ```
 
-No runtime dependencies. Ships ESM + CJS with self-contained TypeScript types.
+Bundles `posthog-js` (its only runtime dependency) for host-enabled in-iframe session recording. Ships ESM + CJS with self-contained TypeScript types.
 
 ## Minimal app
 

package/llms.txt

@@ -1,8 +1,8 @@
 # @nominalso/vibe-bridge
 
-> Iframe-side TypeScript SDK for building Nominal Vibe Apps — standalone browser apps (often built with Lovable) embedded in the Nominal platform via a cross-origin iframe. Connects the app to its Nominal host over a typed postMessage protocol: read Nominal data, submit Close-Management task outputs, upload files, and keep deep-link routing in sync. Browser-only, zero runtime dependencies.
+> Iframe-side TypeScript SDK for building Nominal Vibe Apps — standalone browser apps (often built with Lovable) embedded in the Nominal platform via a cross-origin iframe. Connects the app to its Nominal host over a typed postMessage protocol: read Nominal data, submit Close-Management task outputs, upload files, keep deep-link routing in sync, and (when the host enables it) record the in-iframe session to PostHog. Browser-only; bundles posthog-js as its only runtime dependency.
 
-The integration is always the same: `new VibeAppBridge()` (no config — `parentOrigin` is optional and the bridge auto-detects the embedding Nominal host; pass it only to pin explicitly or to allow preview origins), `await bridge.connect()` once (it returns the tenant/user `ContextPayload`), then call any of the ~46 typed data methods, `upload(file, options)`, or `postTaskOutput(...)`. Tear down with `bridge.destroy()`. The only write path into Nominal is `postTaskOutput`.
+The integration is always the same: `new VibeAppBridge()` (no config — `parentOrigin` is optional and the bridge auto-detects the embedding Nominal host; pass it only to pin explicitly or to allow preview origins), `await bridge.connect()` once (it returns the tenant/user `ContextPayload`), then call any of the ~46 typed data methods, `upload(file, options)`, or `postTaskOutput(...)`. Tear down with `bridge.destroy()`. The only write path into Nominal is `postTaskOutput`. Session recording auto-initializes on `connect()` only when the host sends a `posthog` block with `enabled: true`; emit custom events with `bridge.track(event, properties?)` (a no-op until then).
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Iframe-side SDK for building Nominal Vibe Apps — connects an embedded app to its Nominal host over a typed postMessage bridge (context, data fetch, file upload, subroute deep-linking).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",
@@ -33,6 +33,9 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
+  "dependencies": {
+    "posthog-js": "^1.393.5"
+  },
   "devDependencies": {
     "@nominalso/vibe-api-types": "0.0.1",
     "@nominalso/vibe-protocol-types": "0.0.1"