@nominalso/vibe-bridge 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -38,7 +38,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.4.0";
+var version = "0.5.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -54,7 +54,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);
@@ -409,8 +409,6 @@ var CONNECT_POLL_MS = 500;
 var DEFAULT_TIMEOUTS = {
   /** Typed Nominal API reads/writes (`GET_*` / `POST_*` / `CREATE_*` / ...). */
   api: 3e4,
-  /** `GET_CONTEXT` re-fetch (the initial fetch is governed by `connect()`). */
-  context: 5e3,
   /** `INVALIDATE_CACHE`. */
   invalidate: 1e4,
   /** `UPLOAD_FILE` — large payloads + presigned S3 PUT take a while. */
@@ -423,8 +421,6 @@ function resolveRequestTimeout(type, requestTimeout) {
       return DEFAULT_TIMEOUTS.upload;
     case "INVALIDATE_CACHE":
       return DEFAULT_TIMEOUTS.invalidate;
-    case "GET_CONTEXT":
-      return DEFAULT_TIMEOUTS.context;
     default:
       return DEFAULT_TIMEOUTS.api;
   }
@@ -512,13 +508,20 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.connectPollInterval = null;
     this.connectTimeout = null;
     this.onContextReceived = null;
-    this.onContextError = null;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    this.rejectConnect = null;
     /**
-     * Request ids of the current connect()'s GET_CONTEXT polls. Used to ignore a
-     * late response from a *previous* connect attempt, which would otherwise
-     * resolve/reject the new one (a stale error could reject a healthy reconnect).
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
      */
-    this.connectPollIds = /* @__PURE__ */ new Set();
+    this.contextChangeCallback = null;
+    /**
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
+     */
+    this.authChangeCallback = null;
     this.lastReportedSubroute = null;
     this.suppressSubrouteReport = false;
     this.subrouteCallback = null;
@@ -531,7 +534,21 @@ var VibeAppBridge = class extends BridgeDataMethods {
       progress: (msg) => this.handleProgress(msg)
     };
     this.pushHandlers = {
-      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
+      CONTEXT_PUSH: (payload) => {
+        if (this.onContextReceived) {
+          this.onContextReceived(payload);
+        } else if (this.context) {
+          this.context = payload;
+          this.contextChangeCallback?.(payload);
+        }
+      },
+      // Persistent (not nulled after connect): the host delivers PostHog once at
+      // connect via its own push, and initPostHog is idempotent, so this can run
+      // whenever the message arrives, independent of how connect() resolved.
+      POSTHOG_PUSH: (payload) => this.initPostHog(payload),
+      // Persistent: the host pushes auth changes (logout, identity/tenant
+      // switch) at any time after connect.
+      AUTH_CHANGED: (payload) => this.authChangeCallback?.(payload),
       SUBROUTE_PUSH: (payload) => {
         const safe = normalizeSubroute(payload.subroute);
         if (!safe) return;
@@ -582,11 +599,11 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * methods, `upload()`, and subroute reporting all require an established
    * connection. Concurrent calls return the same promise.
    *
-   * Actively polls the host every 500ms until a response arrives, which
-   * handles the race condition where the host's initial context push arrives
-   * before this listener is ready. Rejects with `Bridge connect timed out`
-   * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
-   * or the host hasn't mounted).
+   * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+   * by pushing the context (so it works even if the host mounts after the
+   * iframe loads). Context is only ever delivered by push. Rejects with `Bridge
+   * connect timed out` after 10 seconds if no context arrives (usually a
+   * `parentOrigin` mismatch or the host hasn't mounted).
    *
    * After connecting, if the context includes an initial subroute (e.g. from
    * a deep link), the bridge navigates to it and starts auto-tracking
@@ -616,16 +633,16 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.stopConnectPolling();
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
       }, CONNECT_TIMEOUT_MS);
       this.connectTimeout = timer;
-      this.onContextError = (error) => {
+      this.rejectConnect = (error) => {
         clearTimeout(timer);
         this.stopConnectPolling();
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         reject(error);
       };
       this.onContextReceived = (ctx) => {
@@ -634,11 +651,10 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.context = ctx;
         this.connectPromise = null;
         this.onContextReceived = null;
-        this.onContextError = null;
+        this.rejectConnect = null;
         console.log(
           `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
         );
-        this.initPostHog(ctx);
         const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
         if (initialSubroute && initialSubroute !== "/") {
           this.withSubrouteSuppressed(() => {
@@ -650,23 +666,14 @@ var VibeAppBridge = class extends BridgeDataMethods {
           this.lastReportedSubroute = window.location.pathname + window.location.search;
         }
         this.setupNavigationTracking();
+        this.warnMissingListeners();
         resolve(ctx);
       };
-      const poll = () => {
-        const requestId = crypto.randomUUID();
-        this.connectPollIds.add(requestId);
-        const message = {
-          __protocol: PROTOCOL_ID,
-          __version: PROTOCOL_VERSION,
-          kind: "request",
-          type: "GET_CONTEXT",
-          requestId,
-          payload: { bridgeVersion: version }
-        };
-        this.postToParent(message);
+      const sendConnect = () => {
+        this.sendCommand("CONNECT", { bridgeVersion: version });
       };
-      poll();
-      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
+      sendConnect();
+      this.connectPollInterval = setInterval(sendConnect, CONNECT_POLL_MS);
     });
     return this.connectPromise;
   }
@@ -693,6 +700,56 @@ var VibeAppBridge = class extends BridgeDataMethods {
       this.subrouteCallback = null;
     };
   }
+  /**
+   * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+   * close, …). The callback fires for each {@link ContextPayload} the host pushes
+   * *after* connect — not for the initial context, which {@link connect} already
+   * returns. Returns an unsubscribe function. Single subscriber: a second call
+   * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+   * connect if it isn't).
+   */
+  onContextChange(callback) {
+    this.contextChangeCallback = callback;
+    return () => {
+      this.contextChangeCallback = null;
+    };
+  }
+  /**
+   * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+   * sign your backend out) or an identity/tenant switch (`authenticated: true`
+   * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+   * host pushes after connect. Returns an unsubscribe function. Single
+   * subscriber: a second call replaces the first.
+   *
+   * **Wire this before {@link connect}** — without it the embedded app won't
+   * sign out when the user logs out of Nominal (the bridge warns at connect if
+   * it isn't wired).
+   */
+  onAuthChange(callback) {
+    this.authChangeCallback = callback;
+    return () => {
+      this.authChangeCallback = null;
+    };
+  }
+  /**
+   * At connect, nudge the app if it hasn't wired the change listeners: every
+   * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+   * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+   * connect flow (not speculatively later), so wire both **before** `connect()`.
+   * The skill/codegen does this by default; this catches hand-wired apps.
+   */
+  warnMissingListeners() {
+    if (!this.authChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onAuthChange \u2014 the app will not sign out on Nominal logout or react to an identity/tenant switch. Call bridge.onAuthChange() before connect()."
+      );
+    }
+    if (!this.contextChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onContextChange \u2014 the app will not react to a tenant/subsidiary/period switch. Call bridge.onContextChange() before connect()."
+      );
+    }
+  }
   // ---------------------------------------------------------------------------
   // Host navigation & UI commands
   //
@@ -773,7 +830,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
   }
   destroy() {
     this.teardownNavigationTracking();
-    this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
+    this.rejectConnect?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
@@ -784,7 +841,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.posthogInitialized = false;
     this.connectPromise = null;
     this.onContextReceived = null;
-    this.onContextError = null;
+    this.rejectConnect = null;
+    this.contextChangeCallback = null;
+    this.authChangeCallback = null;
     this.subrouteCallback = null;
     this.lastReportedSubroute = null;
   }
@@ -797,24 +856,23 @@ var VibeAppBridge = class extends BridgeDataMethods {
       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`).
+   * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+   * (`config.enabled`).
    *
-   * The host is the single source of truth: when it sends no `posthog` 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()`.
+   * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+   * (recording disabled for this env/app) or `enabled: false`, this does
+   * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
+   * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
+   * sides so the parent receives the iframe's rrweb frames into one stitched
+   * recording, and `identify()` ties the iframe's recording + events to the same
+   * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
+   * in try/catch so a duplicate push or a PostHog failure is harmless.
    */
-  initPostHog(ctx) {
-    const config = ctx.posthog;
-    if (!config?.enabled) return;
+  initPostHog(config) {
+    if (!config.enabled) return;
     if (this.posthogInitialized) return;
     if (typeof window === "undefined") return;
     if (!config.token || !config.apiHost || !config.distinctId) {
@@ -973,15 +1031,6 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.kindHandlers[event.data.kind]?.(event.data);
   }
   handleResponse(msg) {
-    if (msg.type === "GET_CONTEXT") {
-      if (!this.connectPollIds.has(msg.requestId)) return;
-      if (msg.ok) {
-        this.onContextReceived?.(msg.data);
-      } else {
-        this.onContextError?.(new BridgeError(msg.code ?? "CONTEXT_ERROR", msg.error));
-      }
-      return;
-    }
     const pending = this.pendingRequests.get(msg.requestId);
     if (!pending) return;
     this.pendingRequests.delete(msg.requestId);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.4.0";
+var version = "0.5.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -1392,6 +1392,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;
@@ -1405,7 +1406,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;
@@ -1419,7 +1419,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;
@@ -3190,9 +3189,10 @@ interface BridgeSubsidiary {
  *
  * 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 them over the bridge so the iframe never hardcodes any of it. When
- * the host omits the {@link ContextPayload.posthog} block entirely (older host,
- * or recording disabled for this env/app), the bridge initializes nothing.
+ * 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. */
@@ -3230,6 +3230,27 @@ interface PostHogContext {
      */
     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;
@@ -3242,21 +3263,9 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
-    /**
-     * PostHog config for in-iframe session recording + custom events. **Absent
-     * when recording is off** (older host, or disabled for this env/app), in which
-     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
-     * compatible.
-     */
-    posthog?: PostHogContext;
     /** 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;
@@ -3490,10 +3499,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3748,9 +3753,9 @@ interface VibeAppBridgeOptions {
      *
      * When omitted, each operation uses an operation-specific default tuned to
      * how long it realistically takes (API reads `30000`, `UPLOAD_FILE`
-     * `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`). Setting this
-     * overrides all of them with a single value — only do that if you have a
-     * specific reason; the defaults already match the host's expectations.
+     * `120000`, `INVALIDATE_CACHE` `10000`). Setting this overrides all of them
+     * with a single value — only do that if you have a specific reason; the
+     * defaults already match the host's expectations.
      */
     requestTimeout?: number;
 }
@@ -3796,13 +3801,20 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private connectPollInterval;
     private connectTimeout;
     private onContextReceived;
-    private onContextError;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    private rejectConnect;
+    /**
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
+     */
+    private contextChangeCallback;
     /**
-     * Request ids of the current connect()'s GET_CONTEXT polls. Used to ignore a
-     * late response from a *previous* connect attempt, which would otherwise
-     * resolve/reject the new one (a stale error could reject a healthy reconnect).
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
      */
-    private readonly connectPollIds;
+    private authChangeCallback;
     private lastReportedSubroute;
     private suppressSubrouteReport;
     private subrouteCallback;
@@ -3819,11 +3831,11 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * methods, `upload()`, and subroute reporting all require an established
      * connection. Concurrent calls return the same promise.
      *
-     * Actively polls the host every 500ms until a response arrives, which
-     * handles the race condition where the host's initial context push arrives
-     * before this listener is ready. Rejects with `Bridge connect timed out`
-     * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
-     * or the host hasn't mounted).
+     * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+     * by pushing the context (so it works even if the host mounts after the
+     * iframe loads). Context is only ever delivered by push. Rejects with `Bridge
+     * connect timed out` after 10 seconds if no context arrives (usually a
+     * `parentOrigin` mismatch or the host hasn't mounted).
      *
      * After connecting, if the context includes an initial subroute (e.g. from
      * a deep link), the bridge navigates to it and starts auto-tracking
@@ -3853,6 +3865,35 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * Returns an unsubscribe function.
      */
     onSubrouteRequest(callback: (subroute: string) => void): () => void;
+    /**
+     * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+     * close, …). The callback fires for each {@link ContextPayload} the host pushes
+     * *after* connect — not for the initial context, which {@link connect} already
+     * returns. Returns an unsubscribe function. Single subscriber: a second call
+     * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+     * connect if it isn't).
+     */
+    onContextChange(callback: (ctx: ContextPayload) => void): () => void;
+    /**
+     * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+     * sign your backend out) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+     * host pushes after connect. Returns an unsubscribe function. Single
+     * subscriber: a second call replaces the first.
+     *
+     * **Wire this before {@link connect}** — without it the embedded app won't
+     * sign out when the user logs out of Nominal (the bridge warns at connect if
+     * it isn't wired).
+     */
+    onAuthChange(callback: (auth: AuthPayload) => void): () => void;
+    /**
+     * At connect, nudge the app if it hasn't wired the change listeners: every
+     * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+     * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+     * connect flow (not speculatively later), so wire both **before** `connect()`.
+     * The skill/codegen does this by default; this catches hand-wired apps.
+     */
+    private warnMissingListeners;
     /**
      * Navigates the host to a raw path relative to this app's tenant/subsidiary
      * base. Fire-and-forget.
@@ -3931,16 +3972,17 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private stopConnectPolling;
     /**
      * Initializes PostHog session recording + analytics from the host-supplied
-     * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+     * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+     * (`config.enabled`).
      *
-     * The host is the single source of truth: when it sends no `posthog` 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()`.
+     * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+     * (recording disabled for this env/app) or `enabled: false`, this does
+     * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
+     * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
+     * sides so the parent receives the iframe's rrweb frames into one stitched
+     * recording, and `identify()` ties the iframe's recording + events to the same
+     * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
+     * in try/catch so a duplicate push or a PostHog failure is harmless.
      */
     private initPostHog;
     /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-var version = "0.4.0";
+var version = "0.5.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -1392,6 +1392,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;
@@ -1405,7 +1406,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;
@@ -1419,7 +1419,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;
@@ -3190,9 +3189,10 @@ interface BridgeSubsidiary {
  *
  * 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 them over the bridge so the iframe never hardcodes any of it. When
- * the host omits the {@link ContextPayload.posthog} block entirely (older host,
- * or recording disabled for this env/app), the bridge initializes nothing.
+ * 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. */
@@ -3230,6 +3230,27 @@ interface PostHogContext {
      */
     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;
@@ -3242,21 +3263,9 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
-    /**
-     * PostHog config for in-iframe session recording + custom events. **Absent
-     * when recording is off** (older host, or disabled for this env/app), in which
-     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
-     * compatible.
-     */
-    posthog?: PostHogContext;
     /** 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;
@@ -3490,10 +3499,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3748,9 +3753,9 @@ interface VibeAppBridgeOptions {
      *
      * When omitted, each operation uses an operation-specific default tuned to
      * how long it realistically takes (API reads `30000`, `UPLOAD_FILE`
-     * `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`). Setting this
-     * overrides all of them with a single value — only do that if you have a
-     * specific reason; the defaults already match the host's expectations.
+     * `120000`, `INVALIDATE_CACHE` `10000`). Setting this overrides all of them
+     * with a single value — only do that if you have a specific reason; the
+     * defaults already match the host's expectations.
      */
     requestTimeout?: number;
 }
@@ -3796,13 +3801,20 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private connectPollInterval;
     private connectTimeout;
     private onContextReceived;
-    private onContextError;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    private rejectConnect;
+    /**
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
+     */
+    private contextChangeCallback;
     /**
-     * Request ids of the current connect()'s GET_CONTEXT polls. Used to ignore a
-     * late response from a *previous* connect attempt, which would otherwise
-     * resolve/reject the new one (a stale error could reject a healthy reconnect).
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
      */
-    private readonly connectPollIds;
+    private authChangeCallback;
     private lastReportedSubroute;
     private suppressSubrouteReport;
     private subrouteCallback;
@@ -3819,11 +3831,11 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * methods, `upload()`, and subroute reporting all require an established
      * connection. Concurrent calls return the same promise.
      *
-     * Actively polls the host every 500ms until a response arrives, which
-     * handles the race condition where the host's initial context push arrives
-     * before this listener is ready. Rejects with `Bridge connect timed out`
-     * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
-     * or the host hasn't mounted).
+     * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+     * by pushing the context (so it works even if the host mounts after the
+     * iframe loads). Context is only ever delivered by push. Rejects with `Bridge
+     * connect timed out` after 10 seconds if no context arrives (usually a
+     * `parentOrigin` mismatch or the host hasn't mounted).
      *
      * After connecting, if the context includes an initial subroute (e.g. from
      * a deep link), the bridge navigates to it and starts auto-tracking
@@ -3853,6 +3865,35 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * Returns an unsubscribe function.
      */
     onSubrouteRequest(callback: (subroute: string) => void): () => void;
+    /**
+     * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+     * close, …). The callback fires for each {@link ContextPayload} the host pushes
+     * *after* connect — not for the initial context, which {@link connect} already
+     * returns. Returns an unsubscribe function. Single subscriber: a second call
+     * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+     * connect if it isn't).
+     */
+    onContextChange(callback: (ctx: ContextPayload) => void): () => void;
+    /**
+     * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+     * sign your backend out) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+     * host pushes after connect. Returns an unsubscribe function. Single
+     * subscriber: a second call replaces the first.
+     *
+     * **Wire this before {@link connect}** — without it the embedded app won't
+     * sign out when the user logs out of Nominal (the bridge warns at connect if
+     * it isn't wired).
+     */
+    onAuthChange(callback: (auth: AuthPayload) => void): () => void;
+    /**
+     * At connect, nudge the app if it hasn't wired the change listeners: every
+     * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+     * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+     * connect flow (not speculatively later), so wire both **before** `connect()`.
+     * The skill/codegen does this by default; this catches hand-wired apps.
+     */
+    private warnMissingListeners;
     /**
      * Navigates the host to a raw path relative to this app's tenant/subsidiary
      * base. Fire-and-forget.
@@ -3931,16 +3972,17 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private stopConnectPolling;
     /**
      * Initializes PostHog session recording + analytics from the host-supplied
-     * config, **only when the host opted in** (`ctx.posthog?.enabled`).
+     * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+     * (`config.enabled`).
      *
-     * The host is the single source of truth: when it sends no `posthog` 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()`.
+     * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+     * (recording disabled for this env/app) or `enabled: false`, this does
+     * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
+     * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
+     * sides so the parent receives the iframe's rrweb frames into one stitched
+     * recording, and `identify()` ties the iframe's recording + events to the same
+     * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
+     * in try/catch so a duplicate push or a PostHog failure is harmless.
      */
     private initPostHog;
     /**

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Iframe-side SDK for building Nominal Vibe Apps — connects an embedded app to its Nominal host over a typed postMessage bridge (context, data fetch, file upload, subroute deep-linking).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",