@nominalso/vibe-host 0.3.0 → 0.5.0

package/README.md

@@ -29,9 +29,9 @@ const host = new VibeAppHost({
   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
 })
 
-// Start listening BEFORE the iframe loads, then push context on its `load` event.
+// Start listening. The iframe identifies itself via its CONNECT handshake, and
+// the host replies with its context — no iframe window needed up front.
 const unmount = host.mount()
-// once the iframe has loaded: host.pushContextTo(iframe.contentWindow)
 ```
 
 ## API
@@ -58,56 +58,40 @@ const trustedOrigins =
     : ['https://app.nominal.so', 'https://*.vercel.app', 'https://*.lovable.app']
 ```
 
-Because you cannot `postMessage` to a pattern, proactive context/subroute pushes target the exact entries plus any origin seen on a validated inbound message; a pattern-matched iframe still receives context via its `connect()` poll response.
+Because you cannot `postMessage` to a pattern, proactive pushes target the exact allowlist entries plus the connected iframe's learned origin; a pattern-matched iframe is reached via the concrete origin learned from its `CONNECT` handshake.
 
-### `mount(iframeWindow?): () => void`
+### `mount(): () => void`
 
-Starts listening for bridge messages and sets up browser back/forward sync. Returns a cleanup function. Pass `iframeWindow` to immediately push context; if omitted, the host answers `GET_CONTEXT` polls but won't proactively push until you call `pushContextTo`.
+Starts listening for bridge messages and sets up browser back/forward sync. Returns a cleanup function. Takes no iframe window — the iframe identifies itself via its `CONNECT` handshake (and re-identifies on every reload), and the host replies with its context.
 
-### `pushContextTo(iframeWindow): void`
+### `refreshContext(): void`
 
-Pushes the current context to the iframe and stores the window reference for future pushes (e.g. subroute sync). Call once the iframe has loaded if you called `mount()` with no argument.
+Re-reads `getContext()` and pushes it to the connected iframe (e.g. after a tenant/subsidiary switch), so the app reacts via `bridge.onContextChange`. No-op until the iframe has connected.
+
+### `notifyAuthChange(auth): void`
+
+Pushes a Nominal auth change (logout, or identity/tenant switch) to the connected iframe, so the app reacts via `bridge.onAuthChange`. No-op until the iframe has connected.
 
 ### Exports
 
-`VibeAppHost`, and the types `VibeAppHostOptions`, `HostContext`, `HostHandlers`, `RequestHandlers`, `ContextPayload`, `VibeApiClientOptions`.
+`VibeAppHost`, and the types `VibeAppHostOptions`, `HostContext`, `HostHandlers`, `RequestHandlers`, `ContextPayload`, `AuthPayload`, `VibeApiClientOptions`.
 
 ## Mounting inside Next.js (nom-ui)
 
-The iframe is server-rendered, so it may start loading before React hydrates, and cross-origin `contentDocument` is always `null`. The robust pattern: `mount()` (no arg) immediately to start listening, then `pushContextTo(iframe.contentWindow)` from the iframe's `load` event.
+Just `mount()` in an effect — no iframe-window handling, no `load`-event dance. The iframe is server-rendered and may load before React hydrates, but that's fine: its bridge re-sends `CONNECT` until the host (now listening) answers, so there's no race.
 
 ```tsx
 'use client'
-import { useEffect, useRef } from 'react'
+import { useEffect } from 'react'
 import { VibeAppHost } from '@nominalso/vibe-host'
 
 function VibeAppFrame({ host, src }: { host: VibeAppHost; src: string }) {
-  const iframeRef = useRef<HTMLIFrameElement>(null)
-
-  useEffect(() => {
-    const iframe = iframeRef.current
-    if (!iframe) return
-    const unmount = host.mount() // listen before the iframe loads
-    const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
-    iframe.addEventListener('load', onLoad)
-    return () => {
-      iframe.removeEventListener('load', onLoad)
-      unmount()
-    }
-  }, [host])
-
-  return (
-    <iframe
-      ref={iframeRef}
-      src={src}
-      sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
-    />
-  )
+  useEffect(() => host.mount(), [host]) // returns the unmount cleanup
+
+  return <iframe src={src} sandbox="allow-scripts allow-forms allow-same-origin allow-popups" />
 }
 ```
 
