@nominalso/vibe-bridge 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.3.0";
+var version = "0.5.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -15,7 +15,7 @@ function normalizeSubroute(subroute) {
   return normalized;
 }
 var PROTOCOL_ID = "nominal-vibe-bridge";
-var PROTOCOL_VERSION = 1;
+var PROTOCOL_VERSION = 2;
 var BRIDGE_KINDS = ["request", "response", "push", "command", "progress"];
 var CORRELATED_KINDS = ["request", "response", "progress"];
 var BRIDGE_KINDS_SET = new Set(BRIDGE_KINDS);
@@ -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 {
   // ---------------------------------------------------------------------------
@@ -367,8 +370,6 @@ var CONNECT_POLL_MS = 500;
 var DEFAULT_TIMEOUTS = {
   /** Typed Nominal API reads/writes (`GET_*` / `POST_*` / `CREATE_*` / ...). */
   api: 3e4,
-  /** `GET_CONTEXT` re-fetch (the initial fetch is governed by `connect()`). */
-  context: 5e3,
   /** `INVALIDATE_CACHE`. */
   invalidate: 1e4,
   /** `UPLOAD_FILE` — large payloads + presigned S3 PUT take a while. */
@@ -381,14 +382,20 @@ function resolveRequestTimeout(type, requestTimeout) {
       return DEFAULT_TIMEOUTS.upload;
     case "INVALIDATE_CACHE":
       return DEFAULT_TIMEOUTS.invalidate;
-    case "GET_CONTEXT":
-      return DEFAULT_TIMEOUTS.context;
     default:
       return DEFAULT_TIMEOUTS.api;
   }
 }
 
 // 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,17 +459,30 @@ 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;
     this.onContextReceived = null;
-    this.onContextError = null;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    this.rejectConnect = null;
     /**
-     * Request ids of the current connect()'s GET_CONTEXT polls. Used to ignore a
-     * late response from a *previous* connect attempt, which would otherwise
-     * resolve/reject the new one (a stale error could reject a healthy reconnect).
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
      */
-    this.connectPollIds = /* @__PURE__ */ new Set();
+    this.contextChangeCallback = null;
+    /**
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
+     */
+    this.authChangeCallback = null;
     this.lastReportedSubroute = null;
     this.suppressSubrouteReport = false;
     this.subrouteCallback = null;
@@ -475,7 +495,21 @@ var VibeAppBridge = class extends BridgeDataMethods {
       progress: (msg) => this.handleProgress(msg)
     };
     this.pushHandlers = {
-      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
+      CONTEXT_PUSH: (payload) => {
+        if (this.onContextReceived) {
+          this.onContextReceived(payload);
+        } else if (this.context) {
+          this.context = payload;
+          this.contextChangeCallback?.(payload);
+        }
+      },
+      // Persistent (not nulled after connect): the host delivers PostHog once at
+      // connect via its own push, and initPostHog is idempotent, so this can run
+      // whenever the message arrives, independent of how connect() resolved.
+      POSTHOG_PUSH: (payload) => this.initPostHog(payload),
+      // Persistent: the host pushes auth changes (logout, identity/tenant
+      // switch) at any time after connect.
+      AUTH_CHANGED: (payload) => this.authChangeCallback?.(payload),
       SUBROUTE_PUSH: (payload) => {
         const safe = normalizeSubroute(payload.subroute);
         if (!safe) return;
@@ -526,11 +560,11 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * methods, `upload()`, and subroute reporting all require an established
    * connection. Concurrent calls return the same promise.
    *
-   * Actively polls the host every 500ms until a response arrives, which
-   * handles the race condition where the host's initial context push arrives
-   * before this listener is ready. Rejects with `Bridge connect timed out`
-   * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
-   * or the host hasn't mounted).
+   * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+   * by pushing the context (so it works even if the host mounts after the
+   * iframe loads). Context is only ever delivered by push. Rejects with `Bridge
+   * connect timed out` after 10 seconds if no context arrives (usually a
+   * `parentOrigin` mismatch or the host hasn't mounted).
    *
    * After connecting, if the context includes an initial subroute (e.g. from
    * a deep link), the bridge navigates to it and starts auto-tracking
@@ -560,16 +594,16 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.stopConnectPolling();
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
       }, CONNECT_TIMEOUT_MS);
       this.connectTimeout = timer;
-      this.onContextError = (error) => {
+      this.rejectConnect = (error) => {
         clearTimeout(timer);
         this.stopConnectPolling();
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         reject(error);
       };
       this.onContextReceived = (ctx) => {
@@ -578,7 +612,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.context = ctx;
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         console.log(
           `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
         );
@@ -593,23 +627,14 @@ var VibeAppBridge = class extends BridgeDataMethods {
           this.lastReportedSubroute = window.location.pathname + window.location.search;
         }
         this.setupNavigationTracking();
+        this.warnMissingListeners();
         resolve(ctx);
       };
-      const poll = () => {
-        const requestId = crypto.randomUUID();
-        this.connectPollIds.add(requestId);
-        const message = {
-          __protocol: PROTOCOL_ID,
-          __version: PROTOCOL_VERSION,
-          kind: "request",
-          type: "GET_CONTEXT",
-          requestId,
-          payload: { bridgeVersion: version }
-        };
-        this.postToParent(message);
+      const sendConnect = () => {
+        this.sendCommand("CONNECT", { bridgeVersion: version });
       };
-      poll();
-      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
+      sendConnect();
+      this.connectPollInterval = setInterval(sendConnect, CONNECT_POLL_MS);
     });
     return this.connectPromise;
   }
@@ -636,6 +661,56 @@ var VibeAppBridge = class extends BridgeDataMethods {
       this.subrouteCallback = null;
     };
   }
+  /**
+   * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+   * close, …). The callback fires for each {@link ContextPayload} the host pushes
+   * *after* connect — not for the initial context, which {@link connect} already
+   * returns. Returns an unsubscribe function. Single subscriber: a second call
+   * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+   * connect if it isn't).
+   */
+  onContextChange(callback) {
+    this.contextChangeCallback = callback;
+    return () => {
+      this.contextChangeCallback = null;
+    };
+  }
+  /**
+   * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+   * sign your backend out) or an identity/tenant switch (`authenticated: true`
+   * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+   * host pushes after connect. Returns an unsubscribe function. Single
+   * subscriber: a second call replaces the first.
+   *
+   * **Wire this before {@link connect}** — without it the embedded app won't
+   * sign out when the user logs out of Nominal (the bridge warns at connect if
+   * it isn't wired).
+   */
+  onAuthChange(callback) {
+    this.authChangeCallback = callback;
+    return () => {
+      this.authChangeCallback = null;
+    };
+  }
+  /**
+   * At connect, nudge the app if it hasn't wired the change listeners: every
+   * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+   * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+   * connect flow (not speculatively later), so wire both **before** `connect()`.
+   * The skill/codegen does this by default; this catches hand-wired apps.
+   */
+  warnMissingListeners() {
+    if (!this.authChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onAuthChange \u2014 the app will not sign out on Nominal logout or react to an identity/tenant switch. Call bridge.onAuthChange() before connect()."
+      );
+    }
+    if (!this.contextChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onContextChange \u2014 the app will not react to a tenant/subsidiary/period switch. Call bridge.onContextChange() before connect()."
+      );
+    }
+  }
   // ---------------------------------------------------------------------------
   // Host navigation & UI commands
   //
@@ -686,9 +761,37 @@ 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"));
+    this.rejectConnect?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
@@ -696,9 +799,12 @@ var VibeAppBridge = class extends BridgeDataMethods {
     }
     this.pendingRequests.clear();
     this.context = null;
+    this.posthogInitialized = false;
     this.connectPromise = null;
     this.onContextReceived = null;
-    this.onContextError = null;
+    this.rejectConnect = null;
+    this.contextChangeCallback = null;
+    this.authChangeCallback = null;
     this.subrouteCallback = null;
     this.lastReportedSubroute = null;
   }
@@ -711,7 +817,59 @@ var VibeAppBridge = class extends BridgeDataMethods {
       clearTimeout(this.connectTimeout);
       this.connectTimeout = null;
     }
-    this.connectPollIds.clear();
+  }
+  /**
+   * Initializes PostHog session recording + analytics from the host-supplied
+   * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+   * (`config.enabled`).
+   *
+   * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+   * (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. Idempotent (the `posthogInitialized` guard) and wrapped
+   * in try/catch so a duplicate push or a PostHog failure is harmless.
+   */
+  initPostHog(config) {
+    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
@@ -834,15 +992,6 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.kindHandlers[event.data.kind]?.(event.data);
   }
   handleResponse(msg) {
-    if (msg.type === "GET_CONTEXT") {
-      if (!this.connectPollIds.has(msg.requestId)) return;
-      if (msg.ok) {
-        this.onContextReceived?.(msg.data);
-      } else {
-        this.onContextError?.(new BridgeError(msg.code ?? "CONTEXT_ERROR", msg.error));
-      }
-      return;
-    }
     const pending = this.pendingRequests.get(msg.requestId);
     if (!pending) return;
     this.pendingRequests.delete(msg.requestId);

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.5.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"