@nominalso/vibe-bridge 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,7 +1,19 @@
 // package.json
-var version = "0.1.0";
+var version = "0.3.0";
 
 // ../protocol-types/dist/index.js
+function normalizeSubroute(subroute) {
+  const normalized = subroute.startsWith("/") ? subroute : `/${subroute}`;
+  const path = normalized.split(/[?#]/)[0];
+  let decoded = path;
+  let prev;
+  do {
+    prev = decoded;
+    decoded = decoded.replace(/%25/gi, "%").replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  } while (decoded !== prev);
+  if (decoded.split("/").some((segment) => segment === "..")) return null;
+  return normalized;
+}
 var PROTOCOL_ID = "nominal-vibe-bridge";
 var PROTOCOL_VERSION = 1;
 var BRIDGE_KINDS = ["request", "response", "push", "command", "progress"];
@@ -18,119 +30,50 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
-
-// src/VibeAppBridge.ts
-var CONNECT_TIMEOUT_MS = 1e4;
-var CONNECT_POLL_MS = 500;
-var VibeAppBridge = class {
-  constructor({ parentOrigin, requestTimeout = 1e4 }) {
-    this.pendingRequests = /* @__PURE__ */ new Map();
-    this.context = null;
-    this.connectPromise = null;
-    this.connectPollInterval = null;
-    this.onContextReceived = null;
-    this.lastReportedSubroute = null;
-    this.suppressSubrouteReport = false;
-    this.subrouteCallback = null;
-    this.origPushState = null;
-    this.origReplaceState = null;
-    this.popstateHandler = null;
-    this.kindHandlers = {
-      response: (msg) => this.handleResponse(msg),
-      push: (msg) => this.dispatchPush(msg),
-      progress: (msg) => this.handleProgress(msg)
-    };
-    this.pushHandlers = {
-      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
-      SUBROUTE_PUSH: (payload) => this.withSubrouteSuppressed(() => {
-        if (this.subrouteCallback) {
-          this.subrouteCallback(payload.subroute);
-        } else {
-          history.pushState(null, "", payload.subroute);
-          window.dispatchEvent(new PopStateEvent("popstate"));
-        }
-        this.lastReportedSubroute = payload.subroute;
-      })
-    };
-    this.parentOrigin = parentOrigin;
-    this.requestTimeout = requestTimeout;
-    this.boundHandleMessage = this.handleMessage.bind(this);
-    window.addEventListener("message", this.boundHandleMessage);
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
   }
-  dispatchPush(msg) {
-    const handler = this.pushHandlers[msg.type];
-    handler(msg.payload);
+};
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
   }
-  /**
-   * Connects to the host and returns the tenant/user {@link ContextPayload}.
-   * **Call this once on app init and await it before any other method** — data
-   * 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).
-   *
-   * After connecting, if the context includes an initial subroute (e.g. from
-   * a deep link), the bridge navigates to it and starts auto-tracking
-   * internal navigation via the history API.
-   *
-   * @returns The tenant/user/subsidiary context for this app session.
-   * @throws If no context is received within 10 seconds.
-   * @example
-   * ```ts
-   * const ctx = await bridge.connect()
-   * // ctx.tenant, ctx.subsidiaryId, ctx.subsidiaries, ctx.user, ctx.lastClosedPeriodSlug
-   * ```
-   */
-  connect() {
-    if (this.context) return Promise.resolve(this.context);
-    if (this.connectPromise) return this.connectPromise;
-    this.connectPromise = new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.stopConnectPolling();
-        this.connectPromise = null;
-        reject(new Error("Bridge connect timed out"));
-      }, CONNECT_TIMEOUT_MS);
-      this.onContextReceived = (ctx) => {
-        clearTimeout(timer);
-        this.stopConnectPolling();
-        this.context = ctx;
-        this.connectPromise = null;
-        this.onContextReceived = null;
-        console.log(
-          `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
-        );
-        if (ctx.subroute && ctx.subroute !== "/") {
-          this.withSubrouteSuppressed(() => {
-            history.replaceState(null, "", ctx.subroute);
-            window.dispatchEvent(new PopStateEvent("popstate"));
-            this.lastReportedSubroute = ctx.subroute;
-          });
-        } else {
-          this.lastReportedSubroute = window.location.pathname + window.location.search;
-        }
-        this.setupNavigationTracking();
-        resolve(ctx);
-      };
-      const poll = () => {
-        const message = {
-          __protocol: PROTOCOL_ID,
-          __version: PROTOCOL_VERSION,
-          kind: "request",
-          type: "GET_CONTEXT",
-          requestId: crypto.randomUUID(),
-          payload: { bridgeVersion: version }
-        };
-        window.parent.postMessage(message, this.parentOrigin);
-      };
-      poll();
-      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
-    });
-    return this.connectPromise;
+};
+function isOriginPattern(entry) {
+  return entry.includes("*");
+}
+var patternCache = /* @__PURE__ */ new Map();
+function patternToRegExp(pattern) {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = escaped.replace(/\\\*/g, "[^./:@?#\\s]+");
+  const compiled = new RegExp(`^${body}$`);
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+function matchesOrigin(origin, entry) {
+  if (!isOriginPattern(entry)) return origin === entry;
+  return patternToRegExp(entry).test(origin);
+}
+function isOriginAllowed(origin, allowlist, { allowPatterns }) {
+  for (const entry of allowlist) {
+    if (isOriginPattern(entry)) {
+      if (allowPatterns && matchesOrigin(origin, entry)) return true;
+    } else if (origin === entry) {
+      return true;
+    }
   }
+  return false;
+}
+
+// src/data-methods.ts
+var BridgeDataMethods = class {
   // ---------------------------------------------------------------------------
   // Operations — Accounting: chart of accounts
   //
@@ -416,13 +359,268 @@ var VibeAppBridge = class {
     const onProgress = options.onProgress ? (p) => options.onProgress(p) : void 0;
     return this.request("UPLOAD_FILE", payload, onProgress);
   }
+};
+
+// src/timeouts.ts
+var CONNECT_TIMEOUT_MS = 1e4;
+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. */
+  upload: 12e4
+};
+function resolveRequestTimeout(type, requestTimeout) {
+  if (requestTimeout !== void 0) return requestTimeout;
+  switch (type) {
+    case "UPLOAD_FILE":
+      return DEFAULT_TIMEOUTS.upload;
+    case "INVALIDATE_CACHE":
+      return DEFAULT_TIMEOUTS.invalidate;
+    case "GET_CONTEXT":
+      return DEFAULT_TIMEOUTS.context;
+    default:
+      return DEFAULT_TIMEOUTS.api;
+  }
+}
+
+// src/VibeAppBridge.ts
+var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
+var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
+function isPreviewSelfHost(hostname) {
+  return PREVIEW_HOST_RE.test(hostname);
+}
+function resolveActualParentOrigin() {
+  if (typeof window === "undefined") return null;
+  try {
+    const ancestors = window.location.ancestorOrigins;
+    if (ancestors && ancestors.length > 0 && ancestors[0]) return ancestors[0];
+  } catch {
+  }
+  try {
+    if (document.referrer) return new URL(document.referrer).origin;
+  } catch {
+  }
+  return null;
+}
+function resolveOriginPolicy(configured) {
+  if (typeof window !== "undefined") {
+    const override = window[PARENT_ORIGIN_OVERRIDE_KEY];
+    if (typeof override === "string" && override.length > 0) {
+      console.log(`[vibe-bridge] Using dev-bridge parentOrigin override: ${override}`);
+      return { targetOrigin: override, isTrusted: (o) => o === override };
+    }
+  }
+  const rawList = configured === void 0 ? [] : Array.isArray(configured) ? configured : [configured];
+  const allowlist = rawList.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (allowlist.length === 0) {
+    const actual2 = resolveActualParentOrigin();
+    if (actual2) return { targetOrigin: actual2, isTrusted: (o) => o === actual2 };
+    console.warn(
+      "[vibe-bridge] No `parentOrigin` set and the embedding host could not be auto-detected (no ancestorOrigins/referrer). Pass `parentOrigin` explicitly."
+    );
+    return { targetOrigin: null, isTrusted: () => false };
+  }
+  const exactEntries = allowlist.filter((entry) => !isOriginPattern(entry));
+  const hasPatterns = exactEntries.length !== allowlist.length;
+  if (allowlist.length === 1 && !hasPatterns) {
+    const only = allowlist[0];
+    return { targetOrigin: only, isTrusted: (o) => o === only };
+  }
+  const allowPatterns = hasPatterns && typeof window !== "undefined" && isPreviewSelfHost(window.location.hostname);
+  const isTrusted = (o) => isOriginAllowed(o, allowlist, { allowPatterns });
+  const actual = resolveActualParentOrigin();
+  let targetOrigin = null;
+  if (actual && isTrusted(actual)) {
+    targetOrigin = actual;
+  } else if (actual === null && !allowPatterns && exactEntries.length === 1) {
+    targetOrigin = exactEntries[0];
+  }
+  if (targetOrigin === null) {
+    console.warn(
+      "[vibe-bridge] Could not resolve a parent origin to post to. Check `parentOrigin` against the embedding host" + (hasPatterns && !allowPatterns ? " \u2014 pattern entries are ignored because this page is not served from a recognised preview host." : ".")
+    );
+  }
+  return { targetOrigin, isTrusted };
+}
+var VibeAppBridge = class extends BridgeDataMethods {
+  constructor({ parentOrigin, requestTimeout } = {}) {
+    super();
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.context = null;
+    this.connectPromise = null;
+    this.connectPollInterval = null;
+    this.connectTimeout = null;
+    this.onContextReceived = null;
+    this.onContextError = 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).
+     */
+    this.connectPollIds = /* @__PURE__ */ new Set();
+    this.lastReportedSubroute = null;
+    this.suppressSubrouteReport = false;
+    this.subrouteCallback = null;
+    this.origPushState = null;
+    this.origReplaceState = null;
+    this.popstateHandler = null;
+    this.kindHandlers = {
+      response: (msg) => this.handleResponse(msg),
+      push: (msg) => this.dispatchPush(msg),
+      progress: (msg) => this.handleProgress(msg)
+    };
+    this.pushHandlers = {
+      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
+      SUBROUTE_PUSH: (payload) => {
+        const safe = normalizeSubroute(payload.subroute);
+        if (!safe) return;
+        this.withSubrouteSuppressed(() => {
+          if (this.subrouteCallback) {
+            this.subrouteCallback(safe);
+          } else {
+            history.pushState(null, "", safe);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+          }
+          this.lastReportedSubroute = safe;
+        });
+      }
+    };
+    /**
+     * Commands targeting the host's UI chrome. All fire-and-forget.
+     *
+     * @example
+     * ```ts
+     * bridge.ui.setSideNav({ collapsed: true })
+     * bridge.ui.switchSubsidiary(42)
+     * ```
+     */
+    this.ui = {
+      /** Collapse or expand the host's side navigation. */
+      setSideNav: (payload) => {
+        this.sendCommand("SET_SIDE_NAV", payload);
+      },
+      /** Switch the host to a different subsidiary. */
+      switchSubsidiary: (subsidiaryId) => {
+        this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
+      }
+    };
+    const policy = resolveOriginPolicy(parentOrigin);
+    this.targetOrigin = policy.targetOrigin;
+    this.isTrustedOrigin = policy.isTrusted;
+    this.requestTimeout = requestTimeout;
+    this.boundHandleMessage = this.handleMessage.bind(this);
+    window.addEventListener("message", this.boundHandleMessage);
+  }
+  dispatchPush(msg) {
+    const handler = this.pushHandlers[msg.type];
+    handler(msg.payload);
+  }
+  /**
+   * Connects to the host and returns the tenant/user {@link ContextPayload}.
+   * **Call this once on app init and await it before any other method** — data
+   * 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).
+   *
+   * After connecting, if the context includes an initial subroute (e.g. from
+   * a deep link), the bridge navigates to it and starts auto-tracking
+   * internal navigation via the history API.
+   *
+   * @returns The tenant/user/subsidiary context for this app session.
+   * @throws If no context is received within 10 seconds.
+   * @example
+   * ```ts
+   * const ctx = await bridge.connect()
+   * // ctx.tenant, ctx.subsidiaryId, ctx.subsidiaries, ctx.user, ctx.lastClosedPeriodSlug
+   * ```
+   */
+  connect() {
+    if (this.context) return Promise.resolve(this.context);
+    if (this.connectPromise) return this.connectPromise;
+    if (this.targetOrigin === null) {
+      return Promise.reject(
+        new BridgeError(
+          "PARENT_ORIGIN_UNRESOLVED",
+          "Could not resolve a parent origin to connect to. Check `parentOrigin` against the embedding host."
+        )
+      );
+    }
+    this.connectPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
+      }, CONNECT_TIMEOUT_MS);
+      this.connectTimeout = timer;
+      this.onContextError = (error) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        reject(error);
+      };
+      this.onContextReceived = (ctx) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.context = ctx;
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        console.log(
+          `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
+        );
+        const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
+        if (initialSubroute && initialSubroute !== "/") {
+          this.withSubrouteSuppressed(() => {
+            history.replaceState(null, "", initialSubroute);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+            this.lastReportedSubroute = initialSubroute;
+          });
+        } else {
+          this.lastReportedSubroute = window.location.pathname + window.location.search;
+        }
+        this.setupNavigationTracking();
+        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);
+      };
+      poll();
+      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
+    });
+    return this.connectPromise;
+  }
   /**
    * Manually reports the current subroute to the host.
    * Usually not needed — navigation is auto-detected via the history API.
    * Use this for hash-based routers or non-standard navigation patterns.
    */
   reportSubroute(subroute, options) {
-    const normalized = subroute.startsWith("/") ? subroute : `/${subroute}`;
+    const normalized = normalizeSubroute(subroute);
+    if (normalized === null) return;
     this.lastReportedSubroute = normalized;
     this.sendCommand("REPORT_SUBROUTE", { subroute: normalized, replace: options?.replace });
   }
