@nominalso/vibe-bridge 0.2.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).
 
@@ -15,9 +15,7 @@ The host counterpart is `@nominalso/vibe-host` (used by Nominal's own app — yo
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN, // exact origin of the embedding Nominal app
-})
+const bridge = new VibeAppBridge() // no config — auto-detects the embedding Nominal app
 
 const ctx: ContextPayload = await bridge.connect() // call ONCE, await before anything else
 
@@ -32,27 +30,30 @@ bridge.destroy() // on unmount
 
 ## Core surface
 
-- `new VibeAppBridge({ parentOrigin, requestTimeout? })` — `requestTimeout` is optional; omit it and each op uses a tuned default (API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000` ms).
-- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on `parentOrigin` mismatch / host not mounted.
+- `new VibeAppBridge({ parentOrigin?, requestTimeout? })` — both optional; `new VibeAppBridge()` auto-detects the host. `requestTimeout` omitted → tuned per-op defaults (API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000` ms).
+- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on a host that never mounts, or immediately with code `PARENT_ORIGIN_UNRESOLVED` if no host could be detected/pinned.
 - ~46 typed data methods, e.g. `getChartOfAccounts`, `getSubsidiaries`, `getPeriods`, `getJournalEntries`, `getAccounts`, `postTaskOutput`. Each takes the operation's `payload` and returns its `data`.
 - `request('<OPERATION>', payload, onProgress?)` — typed escape hatch for any operation; `'<OPERATION>'` autocompletes and narrows the payload/return types.
 - `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/`.
 
 ## Gotchas (wrong → right)
 
 - **Don't call data methods before `connect()` resolves.** Always `await bridge.connect()` first.
-- **`parentOrigin` is an origin, not a URL.** `https://app.nominal.so` ✅ — not `https://app.nominal.so/app` and not a trailing slash. A mismatch makes `connect()` time out after 10 s.
+- **`parentOrigin` is optional** — omit it and the bridge auto-detects the embedding host. If you do pass it, it's an origin or list of origins (not a URL): `https://app.nominal.so` ✅ — not `https://app.nominal.so/app`, no trailing slash. For preview testing pass a list with a glob: `['https://app.nominal.so', 'https://*.vercel.app']` — patterns match only when the app itself runs on a preview host.
 - **`upload()` takes a `File`**, not a path or `FormData`.
 - **Writes go through `postTaskOutput` only.** Vibe Apps never write Nominal data directly.
 - **Call `bridge.destroy()` on unmount** to remove listeners and reject pending requests.
@@ -60,5 +61,5 @@ The full method/operation list is in `README.md` ("Operation catalog") and in `d
 ## Don't
 
 - Don't poll or busy-wait for context — `await connect()` resolves when it's ready.
-- Don't hardcode `parentOrigin`; read it from an env var so dev and prod differ.
+- Don't pass `parentOrigin` unless you mean to pin the host; the default auto-detects it. If you pin, read it from an env var (and add a preview pattern to the list when testing deploy previews).
 - Don't import from `@nominalso/vibe-protocol-types` / `vibe-api-types` — they are not published; all public types are re-exported from `@nominalso/vibe-bridge`.

package/README.md

@@ -2,7 +2,7 @@
 
 Iframe-side SDK for building **Nominal Vibe Apps** — standalone web apps (typically built with [Lovable](https://lovable.dev)) embedded in the Nominal platform via a cross-origin `<iframe>`. The bridge connects your 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.
 
-> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — construct `VibeAppBridge` with the host `parentOrigin`, `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
+> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — `new VibeAppBridge()` (no config — it auto-detects the Nominal host), `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
 
 ## Install
 
@@ -10,18 +10,17 @@ 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
 
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-// 1. Construct with the origin of the Nominal app embedding this iframe.
-//    Must match exactly — drive it from an env var.
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
-})
+// 1. Construct. No config needed — the bridge auto-detects the Nominal app
+//    that embeds it. (Pin the host origin explicitly only if you want to;
+//    see "Pinning the host origin" below.)
+const bridge = new VibeAppBridge()
 
 // 2. Connect ONCE on init and await it before any other call.
 //    Resolves with the tenant/user context (or rejects after 10s).
@@ -47,28 +46,47 @@ await bridge.postTaskOutput({ path: { task_instance_id: 'task-1' }, body: {} })
 bridge.destroy()
 ```
 
