@nominalso/vibe-bridge 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.2.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -44,6 +44,36 @@ var HttpBridgeError = class extends BridgeError {
     this.name = "HttpBridgeError";
   }
 };
+function isOriginPattern(entry) {
+  return entry.includes("*");
+}
+var patternCache = /* @__PURE__ */ new Map();
+function patternToRegExp(pattern) {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = escaped.replace(/\\\*/g, "[^./:@?#\\s]+");
+  const compiled = new RegExp(`^${body}$`);
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+function matchesOrigin(origin, entry) {
+  if (!isOriginPattern(entry)) return origin === entry;
+  return patternToRegExp(entry).test(origin);
+}
+function isOriginAllowed(origin, allowlist, { allowPatterns }) {
+  for (const entry of allowlist) {
+    if (isOriginPattern(entry)) {
+      if (allowPatterns && matchesOrigin(origin, entry)) return true;
+    } else if (origin === entry) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/VibeAppBridge.ts
+import posthogDefault from "posthog-js";
 
 // src/data-methods.ts
 var BridgeDataMethods = class {
@@ -362,13 +392,86 @@ 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) {
+  return PREVIEW_HOST_RE.test(hostname);
+}
+function resolveActualParentOrigin() {
+  if (typeof window === "undefined") return null;
+  try {
+    const ancestors = window.location.ancestorOrigins;
+    if (ancestors && ancestors.length > 0 && ancestors[0]) return ancestors[0];
+  } catch {
+  }
+  try {
+    if (document.referrer) return new URL(document.referrer).origin;
+  } catch {
+  }
+  return null;
+}
+function resolveOriginPolicy(configured) {
+  if (typeof window !== "undefined") {
+    const override = window[PARENT_ORIGIN_OVERRIDE_KEY];
+    if (typeof override === "string" && override.length > 0) {
+      console.log(`[vibe-bridge] Using dev-bridge parentOrigin override: ${override}`);
+      return { targetOrigin: override, isTrusted: (o) => o === override };
+    }
+  }
+  const rawList = configured === void 0 ? [] : Array.isArray(configured) ? configured : [configured];
+  const allowlist = rawList.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (allowlist.length === 0) {
+    const actual2 = resolveActualParentOrigin();
+    if (actual2) return { targetOrigin: actual2, isTrusted: (o) => o === actual2 };
+    console.warn(
+      "[vibe-bridge] No `parentOrigin` set and the embedding host could not be auto-detected (no ancestorOrigins/referrer). Pass `parentOrigin` explicitly."
+    );
+    return { targetOrigin: null, isTrusted: () => false };
+  }
+  const exactEntries = allowlist.filter((entry) => !isOriginPattern(entry));
+  const hasPatterns = exactEntries.length !== allowlist.length;
+  if (allowlist.length === 1 && !hasPatterns) {
+    const only = allowlist[0];
+    return { targetOrigin: only, isTrusted: (o) => o === only };
+  }
+  const allowPatterns = hasPatterns && typeof window !== "undefined" && isPreviewSelfHost(window.location.hostname);
+  const isTrusted = (o) => isOriginAllowed(o, allowlist, { allowPatterns });
+  const actual = resolveActualParentOrigin();
+  let targetOrigin = null;
+  if (actual && isTrusted(actual)) {
+    targetOrigin = actual;
+  } else if (actual === null && !allowPatterns && exactEntries.length === 1) {
+    targetOrigin = exactEntries[0];
+  }
+  if (targetOrigin === null) {
+    console.warn(
+      "[vibe-bridge] Could not resolve a parent origin to post to. Check `parentOrigin` against the embedding host" + (hasPatterns && !allowPatterns ? " \u2014 pattern entries are ignored because this page is not served from a recognised preview host." : ".")
+    );
+  }
+  return { targetOrigin, isTrusted };
+}
 var VibeAppBridge = class extends BridgeDataMethods {
-  constructor({ parentOrigin, requestTimeout }) {
+  constructor({ parentOrigin, requestTimeout } = {}) {
     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;
     /**
@@ -423,7 +526,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
       }
     };
-    this.parentOrigin = parentOrigin;
+    const policy = resolveOriginPolicy(parentOrigin);
+    this.targetOrigin = policy.targetOrigin;
+    this.isTrustedOrigin = policy.isTrusted;
     this.requestTimeout = requestTimeout;
     this.boundHandleMessage = this.handleMessage.bind(this);
     window.addEventListener("message", this.boundHandleMessage);
@@ -459,6 +564,14 @@ var VibeAppBridge = class extends BridgeDataMethods {
   connect() {
     if (this.context) return Promise.resolve(this.context);
     if (this.connectPromise) return this.connectPromise;
+    if (this.targetOrigin === null) {
+      return Promise.reject(
+        new BridgeError(
+          "PARENT_ORIGIN_UNRESOLVED",
+          "Could not resolve a parent origin to connect to. Check `parentOrigin` against the embedding host."
+        )
+      );
+    }
     this.connectPromise = new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.stopConnectPolling();
@@ -467,6 +580,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.onContextError = null;
         reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
       }, CONNECT_TIMEOUT_MS);
+      this.connectTimeout = timer;
       this.onContextError = (error) => {
         clearTimeout(timer);
         this.stopConnectPolling();
@@ -485,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(() => {
@@ -509,7 +624,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
           requestId,
           payload: { bridgeVersion: version }
         };
-        window.parent.postMessage(message, this.parentOrigin);
+        this.postToParent(message);
       };
       poll();
       this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
@@ -589,8 +704,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.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
@@ -598,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;
@@ -609,8 +754,65 @@ var VibeAppBridge = class extends BridgeDataMethods {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    if (this.connectTimeout !== null) {
+      clearTimeout(this.connectTimeout);
+      this.connectTimeout = null;
+    }
     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
@@ -665,10 +867,13 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
   }
   sendCommand(type, payload) {
-    window.parent.postMessage(
-      { __protocol: PROTOCOL_ID, __version: PROTOCOL_VERSION, kind: "command", type, payload },
-      this.parentOrigin
-    );
+    this.postToParent({
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "command",
+      type,
+      payload
+    });
   }
   /**
    * Low-level typed request for **any** operation in {@link RequestRegistry}.
@@ -711,11 +916,20 @@ var VibeAppBridge = class extends BridgeDataMethods {
         requestId,
         payload
       };
-      window.parent.postMessage(message, this.parentOrigin);
+      this.postToParent(message);
     });
   }
+  /**
+   * Posts to the embedding host. No-op when no concrete target origin could be
+   * resolved (a config/embedding error) — `connect()` rejects fast in that case
+   * so calls never silently hang waiting on a timeout.
+   */
+  postToParent(message) {
+    if (this.targetOrigin === null) return;
+    window.parent.postMessage(message, this.targetOrigin);
+  }
   handleMessage(event) {
-    if (event.origin !== this.parentOrigin) return;
+    if (!this.isTrustedOrigin(event.origin)) return;
     if (!isBridgeMessage(event.data)) return;
     this.kindHandlers[event.data.kind]?.(event.data);
   }

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:
@@ -34,7 +44,7 @@ The host pushes context to the iframe on load, but the iframe's listener may not
 4. The bridge begins auto-tracking SPA navigation (see below).
 5. If nothing arrives within **10 seconds**, `connect()` rejects with a `BridgeError` (code `'TIMEOUT'`, message `Bridge connect timed out`).
 
-A timeout almost always means a `parentOrigin` mismatch or the host never mounted.
+A timeout almost always means a `parentOrigin` mismatch or the host never mounted. A separate, immediate rejection — `BridgeError` code `PARENT_ORIGIN_UNRESOLVED` — means no concrete parent origin could be resolved at all (e.g. a pattern-only `parentOrigin` on a non-preview host); fix `parentOrigin` rather than waiting on the timeout.
 
 ## Initial deep link
 

package/docs/getting-started.md

@@ -8,16 +8,14 @@
 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
 
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
-})
+const bridge = new VibeAppBridge() // auto-detects the embedding Nominal host
 
 async function main() {
   const ctx: ContextPayload = await bridge.connect()
@@ -32,20 +30,24 @@ async function main() {
 main().catch(console.error)
 ```
 
-## `parentOrigin`
+## `parentOrigin` (optional)
 
-`parentOrigin` is the **origin** (scheme + host + port, no path, no trailing slash) of the Nominal app that embeds your iframe. It must match exactly — the bridge ignores messages from any other origin and only posts to this one.
+By default you pass **nothing** — the bridge auto-detects the Nominal app that embeds your iframe and talks only to it. This is safe because Nominal serves Vibe Apps behind a `frame-ancestors` CSP, so only nom-ui can frame the app. Most apps need nothing here.
 
-Drive it from an environment variable so the same code works locally and in production:
+Pass `parentOrigin` to **pin the host origin** explicitly (defense in depth, or when running outside Nominal's edge). It's an **origin** — scheme + host + port, no path, no trailing slash. Drive it from an env var, or use a list / **glob patterns** for dynamic preview deployments:
 
-```sh
-# .env (committed — standalone/dev default)
-VITE_PARENT_ORIGIN=http://localhost:5173
+```ts
+new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
+```
 
-# .env.local (git-ignored — when testing inside nom-ui locally)
+```sh
+# .env.local — when pinning explicitly while testing inside nom-ui locally
 VITE_PARENT_ORIGIN=http://localhost:3000
 ```
 
+A pattern's `*` matches exactly one DNS label or port (anchored, scheme literal). Patterns are honoured **only when the app's own page is served from a recognised preview host** (`*.vercel.app`, `*.lovable.app`, `localhost`, …); on a production custom domain they are ignored and only exact origins match. Keep at least one exact origin in the list.
+
 ## Next
 
 - [`connect-lifecycle.md`](./connect-lifecycle.md) — how `connect()` works and the connection lifecycle.

package/llms.txt

@@ -1,13 +1,13 @@
 # @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: construct `VibeAppBridge` with the host `parentOrigin`, `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
 
 - [README](./README.md): install, quickstart, full API, common mistakes, and the operation catalog.
-- [Getting started](./docs/getting-started.md): install + minimal app + `parentOrigin` setup.
+- [Getting started](./docs/getting-started.md): install + minimal app + optional `parentOrigin` pinning.
 - [Connection lifecycle](./docs/connect-lifecycle.md): `connect()` semantics, `ContextPayload`, timeout, subroute sync, teardown.
 - [Fetching data](./docs/data-fetching.md): named methods vs the typed `request()` escape hatch, payload shapes, errors/timeouts, operation list.
 - [File upload](./docs/file-upload.md): `upload(file, options)`, progress events, constraints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.2.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"