@@ -438,17 +636,69 @@ var VibeAppBridge = class {
       this.subrouteCallback = null;
     };
   }
+  // ---------------------------------------------------------------------------
+  // Host navigation & UI commands
+  //
+  // These drive the *host* (nom-ui) chrome — its router, side nav, and
+  // subsidiary switcher — rather than the iframe's own internal routing
+  // (`reportSubroute`). Navigation/UI commands are fire-and-forget;
+  // `invalidateCache` is awaited.
+  // ---------------------------------------------------------------------------
+  /**
+   * Navigates the host to a raw path relative to this app's tenant/subsidiary
+   * base. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigate('/journal-entries/123')
+   * bridge.navigate('/journal-entries/123', 'replace')
+   * ```
+   */
+  navigate(path, action = "push") {
+    this.sendCommand("NAVIGATE", { path, action });
+  }
+  /**
+   * Navigates the host to a named Nominal route, with optional params for
+   * placeholder segments. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigateTo('CHART_OF_ACCOUNTS')
+   * bridge.navigateTo('JOURNAL_ENTRY', { id: '123' }, 'replace')
+   * ```
+   */
+  navigateTo(route, routeParams, action = "push") {
+    this.sendCommand("NAVIGATE", { route, routeParams, action });
+  }
+  /** Refreshes the host's current route (re-fetches its server data). Fire-and-forget. */
+  refresh() {
+    this.sendCommand("NAVIGATE", { action: "refresh" });
+  }
+  /**
+   * Asks the host to invalidate cached data by path prefix and/or cache tag so
+   * subsequent reads see fresh values. Awaited.
+   *
+   * @example
+   * ```ts
+   * await bridge.invalidateCache({ tags: ['SUBSIDIARIES'], paths: ['/accounting/accounts'] })
+   * ```
+   */
+  invalidateCache(payload) {
+    return this.request("INVALIDATE_CACHE", payload);
+  }
   destroy() {
     this.teardownNavigationTracking();
+    this.onContextError?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
-      pending.reject(new Error("Bridge destroyed"));
+      pending.reject(new BridgeError("DESTROYED", "Bridge destroyed"));
     }
     this.pendingRequests.clear();
     this.context = null;
     this.connectPromise = null;
     this.onContextReceived = null;