-`parentOrigin` via environment variable:
+### Pinning the host origin (optional)
 
-```sh
-# .env (committed — standalone/dev default)
-VITE_PARENT_ORIGIN=http://localhost:5173
+By default you pass **nothing** — the bridge talks only to the Nominal page that
+actually embeds it. That's safe because Nominal serves Vibe Apps behind a
+`frame-ancestors` CSP, so only nom-ui can frame your app. Most apps need nothing
+more.
+
+Pass `parentOrigin` to pin explicitly — defense in depth, or when running
+outside Nominal's edge. Drive it from an env var, or use a list / **glob
+patterns** to accept dynamic preview deployments:
+
+```ts
+new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
+```
 
-# .env.local (git-ignored — override when testing inside nom-ui)
+```sh
+# .env.local
 VITE_PARENT_ORIGIN=http://localhost:3000
 ```
 
+A pattern's `*` matches exactly one DNS label or port (anchored, scheme
+literal): `https://*.vercel.app` matches `https://pr-7.vercel.app` but not
+`https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. **Patterns are
+honoured only when this app's own page is served from a recognised preview host**
+(`*.vercel.app`, `*.lovable.app`, `localhost`, …) — on a production custom
+domain pattern entries are ignored and only exact origins match. Always include
+at least one exact origin alongside any patterns.
+
 ## API
 
 ### `new VibeAppBridge(options)`
 
-| Option           | Type     | Default  | Description                                                                                                                                                                                               |
-| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parentOrigin`   | `string` | —        | Origin of the Nominal app embedding this iframe. **Must match the host origin exactly.**                                                                                                                  |
-| `requestTimeout` | `number` | _per-op_ | Global timeout (ms) before a call rejects with `BridgeError` code `'TIMEOUT'`. Omit to use per-operation defaults: API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`. |
+| Option           | Type                 | Default  | Description                                                                                                                                                                                               |
+| ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parentOrigin`   | `string \| string[]` | _auto_   | **Optional.** Omit to auto-detect the embedding Nominal host. Pass to pin: exact origins always match; glob patterns (`https://*.vercel.app`) match only when this app runs on a preview host. See above. |
+| `requestTimeout` | `number`             | _per-op_ | Global timeout (ms) before a call rejects with `BridgeError` code `'TIMEOUT'`. Omit to use per-operation defaults: API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`. |
 
 ### `connect(): Promise<ContextPayload>`
 
-Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). Concurrent calls return the same promise.
+Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). If no concrete parent origin can be resolved (e.g. a pattern-only `parentOrigin` on a non-preview host), it rejects immediately with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`. Concurrent calls return the same promise.
 
 ### Data operations
 
@@ -100,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
 
@@ -115,7 +155,7 @@ import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 function useVibeBridge() {
   const [ctx, setCtx] = useState<ContextPayload | null>(null)
   useEffect(() => {
-    const bridge = new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+    const bridge = new VibeAppBridge()
     bridge.connect().then(setCtx).catch(console.error)
     return () => bridge.destroy()
   }, [])
@@ -172,13 +212,15 @@ const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.su
 ```
 
 ```ts
-// ❌ WRONG — parentOrigin must be an ORIGIN, not a URL with a path, and must match exactly.
+// ❌ WRONG — each entry must be an ORIGIN (scheme + host + port), not a URL with a path.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so/some/path' })
 // ❌ a trailing slash or wrong port also fails → connect() times out after 10s.
 new VibeAppBridge({ parentOrigin: 'http://localhost:3000/' })
 
-// ✅ CORRECT — scheme + host + port only, exact match to the embedding app.
+// ✅ CORRECT — scheme + host + port only, matching the embedding app.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so' })
+// ✅ CORRECT — a list with a preview pattern (honoured only on a preview host).
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
 ```
 
 ```ts

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.2.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -73,6 +83,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
+var import_posthog_js = __toESM(require("posthog-js"), 1);
 
 // src/data-methods.ts
 var BridgeDataMethods = class {
@@ -391,13 +431,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(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) {
+  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;
     /**
@@ -452,7 +565,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);
@@ -488,6 +603,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();
@@ -496,6 +619,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();
@@ -514,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(() => {
@@ -538,7 +663,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);
@@ -618,8 +743,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()) {
@@ -627,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;
@@ -638,8 +793,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
@@ -694,10 +906,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}.
@@ -740,11 +955,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);
   }