-Calling `contentWindow.postMessage` while the iframe is still at `about:blank` throws a `DOMException` — that's why context is pushed from the `load` event, not on effect setup.
-
 ## How it fits together
 
 The iframe side is [`@nominalso/vibe-bridge`](https://www.npmjs.com/package/@nominalso/vibe-bridge). See the [repository](https://github.com/nominalso/vibe-apps-sdk#readme) for the full protocol and architecture.

package/dist/index.cjs

@@ -27,7 +27,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.3.0";
+var version = "0.5.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -43,7 +43,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);
@@ -657,18 +657,20 @@ function rejectUnwired(op) {
 var VibeAppHost = class {
   constructor(opts) {
     /**
-     * Concrete iframe origins observed on validated inbound messages. Because you
-     * cannot `postMessage` to a glob pattern, proactive pushes target these
-     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     * The connected iframe, as two facets of one thing: `connectedWindow` is its
+     * `Window` (identity + the single push target) and `connectedOrigin` is its
+     * origin (what you `postMessage` to — you cannot post to a `Window` ref, nor to
+     * a glob). Both are written together by {@link handleConnect} (the sole writer)
+     * and cleared together on unmount, so they can never diverge.
+     *
+     * There is deliberately no other window reference. The connected window can
+     * only be learned from each `CONNECT` handshake's `event.source`, never at
+     * mount: a reloaded/remounted iframe is a *new* `Window` with the same origin,
+     * so a mount-time window would be stale. The gate blocks every non-`CONNECT`
+     * message whose source isn't `connectedWindow`; every proactive push targets it.
      */
-    this.connectedOrigins = /* @__PURE__ */ new Set();
-    this.iframeWindow = null;
-    /**
-     * Source windows we've already logged a successful handshake for. The bridge
-     * polls `GET_CONTEXT` on an interval until it connects, so without this the
-     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
-     */
-    this.handshakeLoggedWindows = /* @__PURE__ */ new WeakSet();
+    this.connectedWindow = null;
+    this.connectedOrigin = null;
     this.kindHandlers = {
       request: (msg, source, origin) => this.handleRequest(msg, source, origin),
       command: (msg) => this.dispatchCommand(msg)
@@ -677,6 +679,7 @@ var VibeAppHost = class {
     this.trustedOrigins = new Set(trustedOrigins);
     this.exactOrigins = trustedOrigins.filter((entry) => !isOriginPattern(entry));
     this.getContext = getContext;
+    this.getPostHog = opts.getPostHog;
     this.appBasePath = appBasePath;
     this.onRequestComplete = opts.onRequestComplete;
     this.rateLimiter = createRateLimiter(opts.rateLimit ?? DEFAULT_RATE_LIMIT);
@@ -689,7 +692,8 @@ var VibeAppHost = class {
     this.commandHandlers = this.buildCommandHandlers(opts);
   }
   dispatchCommand(msg) {
-    const handler = this.commandHandlers[msg.type];
+    const handlers = this.commandHandlers;
+    const handler = handlers[msg.type];
     if (!handler) {
       console.warn(`[vibe-host] Received unknown command "${msg.type}" \u2014 ignoring.`);
       return;
@@ -735,31 +739,41 @@ var VibeAppHost = class {
    * Starts listening for bridge messages and sets up browser back/forward sync.
    * Returns a cleanup function to call on unmount.
    *
-   * Pass `iframeWindow` to immediately push context to the iframe. If omitted,
-   * the host will respond to GET_CONTEXT polls from the bridge but won't
-   * proactively push — call `pushContextTo(iframeWindow)` once the iframe has
-   * loaded to trigger the proactive push.
+   * Takes no iframe window: the host learns the iframe from its `CONNECT`
+   * handshake (and re-learns it on every reload), then delivers context as the
+   * reply to that handshake. Just call `mount()` once the host exists.
    */
-  mount(iframeWindow) {
-    if (iframeWindow) this.iframeWindow = iframeWindow;
+  mount() {
     window.addEventListener("message", this.boundHandleMessage);
     window.addEventListener("popstate", this.boundHandlePopState);
-    if (iframeWindow) this.pushContext(iframeWindow);
     return () => {
       window.removeEventListener("message", this.boundHandleMessage);
       window.removeEventListener("popstate", this.boundHandlePopState);
-      this.iframeWindow = null;
-      this.connectedOrigins.clear();
+      this.connectedWindow = null;
+      this.connectedOrigin = null;
     };
   }
   /**
-   * Pushes the current context to the iframe and updates the stored iframe
-   * window reference. Call this once the iframe has loaded if `mount()` was
-   * called without an `iframeWindow`.
+   * Re-reads `getContext()` and re-pushes it to the connected iframe, so an open
+   * app reacts to a tenant/subsidiary switch or period close without reloading.
+   * PostHog is not re-sent (it rides only the connect handshake). No-op until an
+   * iframe is mounted.
+   */
+  refreshContext() {
+    if (!this.connectedWindow) return;
+    this.pushContext(this.connectedWindow);
+  }
+  /**
+   * Notifies the connected iframe of a Nominal auth change — a logout
+   * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+   * with a new `userId`/`tenant`) — via `AUTH_CHANGED`, so the app re-authenticates
+   * or signs its own backend out. No-op until the iframe has connected. When auth
+   * and context change together, call this *before* {@link refreshContext} ("auth
+   * change, then context").
    */
-  pushContextTo(iframeWindow) {
-    this.iframeWindow = iframeWindow;
-    this.pushContext(iframeWindow);
+  notifyAuthChange(auth) {
+    if (!this.connectedWindow) return;
+    this.pushToIframe("AUTH_CHANGED", auth);
   }
   pushContext(target) {
     const message = {
@@ -774,14 +788,14 @@ var VibeAppHost = class {
     }
   }
   handlePopState() {
-    if (!this.iframeWindow) return;
+    if (!this.connectedWindow) return;
     const currentPath = window.location.pathname;
     if (!currentPath.startsWith(this.appBasePath)) return;
     const subroute = currentPath.slice(this.appBasePath.length) || "/";
     this.pushToIframe("SUBROUTE_PUSH", { subroute });
   }
   pushToIframe(type, payload) {
-    if (!this.iframeWindow) return;
+    if (!this.connectedWindow) return;
     const message = {
       __protocol: PROTOCOL_ID,
       __version: PROTOCOL_VERSION,
@@ -790,44 +804,95 @@ var VibeAppHost = class {
       payload
     };
     for (const origin of this.concreteTargets()) {
-      this.iframeWindow.postMessage(message, origin);
+      this.connectedWindow.postMessage(message, origin);
     }
   }
+  /**
+   * Sends the host's PostHog config to a freshly connected iframe as a one-time
+   * POSTHOG_PUSH. No-op when no `getPostHog` source is configured or it returns
+   * nothing (recording disabled). Targets the exact handshaking window/origin
+   * (no `concreteTargets` fan-out) since it fires from a validated inbound poll.
+   */
+  pushPostHog(target, origin) {
+    const payload = this.getPostHog?.();
+    if (!payload) return;
+    const message = {
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "push",
+      type: "POSTHOG_PUSH",
+      payload
+    };
+    target.postMessage(message, origin);
+  }
   async handleMessage(event) {
     if (!isOriginAllowed(event.origin, this.trustedOrigins, { allowPatterns: true })) return;
     if (!isBridgeMessage(event.data)) return;
-    this.connectedOrigins.add(event.origin);
-    await this.kindHandlers[event.data.kind]?.(event.data, event.source, event.origin);
+    const msg = event.data;
+    const source = event.source;
+    if (msg.kind === "command" && msg.type === "CONNECT") {
+      this.handleConnect(source, event.origin);
+      return;
+    }
+    if (source !== this.connectedWindow) {
+      if (msg.kind === "request") {
+        this.respond(source, event.origin, {
+          kind: "response",
+          type: msg.type,
+          requestId: msg.requestId,
+          ok: false,
+          error: "Vibe App is not connected \u2014 call connect() first.",
+          code: "NOT_CONNECTED"
+        });
+      }
+      return;
+    }
+    await this.kindHandlers[msg.kind]?.(msg, source, event.origin);
+  }
+  /**
+   * Handles the CONNECT handshake: records the connecting window/origin (which
+   * opens the connection gate for it) and pushes the initial context + one-time
+   * PostHog config. Only the first CONNECT per origin pushes — later retries are
+   * ignored, so the bridge receives exactly one initial CONTEXT_PUSH (no
+   * spurious onContextChange). A reloaded iframe is a new window and re-connects
+   * normally. If `getContext()` throws, the window is left unconnected so the
+   * bridge's retry can recover.
+   */
+  handleConnect(source, origin) {
+    if (source === this.connectedWindow) return;
+    try {
+      const ctx = { ...this.getContext(), hostVersion: version };
+      this.connectedWindow = source;
+      this.connectedOrigin = origin;
+      console.log(
+        `[vibe-host] Vibe App connected \u2014 host: ${version}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
+      );
+      const message = {
+        __protocol: PROTOCOL_ID,
+        __version: PROTOCOL_VERSION,
+        kind: "push",
+        type: "CONTEXT_PUSH",
+        payload: ctx
+      };
+      source.postMessage(message, origin);
+      this.pushPostHog(source, origin);
+    } catch (err) {
+      console.error("[vibe-host] getContext threw during connect \u2014 context not delivered.", err);
+    }
   }
   /**
    * Concrete origins a proactive push may target: the exact allowlist entries
-   * plus any origins seen on validated inbound messages. Never includes glob
-   * patterns (you cannot `postMessage` to one). When only exact origins are
-   * configured this equals the configured set, so behaviour is unchanged.
+   * plus the connected iframe's learned origin. Never includes glob patterns
+   * (you cannot `postMessage` to one). When only exact origins are configured
+   * this equals the configured set, so behaviour is unchanged.
    */
   concreteTargets() {
-    return /* @__PURE__ */ new Set([...this.exactOrigins, ...this.connectedOrigins]);
+    const targets = new Set(this.exactOrigins);
+    if (this.connectedOrigin) targets.add(this.connectedOrigin);
+    return targets;
   }
   async handleRequest(msg, source, origin) {
     const { requestId, type } = msg;
-    if (type === "GET_CONTEXT") {
-      try {
-        const ctx = { ...this.getContext(), hostVersion: version };
-        if (!this.handshakeLoggedWindows.has(source)) {
-          this.handshakeLoggedWindows.add(source);
-          const bridgeVersion = msg.payload?.bridgeVersion ?? "unknown";
-          console.log(
-            `[vibe-host] Vibe App connected \u2014 bridge: ${bridgeVersion}, host: ${version}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
-          );
-        }
-        this.respond(source, origin, { kind: "response", type, requestId, ok: true, data: ctx });
-      } catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        const code = err instanceof BridgeError ? err.code : "CONTEXT_ERROR";
-        this.respond(source, origin, { kind: "response", type, requestId, ok: false, error, code });
-      }
-      return;
-    }
     if (!checkRateLimit(this.rateLimiter)) {
       this.respond(source, origin, {
         kind: "response",

package/dist/index.d.cts

@@ -1390,6 +1390,7 @@ type ActivityProviderOperationErrorType = 'Connection Error' | 'Authentication E
 type ActivityReconciliationDefinitionData = {
     type: ActivityReconciliationType;
     task_definition_id: string;
+    currency?: ActivityCurrency | null;
     side_a_entity_type: ActivityReconciliationEntityType;
     side_a_entity_id: string;
     side_b_entity_type: ActivityReconciliationEntityType;
@@ -1403,7 +1404,6 @@ type ActivityReconciliationInstanceDataInput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: number | string | null;
     side_b_value?: number | string | null;
     reconciling_items_balance?: number | string | null;
@@ -1417,7 +1417,6 @@ type ActivityReconciliationInstanceDataOutput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: string | null;
     side_b_value?: string | null;
     reconciling_items_balance?: string | null;
@@ -3180,6 +3179,76 @@ 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 it over the bridge (as a one-time `POSTHOG_PUSH`, separate from
+ * {@link ContextPayload}) so the iframe never hardcodes any of it. When the host
+ * has no PostHog config (recording disabled for this env/app), it sends no
+ * `POSTHOG_PUSH` and 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;
+}
+/**
+ * Authentication-state change the host pushes to the iframe via `AUTH_CHANGED`.
+ * It carries the security principal the embedded app authenticates and scopes
+ * its own data by. Sent when the Nominal session changes: a logout
+ * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+ * with a new `userId`/`tenant`). The initial state is implicit at connect — the
+ * iframe only loads when authenticated, and the current identity/tenant are
+ * {@link ContextPayload.user} / {@link ContextPayload.tenant}, so apps baseline
+ * off those and react to this push.
+ *
+ * Subsidiary/period and other view-level state are NOT here — they ride the
+ * follow-up `CONTEXT_PUSH` (`onContextChange`), per "auth change, then context".
+ */
+interface AuthPayload {
+    /** Whether the Nominal user is still authenticated. */
+    authenticated: boolean;
+    /** The effective Nominal user id when authenticated; omitted on logout. */
+    userId?: string;
+    /** The tenant the user is acting in — the app's data-scoping key (RLS). */
+    tenant?: string;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3195,11 +3264,6 @@ interface ContextPayload {
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
-/** Payload sent by the bridge when requesting context from the host. */
-interface GetContextPayload {
-    /** Version of the bridge SDK (@nominalso/vibe-bridge) running in the iframe. */
-    bridgeVersion: string;
-}
 
 interface UploadPayload {
     buffer: ArrayBuffer;
@@ -3451,10 +3515,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3568,6 +3628,13 @@ interface VibeAppHostOptions {
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
+    /**
+     * Optional PostHog config source. Read **once per iframe** at connect and
+     * delivered via a one-time `POSTHOG_PUSH`, kept separate from `getContext` so
+     * it never re-sends when context or auth later change. Return `undefined` (or
+     * a config with `enabled: false`) to disable in-iframe recording.
+     */
+    getPostHog?: () => PostHogContext | undefined;
     /**
      * The base URL path of this Vibe App in nom-ui, e.g. `/acme/1/apps/fixed-assets`.
      * Used to sync the browser URL with the iframe's internal subroute.
@@ -3620,18 +3687,11 @@ interface VibeAppHostOptions {
  *   onUpload: (p, sendProgress) => uploadToS3(p, sendProgress),
  * })
  *
- * useEffect(() => {
- *   const iframe = iframeRef.current
- *   if (!iframe) return
- *   const unmount = host.mount() // listen before the iframe loads
- *   const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
- *   iframe.addEventListener('load', onLoad)
- *   return () => {
- *     iframe.removeEventListener('load', onLoad)
- *     unmount()
- *   }
- * }, [host])
+ * useEffect(() => host.mount(), [host]) // returns the unmount cleanup
  * ```
+ *
+ * `mount()` just starts listening; the iframe identifies itself via its
+ * `CONNECT` handshake, so the host never needs the iframe's `Window` up front.
  */
 declare class VibeAppHost {
     /**
@@ -3644,26 +3704,29 @@ declare class VibeAppHost {
     /** The exact (non-pattern) subset of {@link trustedOrigins} — see {@link concreteTargets}. */
     private readonly exactOrigins;
     /**
-     * Concrete iframe origins observed on validated inbound messages. Because you
-     * cannot `postMessage` to a glob pattern, proactive pushes target these
-     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     * The connected iframe, as two facets of one thing: `connectedWindow` is its
+     * `Window` (identity + the single push target) and `connectedOrigin` is its
+     * origin (what you `postMessage` to — you cannot post to a `Window` ref, nor to
+     * a glob). Both are written together by {@link handleConnect} (the sole writer)
+     * and cleared together on unmount, so they can never diverge.
+     *
+     * There is deliberately no other window reference. The connected window can
+     * only be learned from each `CONNECT` handshake's `event.source`, never at
+     * mount: a reloaded/remounted iframe is a *new* `Window` with the same origin,
+     * so a mount-time window would be stale. The gate blocks every non-`CONNECT`
+     * message whose source isn't `connectedWindow`; every proactive push targets it.
      */
-    private readonly connectedOrigins;
+    private connectedWindow;
+    private connectedOrigin;
     private readonly handlers;
     private readonly commandHandlers;
     private readonly getContext;
+    private readonly getPostHog?;
     private readonly appBasePath;
     private readonly onRequestComplete?;
     private readonly rateLimiter;
     private readonly boundHandleMessage;
     private readonly boundHandlePopState;
-    private iframeWindow;
-    /**
-     * Source windows we've already logged a successful handshake for. The bridge
-     * polls `GET_CONTEXT` on an interval until it connects, so without this the
-     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
-     */
-    private readonly handshakeLoggedWindows;
     private readonly kindHandlers;
     private dispatchCommand;
     /**
@@ -3683,31 +3746,57 @@ declare class VibeAppHost {
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
      *
-     * Pass `iframeWindow` to immediately push context to the iframe. If omitted,
-     * the host will respond to GET_CONTEXT polls from the bridge but won't
-     * proactively push — call `pushContextTo(iframeWindow)` once the iframe has
-     * loaded to trigger the proactive push.
+     * Takes no iframe window: the host learns the iframe from its `CONNECT`
+     * handshake (and re-learns it on every reload), then delivers context as the
+     * reply to that handshake. Just call `mount()` once the host exists.
+     */
+    mount(): () => void;
+    /**
+     * Re-reads `getContext()` and re-pushes it to the connected iframe, so an open
+     * app reacts to a tenant/subsidiary switch or period close without reloading.
+     * PostHog is not re-sent (it rides only the connect handshake). No-op until an
+     * iframe is mounted.
      */
-    mount(iframeWindow?: Window): () => void;
+    refreshContext(): void;
     /**
-     * Pushes the current context to the iframe and updates the stored iframe
-     * window reference. Call this once the iframe has loaded if `mount()` was
-     * called without an `iframeWindow`.
+     * Notifies the connected iframe of a Nominal auth change — a logout
+     * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant`) — via `AUTH_CHANGED`, so the app re-authenticates
+     * or signs its own backend out. No-op until the iframe has connected. When auth
+     * and context change together, call this *before* {@link refreshContext} ("auth
+     * change, then context").
      */
-    pushContextTo(iframeWindow: Window): void;
+    notifyAuthChange(auth: AuthPayload): void;
     private pushContext;
     private handlePopState;
     private pushToIframe;
+    /**
+     * Sends the host's PostHog config to a freshly connected iframe as a one-time
+     * POSTHOG_PUSH. No-op when no `getPostHog` source is configured or it returns
+     * nothing (recording disabled). Targets the exact handshaking window/origin
+     * (no `concreteTargets` fan-out) since it fires from a validated inbound poll.
+     */
+    private pushPostHog;
     private handleMessage;
+    /**
+     * Handles the CONNECT handshake: records the connecting window/origin (which
+     * opens the connection gate for it) and pushes the initial context + one-time
+     * PostHog config. Only the first CONNECT per origin pushes — later retries are
+     * ignored, so the bridge receives exactly one initial CONTEXT_PUSH (no
+     * spurious onContextChange). A reloaded iframe is a new window and re-connects
+     * normally. If `getContext()` throws, the window is left unconnected so the
+     * bridge's retry can recover.
+     */
+    private handleConnect;
     /**
      * Concrete origins a proactive push may target: the exact allowlist entries
-     * plus any origins seen on validated inbound messages. Never includes glob
-     * patterns (you cannot `postMessage` to one). When only exact origins are
-     * configured this equals the configured set, so behaviour is unchanged.
+     * plus the connected iframe's learned origin. Never includes glob patterns
+     * (you cannot `postMessage` to one). When only exact origins are configured
+     * this equals the configured set, so behaviour is unchanged.
      */
     private concreteTargets;
     private handleRequest;
     private respond;
 }
 
-export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { type AuthPayload, BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type PostHogContext, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.d.ts

@@ -1390,6 +1390,7 @@ type ActivityProviderOperationErrorType = 'Connection Error' | 'Authentication E
 type ActivityReconciliationDefinitionData = {
     type: ActivityReconciliationType;
     task_definition_id: string;
+    currency?: ActivityCurrency | null;
     side_a_entity_type: ActivityReconciliationEntityType;
     side_a_entity_id: string;
     side_b_entity_type: ActivityReconciliationEntityType;
@@ -1403,7 +1404,6 @@ type ActivityReconciliationInstanceDataInput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: number | string | null;
     side_b_value?: number | string | null;
     reconciling_items_balance?: number | string | null;
@@ -1417,7 +1417,6 @@ type ActivityReconciliationInstanceDataOutput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: string | null;
     side_b_value?: string | null;
     reconciling_items_balance?: string | null;
@@ -3180,6 +3179,76 @@ 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 it over the bridge (as a one-time `POSTHOG_PUSH`, separate from
+ * {@link ContextPayload}) so the iframe never hardcodes any of it. When the host
+ * has no PostHog config (recording disabled for this env/app), it sends no
+ * `POSTHOG_PUSH` and 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;
+}
+/**
+ * Authentication-state change the host pushes to the iframe via `AUTH_CHANGED`.
+ * It carries the security principal the embedded app authenticates and scopes
+ * its own data by. Sent when the Nominal session changes: a logout
+ * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+ * with a new `userId`/`tenant`). The initial state is implicit at connect — the
+ * iframe only loads when authenticated, and the current identity/tenant are
+ * {@link ContextPayload.user} / {@link ContextPayload.tenant}, so apps baseline
+ * off those and react to this push.
+ *
+ * Subsidiary/period and other view-level state are NOT here — they ride the
+ * follow-up `CONTEXT_PUSH` (`onContextChange`), per "auth change, then context".
+ */
+interface AuthPayload {
+    /** Whether the Nominal user is still authenticated. */
+    authenticated: boolean;
+    /** The effective Nominal user id when authenticated; omitted on logout. */
+    userId?: string;
+    /** The tenant the user is acting in — the app's data-scoping key (RLS). */
+    tenant?: string;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3195,11 +3264,6 @@ interface ContextPayload {
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
-/** Payload sent by the bridge when requesting context from the host. */
-interface GetContextPayload {
-    /** Version of the bridge SDK (@nominalso/vibe-bridge) running in the iframe. */
-    bridgeVersion: string;
-}
 
 interface UploadPayload {
     buffer: ArrayBuffer;
@@ -3451,10 +3515,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3568,6 +3628,13 @@ interface VibeAppHostOptions {
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
+    /**
+     * Optional PostHog config source. Read **once per iframe** at connect and
+     * delivered via a one-time `POSTHOG_PUSH`, kept separate from `getContext` so
+     * it never re-sends when context or auth later change. Return `undefined` (or
+     * a config with `enabled: false`) to disable in-iframe recording.
+     */
+    getPostHog?: () => PostHogContext | undefined;
     /**
      * The base URL path of this Vibe App in nom-ui, e.g. `/acme/1/apps/fixed-assets`.
      * Used to sync the browser URL with the iframe's internal subroute.
@@ -3620,18 +3687,11 @@ interface VibeAppHostOptions {
  *   onUpload: (p, sendProgress) => uploadToS3(p, sendProgress),
  * })
  *
- * useEffect(() => {
- *   const iframe = iframeRef.current
- *   if (!iframe) return
- *   const unmount = host.mount() // listen before the iframe loads
- *   const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
- *   iframe.addEventListener('load', onLoad)
- *   return () => {
- *     iframe.removeEventListener('load', onLoad)
- *     unmount()
- *   }
- * }, [host])
+ * useEffect(() => host.mount(), [host]) // returns the unmount cleanup
  * ```
+ *
+ * `mount()` just starts listening; the iframe identifies itself via its
+ * `CONNECT` handshake, so the host never needs the iframe's `Window` up front.
  */
 declare class VibeAppHost {
     /**
@@ -3644,26 +3704,29 @@ declare class VibeAppHost {
     /** The exact (non-pattern) subset of {@link trustedOrigins} — see {@link concreteTargets}. */
     private readonly exactOrigins;
     /**
-     * Concrete iframe origins observed on validated inbound messages. Because you
-     * cannot `postMessage` to a glob pattern, proactive pushes target these
-     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     * The connected iframe, as two facets of one thing: `connectedWindow` is its
+     * `Window` (identity + the single push target) and `connectedOrigin` is its
+     * origin (what you `postMessage` to — you cannot post to a `Window` ref, nor to
+     * a glob). Both are written together by {@link handleConnect} (the sole writer)
+     * and cleared together on unmount, so they can never diverge.
+     *
+     * There is deliberately no other window reference. The connected window can
+     * only be learned from each `CONNECT` handshake's `event.source`, never at
+     * mount: a reloaded/remounted iframe is a *new* `Window` with the same origin,
+     * so a mount-time window would be stale. The gate blocks every non-`CONNECT`
+     * message whose source isn't `connectedWindow`; every proactive push targets it.
      */
-    private readonly connectedOrigins;
+    private connectedWindow;
+    private connectedOrigin;
     private readonly handlers;
     private readonly commandHandlers;
     private readonly getContext;
+    private readonly getPostHog?;
     private readonly appBasePath;
     private readonly onRequestComplete?;
     private readonly rateLimiter;
     private readonly boundHandleMessage;
     private readonly boundHandlePopState;
-    private iframeWindow;
-    /**
-     * Source windows we've already logged a successful handshake for. The bridge
-     * polls `GET_CONTEXT` on an interval until it connects, so without this the
-     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
-     */
-    private readonly handshakeLoggedWindows;
     private readonly kindHandlers;
     private dispatchCommand;
     /**
@@ -3683,31 +3746,57 @@ declare class VibeAppHost {
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
      *
-     * Pass `iframeWindow` to immediately push context to the iframe. If omitted,
-     * the host will respond to GET_CONTEXT polls from the bridge but won't
-     * proactively push — call `pushContextTo(iframeWindow)` once the iframe has
-     * loaded to trigger the proactive push.
+     * Takes no iframe window: the host learns the iframe from its `CONNECT`
+     * handshake (and re-learns it on every reload), then delivers context as the
+     * reply to that handshake. Just call `mount()` once the host exists.
+     */
+    mount(): () => void;
+    /**
+     * Re-reads `getContext()` and re-pushes it to the connected iframe, so an open
+     * app reacts to a tenant/subsidiary switch or period close without reloading.
+     * PostHog is not re-sent (it rides only the connect handshake). No-op until an
+     * iframe is mounted.
      */
-    mount(iframeWindow?: Window): () => void;
+    refreshContext(): void;
     /**
-     * Pushes the current context to the iframe and updates the stored iframe
-     * window reference. Call this once the iframe has loaded if `mount()` was
-     * called without an `iframeWindow`.
+     * Notifies the connected iframe of a Nominal auth change — a logout
+     * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant`) — via `AUTH_CHANGED`, so the app re-authenticates
+     * or signs its own backend out. No-op until the iframe has connected. When auth
+     * and context change together, call this *before* {@link refreshContext} ("auth
+     * change, then context").
      */
-    pushContextTo(iframeWindow: Window): void;
+    notifyAuthChange(auth: AuthPayload): void;
     private pushContext;
     private handlePopState;
     private pushToIframe;
+    /**
+     * Sends the host's PostHog config to a freshly connected iframe as a one-time
+     * POSTHOG_PUSH. No-op when no `getPostHog` source is configured or it returns
+     * nothing (recording disabled). Targets the exact handshaking window/origin
+     * (no `concreteTargets` fan-out) since it fires from a validated inbound poll.
+     */
+    private pushPostHog;
     private handleMessage;
+    /**
+     * Handles the CONNECT handshake: records the connecting window/origin (which
+     * opens the connection gate for it) and pushes the initial context + one-time
+     * PostHog config. Only the first CONNECT per origin pushes — later retries are
+     * ignored, so the bridge receives exactly one initial CONTEXT_PUSH (no
+     * spurious onContextChange). A reloaded iframe is a new window and re-connects
+     * normally. If `getContext()` throws, the window is left unconnected so the
+     * bridge's retry can recover.
+     */
+    private handleConnect;
     /**
      * Concrete origins a proactive push may target: the exact allowlist entries
-     * plus any origins seen on validated inbound messages. Never includes glob
-     * patterns (you cannot `postMessage` to one). When only exact origins are
-     * configured this equals the configured set, so behaviour is unchanged.
+     * plus the connected iframe's learned origin. Never includes glob patterns
+     * (you cannot `postMessage` to one). When only exact origins are configured
+     * this equals the configured set, so behaviour is unchanged.
      */
     private concreteTargets;
     private handleRequest;
     private respond;
 }
 
-export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { type AuthPayload, BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type PostHogContext, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

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);
@@ -632,18 +632,20 @@ function rejectUnwired(op) {
 var VibeAppHost = class {
   constructor(opts) {
     /**
-     * Concrete iframe origins observed on validated inbound messages. Because you
-     * cannot `postMessage` to a glob pattern, proactive pushes target these
-     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     * The connected iframe, as two facets of one thing: `connectedWindow` is its
+     * `Window` (identity + the single push target) and `connectedOrigin` is its
+     * origin (what you `postMessage` to — you cannot post to a `Window` ref, nor to
+     * a glob). Both are written together by {@link handleConnect} (the sole writer)
+     * and cleared together on unmount, so they can never diverge.
+     *
+     * There is deliberately no other window reference. The connected window can
+     * only be learned from each `CONNECT` handshake's `event.source`, never at
+     * mount: a reloaded/remounted iframe is a *new* `Window` with the same origin,
+     * so a mount-time window would be stale. The gate blocks every non-`CONNECT`
+     * message whose source isn't `connectedWindow`; every proactive push targets it.
      */
-    this.connectedOrigins = /* @__PURE__ */ new Set();
-    this.iframeWindow = null;
-    /**
-     * Source windows we've already logged a successful handshake for. The bridge
-     * polls `GET_CONTEXT` on an interval until it connects, so without this the
-     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
-     */
-    this.handshakeLoggedWindows = /* @__PURE__ */ new WeakSet();
+    this.connectedWindow = null;
+    this.connectedOrigin = null;
     this.kindHandlers = {
       request: (msg, source, origin) => this.handleRequest(msg, source, origin),
       command: (msg) => this.dispatchCommand(msg)
@@ -652,6 +654,7 @@ var VibeAppHost = class {
     this.trustedOrigins = new Set(trustedOrigins);
     this.exactOrigins = trustedOrigins.filter((entry) => !isOriginPattern(entry));
     this.getContext = getContext;
+    this.getPostHog = opts.getPostHog;
     this.appBasePath = appBasePath;
     this.onRequestComplete = opts.onRequestComplete;
     this.rateLimiter = createRateLimiter(opts.rateLimit ?? DEFAULT_RATE_LIMIT);
@@ -664,7 +667,8 @@ var VibeAppHost = class {
     this.commandHandlers = this.buildCommandHandlers(opts);
   }
   dispatchCommand(msg) {
-    const handler = this.commandHandlers[msg.type];
+    const handlers = this.commandHandlers;
+    const handler = handlers[msg.type];
     if (!handler) {
       console.warn(`[vibe-host] Received unknown command "${msg.type}" \u2014 ignoring.`);
       return;
@@ -710,31 +714,41 @@ var VibeAppHost = class {
    * Starts listening for bridge messages and sets up browser back/forward sync.
    * Returns a cleanup function to call on unmount.
    *
-   * Pass `iframeWindow` to immediately push context to the iframe. If omitted,
-   * the host will respond to GET_CONTEXT polls from the bridge but won't
-   * proactively push — call `pushContextTo(iframeWindow)` once the iframe has
-   * loaded to trigger the proactive push.
+   * Takes no iframe window: the host learns the iframe from its `CONNECT`
+   * handshake (and re-learns it on every reload), then delivers context as the
+   * reply to that handshake. Just call `mount()` once the host exists.
    */
-  mount(iframeWindow) {
-    if (iframeWindow) this.iframeWindow = iframeWindow;
+  mount() {
     window.addEventListener("message", this.boundHandleMessage);
     window.addEventListener("popstate", this.boundHandlePopState);
-    if (iframeWindow) this.pushContext(iframeWindow);
     return () => {
       window.removeEventListener("message", this.boundHandleMessage);
       window.removeEventListener("popstate", this.boundHandlePopState);
-      this.iframeWindow = null;
-      this.connectedOrigins.clear();
+      this.connectedWindow = null;
+      this.connectedOrigin = null;
     };
   }
   /**
-   * Pushes the current context to the iframe and updates the stored iframe
-   * window reference. Call this once the iframe has loaded if `mount()` was
-   * called without an `iframeWindow`.
+   * Re-reads `getContext()` and re-pushes it to the connected iframe, so an open
+   * app reacts to a tenant/subsidiary switch or period close without reloading.
+   * PostHog is not re-sent (it rides only the connect handshake). No-op until an
+   * iframe is mounted.
+   */
+  refreshContext() {
+    if (!this.connectedWindow) return;
+    this.pushContext(this.connectedWindow);
+  }
+  /**
+   * Notifies the connected iframe of a Nominal auth change — a logout
+   * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+   * with a new `userId`/`tenant`) — via `AUTH_CHANGED`, so the app re-authenticates
+   * or signs its own backend out. No-op until the iframe has connected. When auth
+   * and context change together, call this *before* {@link refreshContext} ("auth
+   * change, then context").
    */
-  pushContextTo(iframeWindow) {
-    this.iframeWindow = iframeWindow;
-    this.pushContext(iframeWindow);
+  notifyAuthChange(auth) {
+    if (!this.connectedWindow) return;
+    this.pushToIframe("AUTH_CHANGED", auth);
   }
   pushContext(target) {
     const message = {
@@ -749,14 +763,14 @@ var VibeAppHost = class {
     }
   }
   handlePopState() {
-    if (!this.iframeWindow) return;
+    if (!this.connectedWindow) return;
     const currentPath = window.location.pathname;
     if (!currentPath.startsWith(this.appBasePath)) return;
     const subroute = currentPath.slice(this.appBasePath.length) || "/";
     this.pushToIframe("SUBROUTE_PUSH", { subroute });
   }
   pushToIframe(type, payload) {
-    if (!this.iframeWindow) return;
+    if (!this.connectedWindow) return;
     const message = {
       __protocol: PROTOCOL_ID,
       __version: PROTOCOL_VERSION,
@@ -765,44 +779,95 @@ var VibeAppHost = class {
       payload
     };
     for (const origin of this.concreteTargets()) {
-      this.iframeWindow.postMessage(message, origin);
+      this.connectedWindow.postMessage(message, origin);
     }
   }
+  /**
+   * Sends the host's PostHog config to a freshly connected iframe as a one-time
+   * POSTHOG_PUSH. No-op when no `getPostHog` source is configured or it returns
+   * nothing (recording disabled). Targets the exact handshaking window/origin
+   * (no `concreteTargets` fan-out) since it fires from a validated inbound poll.
+   */
+  pushPostHog(target, origin) {
+    const payload = this.getPostHog?.();
+    if (!payload) return;
+    const message = {
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "push",
+      type: "POSTHOG_PUSH",
+      payload
+    };
+    target.postMessage(message, origin);
+  }
   async handleMessage(event) {
     if (!isOriginAllowed(event.origin, this.trustedOrigins, { allowPatterns: true })) return;
     if (!isBridgeMessage(event.data)) return;
-    this.connectedOrigins.add(event.origin);
-    await this.kindHandlers[event.data.kind]?.(event.data, event.source, event.origin);
+    const msg = event.data;
+    const source = event.source;
+    if (msg.kind === "command" && msg.type === "CONNECT") {
+      this.handleConnect(source, event.origin);
+      return;
+    }
+    if (source !== this.connectedWindow) {
+      if (msg.kind === "request") {
+        this.respond(source, event.origin, {
+          kind: "response",
+          type: msg.type,
+          requestId: msg.requestId,
+          ok: false,
+          error: "Vibe App is not connected \u2014 call connect() first.",
+          code: "NOT_CONNECTED"
+        });
+      }
+      return;
+    }
+    await this.kindHandlers[msg.kind]?.(msg, source, event.origin);
+  }
+  /**
+   * Handles the CONNECT handshake: records the connecting window/origin (which
+   * opens the connection gate for it) and pushes the initial context + one-time
+   * PostHog config. Only the first CONNECT per origin pushes — later retries are
+   * ignored, so the bridge receives exactly one initial CONTEXT_PUSH (no
+   * spurious onContextChange). A reloaded iframe is a new window and re-connects
+   * normally. If `getContext()` throws, the window is left unconnected so the
+   * bridge's retry can recover.
+   */
+  handleConnect(source, origin) {
+    if (source === this.connectedWindow) return;
+    try {
+      const ctx = { ...this.getContext(), hostVersion: version };
+      this.connectedWindow = source;
+      this.connectedOrigin = origin;
+      console.log(
+        `[vibe-host] Vibe App connected \u2014 host: ${version}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
+      );
+      const message = {
+        __protocol: PROTOCOL_ID,
+        __version: PROTOCOL_VERSION,
+        kind: "push",
+        type: "CONTEXT_PUSH",
+        payload: ctx
+      };
+      source.postMessage(message, origin);
+      this.pushPostHog(source, origin);
+    } catch (err) {
+      console.error("[vibe-host] getContext threw during connect \u2014 context not delivered.", err);
+    }
   }
   /**
    * Concrete origins a proactive push may target: the exact allowlist entries
-   * plus any origins seen on validated inbound messages. Never includes glob
-   * patterns (you cannot `postMessage` to one). When only exact origins are
-   * configured this equals the configured set, so behaviour is unchanged.
+   * plus the connected iframe's learned origin. Never includes glob patterns
+   * (you cannot `postMessage` to one). When only exact origins are configured
+   * this equals the configured set, so behaviour is unchanged.
    */
   concreteTargets() {
-    return /* @__PURE__ */ new Set([...this.exactOrigins, ...this.connectedOrigins]);
+    const targets = new Set(this.exactOrigins);
+    if (this.connectedOrigin) targets.add(this.connectedOrigin);
+    return targets;
   }
   async handleRequest(msg, source, origin) {
     const { requestId, type } = msg;
-    if (type === "GET_CONTEXT") {
-      try {
-        const ctx = { ...this.getContext(), hostVersion: version };
-        if (!this.handshakeLoggedWindows.has(source)) {
-          this.handshakeLoggedWindows.add(source);
-          const bridgeVersion = msg.payload?.bridgeVersion ?? "unknown";
-          console.log(
-            `[vibe-host] Vibe App connected \u2014 bridge: ${bridgeVersion}, host: ${version}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
-          );
-        }
-        this.respond(source, origin, { kind: "response", type, requestId, ok: true, data: ctx });
-      } catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        const code = err instanceof BridgeError ? err.code : "CONTEXT_ERROR";
-        this.respond(source, origin, { kind: "response", type, requestId, ok: false, error, code });
-      }
-      return;
-    }
     if (!checkRateLimit(this.rateLimiter)) {
       this.respond(source, origin, {
         kind: "response",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-host",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Host-side SDK for embedding Nominal Vibe Apps — receives bridge requests over a typed postMessage protocol and dispatches them to Nominal APIs (used by nom-ui).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",