+    this.onContextError = null;
     this.subrouteCallback = null;
     this.lastReportedSubroute = null;
   }
@@ -457,6 +707,11 @@ var VibeAppBridge = class {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    if (this.connectTimeout !== null) {
+      clearTimeout(this.connectTimeout);
+      this.connectTimeout = null;
+    }
+    this.connectPollIds.clear();
   }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
@@ -505,16 +760,20 @@ var VibeAppBridge = class {
   }
   reportCurrentSubroute(replace) {
     if (this.suppressSubrouteReport) return;
-    const subroute = window.location.pathname + window.location.search;
+    const subroute = normalizeSubroute(window.location.pathname + window.location.search);
+    if (subroute === null) return;
     if (subroute === this.lastReportedSubroute) return;
     this.lastReportedSubroute = subroute;
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
   }
   sendCommand(type, payload) {
-    window.parent.postMessage(
-      { __protocol: PROTOCOL_ID, __version: PROTOCOL_VERSION, kind: "command", type, payload },
-      this.parentOrigin
-    );
+    this.postToParent({
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "command",
+      type,
+      payload
+    });
   }
   /**
    * Low-level typed request for **any** operation in {@link RequestRegistry}.
@@ -531,10 +790,13 @@ var VibeAppBridge = class {
   request(type, payload, onProgress) {
     return new Promise((resolve, reject) => {
       const requestId = crypto.randomUUID();
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(requestId);
-        reject(new Error(`Vibe bridge request timed out: ${type}`));
-      }, this.requestTimeout);
+      const timer = setTimeout(
+        () => {
+          this.pendingRequests.delete(requestId);
+          reject(new BridgeError("TIMEOUT", `Vibe bridge request timed out: ${type}`));
+        },
+        resolveRequestTimeout(type, this.requestTimeout)
+      );
       this.pendingRequests.set(requestId, {
         resolve: (data) => {
           clearTimeout(timer);
@@ -554,17 +816,31 @@ var VibeAppBridge = class {
         requestId,
         payload
       };
-      window.parent.postMessage(message, this.parentOrigin);
+      this.postToParent(message);
     });
   }
+  /**
+   * Posts to the embedding host. No-op when no concrete target origin could be
+   * resolved (a config/embedding error) — `connect()` rejects fast in that case
+   * so calls never silently hang waiting on a timeout.
+   */
+  postToParent(message) {
+    if (this.targetOrigin === null) return;
+    window.parent.postMessage(message, this.targetOrigin);
+  }
   handleMessage(event) {
-    if (event.origin !== this.parentOrigin) return;
+    if (!this.isTrustedOrigin(event.origin)) return;
     if (!isBridgeMessage(event.data)) return;
     this.kindHandlers[event.data.kind]?.(event.data);
   }
   handleResponse(msg) {
     if (msg.type === "GET_CONTEXT") {
-      if (msg.ok) this.onContextReceived?.(msg.data);
+      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);
@@ -572,6 +848,10 @@ var VibeAppBridge = class {
     this.pendingRequests.delete(msg.requestId);
     if (msg.ok) {
       pending.resolve(msg.data);
+    } else if (msg.status !== void 0) {
+      pending.reject(new HttpBridgeError(msg.status, msg.error));
+    } else if (msg.code) {
+      pending.reject(new BridgeError(msg.code, msg.error));
     } else {
       pending.reject(new Error(msg.error));
     }
@@ -583,5 +863,7 @@ var VibeAppBridge = class {
 };
 export {
   version as BRIDGE_VERSION,
+  BridgeError,
+  HttpBridgeError,
   VibeAppBridge
 };

package/docs/connect-lifecycle.md

@@ -32,9 +32,9 @@ The host pushes context to the iframe on load, but the iframe's listener may not
 2. The host responds as soon as its listener is mounted, **or** proactively pushes `CONTEXT_PUSH` once it has the iframe's window.
 3. Whichever arrives first resolves `connect()`. Polling stops.
 4. The bridge begins auto-tracking SPA navigation (see below).
-5. If nothing arrives within **10 seconds**, `connect()` rejects with `Bridge connect timed out`.
+5. If nothing arrives within **10 seconds**, `connect()` rejects with a `BridgeError` (code `'TIMEOUT'`, message `Bridge connect timed out`).
 
-A timeout almost always means a `parentOrigin` mismatch or the host never mounted.
+A timeout almost always means a `parentOrigin` mismatch or the host never mounted. A separate, immediate rejection — `BridgeError` code `PARENT_ORIGIN_UNRESOLVED` — means no concrete parent origin could be resolved at all (e.g. a pattern-only `parentOrigin` on a non-preview host); fix `parentOrigin` rather than waiting on the timeout.
 
 ## Initial deep link
 
@@ -53,4 +53,4 @@ After connecting, the bridge monkey-patches `history.pushState`/`replaceState` t
 bridge.destroy()
 ```
 
-Removes listeners, rejects pending requests with `Bridge destroyed`, and restores the original history methods. Call it on unmount.
+Removes listeners, rejects any pending requests with a `BridgeError` (code `'DESTROYED'`, message `Bridge destroyed`), and restores the original history methods. Call it on unmount.

package/docs/data-fetching.md

@@ -39,15 +39,20 @@ Vibe Apps never write Nominal data directly; everything else is read-only.
 
 ## Errors & timeouts
 
-- A rejected operation throws an `Error` whose `message` is the host's error string. Wrap calls in `try/catch`.
-- Requests time out after `requestTimeout` ms (default 10 000) with `Vibe bridge request timed out: <OPERATION>`. Override per-bridge: `new VibeAppBridge({ parentOrigin, requestTimeout: 30000 })`.
+- A rejected operation throws a `BridgeError` (`extends Error`) carrying a machine-readable `code` (e.g. `'RATE_LIMITED'`, `'FILE_TOO_LARGE'`, `'TIMEOUT'`) alongside the host's `message`. Branch on `error.code` rather than string-matching the message. (A failure the host sends without a code falls back to a plain `Error`.) A failed Nominal API call throws the `HttpBridgeError` subtype (`code: 'REQUEST_FAILED'`), which adds the HTTP `status` — branch on `err.status` (e.g. `404`).
+- Each operation times out on a default tuned to how long it realistically takes: API reads/writes **30 000 ms**, `UPLOAD_FILE` **120 000 ms**, `INVALIDATE_CACHE` **10 000 ms**, `GET_CONTEXT` **5 000 ms**. On timeout the call rejects with a `BridgeError` whose `code` is `'TIMEOUT'` (message `Vibe bridge request timed out: <OPERATION>`). Override all of them with one value via `new VibeAppBridge({ parentOrigin, requestTimeout: 45000 })`.
 
 ```ts
+import { BridgeError } from '@nominalso/vibe-bridge'
+
 try {
   const entry = await bridge.getJournalEntry({
     path: { subsidiary_id: ctx.subsidiaryId, journal_entry_id: '42' },
   })
 } catch (err) {
+  if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+    // back off and retry
+  }
   console.error('Fetch failed:', err instanceof Error ? err.message : err)
 }
 ```