@nominalso/vibe-host 0.4.0 → 0.5.1

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.4.0";
+var version = "0.5.1";
 
 // ../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);
@@ -58,20 +58,46 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:BridgeError");
+var HTTP_BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:HttpBridgeError");
 var BridgeError = class extends Error {
   constructor(code, message) {
     super(message);
     this.code = code;
     this.name = "BridgeError";
   }
+  /**
+   * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+   * an error may have been thrown by a differently-built copy of the SDK (e.g.
+   * server bundle vs client bundle) — it matches on a process-global brand
+   * rather than class identity.
+   */
+  static isBridgeError(err) {
+    return typeof err === "object" && err !== null && err[BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(BridgeError.prototype, BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 var HttpBridgeError = class extends BridgeError {
   constructor(status, message) {
     super("REQUEST_FAILED", message);
     this.status = status;
     this.name = "HttpBridgeError";
   }
+  /**
+   * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+   * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+   */
+  static isHttpBridgeError(err) {
+    return typeof err === "object" && err !== null && err[HTTP_BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(HttpBridgeError.prototype, HTTP_BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 function isOriginPattern(entry) {
   return entry.includes("*");
 }
@@ -657,18 +683,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 +705,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 +718,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 +765,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.
    */
-  pushContextTo(iframeWindow) {
-    this.iframeWindow = iframeWindow;
-    this.pushContext(iframeWindow);
+  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").
+   */
+  notifyAuthChange(auth) {
+    if (!this.connectedWindow) return;
+    this.pushToIframe("AUTH_CHANGED", auth);
   }
   pushContext(target) {
     const message = {
@@ -774,14 +814,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 +830,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",