@nominalso/vibe-host 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -20,14 +20,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BridgeError: () => BridgeError,
+  HttpBridgeError: () => HttpBridgeError,
   VibeAppHost: () => VibeAppHost
 });
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.1.0";
+var version = "0.2.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"];
@@ -44,6 +58,20 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
+  }
+};
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
+  }
+};
 
 // ../api-client/dist/index.js
 var import_client_fetch = require("@hey-api/client-fetch");
@@ -375,10 +403,6 @@ var getSubsidiaryParentCurrenciesApiTenancySubsidiarySubsidiaryIdParentCurrencie
 };
 function createVibeApiClient({ baseUrl, stripApiPrefix }) {
   const client2 = (0, import_client_fetch2.createClient)((0, import_client_fetch2.createConfig)({ baseUrl }));
-  client2.interceptors.request.use((request) => {
-    console.log("[vibe-api-client] request url:", request.url);
-    return request;
-  });
   if (stripApiPrefix) {
     client2.interceptors.request.use(
       (request) => new Request(request.url.replace(`${baseUrl}/api/`, `${baseUrl}/`), request)
@@ -387,16 +411,28 @@ function createVibeApiClient({ baseUrl, stripApiPrefix }) {
   return client2;
 }
 
-// src/handlerMap.ts
+// src/handlers/call.ts
 async function call(fn, payload, client2) {
-  const { data } = await fn({ ...payload, client: client2 });
-  if (data == null) throw new Error("API returned no data");
+  const { data, response } = await fn({ ...payload, client: client2 });
+  if (data == null) {
+    if (response && !response.ok) {
+      throw new HttpBridgeError(
+        response.status,
+        `API request failed with status ${response.status}`
+      );
+    }
+    if (!response) {
+      throw new Error("API request produced no response");
+    }
+    return null;
+  }
   return data;
 }
-function createHandlerMap(options) {
-  const client2 = createVibeApiClient(options);
+
+// src/handlers/accounting.ts
+function accountingHandlers(client2) {
   return {
-    // Accounting — chart of accounts
+    // Chart of accounts
     GET_CHART_OF_ACCOUNTS: (p) => call(getCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGet, p, client2),
     GET_COA_TREE: (p) => call(getCoaTreeApiAccountingSubsidiarySubsidiaryIdCoaGet, p, client2),
     GET_COA_FLAT_SIMPLE: (p) => call(
@@ -421,7 +457,7 @@ function createHandlerMap(options) {
     ),
     GET_ACCOUNTS: (p) => call(getAccountsApiAccountingAccountGet, p, client2),
     GET_ACCOUNT: (p) => call(getAccountApiAccountingAccountAccountIdGet, p, client2),
-    // Accounting — exchange rates
+    // Exchange rates
     GET_CONVERSION_RATES: (p) => call(getConversionRateApiAccountingCurrencyCurrencyConversionRatesGet, p, client2),
     GET_EFFECTIVE_EXCHANGE_RATE: (p) => call(getEffectiveExchangeRateApiAccountingConsolidationExchangeRateGet, p, client2),
     GET_EXCHANGE_RATE_BY_DATE: (p) => call(
@@ -429,7 +465,7 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Accounting — dimensions
+    // Dimensions
     GET_DIMENSIONS: (p) => call(getDimensionsApiAccountingDimensionGet, p, client2),
     GET_DIMENSION_VALUES: (p) => call(getDimensionValuesApiAccountingDimensionValueGet, p, client2),
     GET_DIMENSION_VALUES_HIERARCHICAL: (p) => call(
@@ -442,7 +478,7 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Accounting — journal entries
+    // Journal entries
     GET_JOURNAL_ENTRIES: (p) => call(
       getSubsidiaryJournalApiAccountingSubsidiarySubsidiaryIdJournalEntryGet,
       p,
@@ -457,8 +493,14 @@ function createHandlerMap(options) {
       getJournalEntryApiAccountingSubsidiarySubsidiaryIdJournalEntryJournalEntryIdGet,
       p,
       client2
-    ),
-    // Activity — period instances
+    )
+  };
+}
+
+// src/handlers/activity.ts
+function activityHandlers(client2) {
+  return {
+    // Period instances
     GET_PERIODS: (p) => call(getPeriodInstancesApiActivityPeriodInstanceGet, p, client2),
     GET_PERIOD_INSTANCE: (p) => call(getPeriodInstanceApiActivityPeriodInstancePeriodInstanceIdGet, p, client2),
     GET_PERIOD_INSTANCE_BY_SLUG: (p) => call(
@@ -471,14 +513,14 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Activity — activity definitions
+    // Activity definitions
     GET_ACTIVITY_DEFINITIONS: (p) => call(getActivityDefinitionsApiActivityActivityDefinitionGet, p, client2),
     GET_ACTIVITY_DEFINITION: (p) => call(
       getActivityDefinitionByIdApiActivityActivityDefinitionActivityDefinitionIdGet,
       p,
       client2
     ),
-    // Activity — activity instances
+    // Activity instances
     GET_ACTIVITY_INSTANCES: (p) => call(getActivityInstancesApiActivityActivityInstanceGet, p, client2),
     GET_ACTIVITY_INSTANCE: (p) => call(getActivityInstanceApiActivityActivityInstanceActivityInstanceIdGet, p, client2),
     GET_ACTIVITY_INSTANCE_BY_PERIOD: (p) => call(
@@ -496,28 +538,43 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Activity — task definitions
+    // Task definitions
     GET_TASK_DEFINITIONS: (p) => call(getAllTasksDefinitionsApiActivityTaskDefinitionGet, p, client2),
     GET_TASK_DEFINITION: (p) => call(getTaskDefinitionByIdApiActivityTaskDefinitionTaskDefinitionIdGet, p, client2),
     CREATE_TASK_DEFINITION: (p) => call(createTaskDefinitionApiActivityTaskDefinitionPost, p, client2),
     UPDATE_TASK_DEFINITION: (p) => call(updateTaskDefinitionApiActivityTaskDefinitionTaskDefinitionIdPut, p, client2),
     GET_TASK_DEFINITIONS_BY_FILTER: (p) => call(getAllTasksDefinitionsByFilterApiActivityTaskDefinitionQueryPost, p, client2),
-    // Activity — task instances
+    // Task instances
     GET_TASK_INSTANCES: (p) => call(getAllTaskInstancesApiActivityTaskInstanceGet, p, client2),
     GET_TASK_INSTANCE: (p) => call(getTaskInstanceByIdApiActivityTaskInstanceTaskInstanceIdGet, p, client2),
     POST_TASK_OUTPUT: (p) => call(updateTaskInstanceApiActivityTaskInstanceTaskInstanceIdPut, p, client2),
-    GET_TASK_INSTANCES_BY_FILTER: (p) => call(getAllTaskInstancesByFilterApiActivityTaskInstanceQueryPost, p, client2),
-    // Audit trail
+    GET_TASK_INSTANCES_BY_FILTER: (p) => call(getAllTaskInstancesByFilterApiActivityTaskInstanceQueryPost, p, client2)
+  };
+}
+
+// src/handlers/audit-trail.ts
+function auditTrailHandlers(client2) {
+  return {
     GET_AUDIT_EVENTS: (p) => call(getEventsApiAuditTrailEventGet, p, client2),
-    GET_ENTITY_AUDIT_EVENTS: (p) => call(getEntityEventsApiAuditTrailEventEntityTargetTypeTargetIdPost, p, client2),
-    // Period manager
+    GET_ENTITY_AUDIT_EVENTS: (p) => call(getEntityEventsApiAuditTrailEventEntityTargetTypeTargetIdPost, p, client2)
+  };
+}
+
+// src/handlers/period-manager.ts
+function periodManagerHandlers(client2) {
+  return {
     GET_FISCAL_CALENDARS: (p) => call(
       getFiscalCalendarsBySubsidiaryApiPeriodManagerFiscalCalendarBySubsidiarySubsidiaryIdGet,
       p,
       client2
     ),
-    GET_FISCAL_CALENDAR: (p) => call(getFiscalCalendarByIdApiPeriodManagerFiscalCalendarCalendarIdGet, p, client2),
-    // Tenancy
+    GET_FISCAL_CALENDAR: (p) => call(getFiscalCalendarByIdApiPeriodManagerFiscalCalendarCalendarIdGet, p, client2)
+  };
+}
+
+// src/handlers/tenancy.ts
+function tenancyHandlers(client2) {
+  return {
     GET_SUBSIDIARIES: (p) => call(getAllSubsidiariesApiTenancySubsidiaryGet, p, client2),
     GET_SUBSIDIARY: (p) => call(getSubsidiaryApiTenancySubsidiarySubsidiaryIdGet, p, client2),
     GET_SUBSIDIARY_PARENT_CURRENCIES: (p) => call(
@@ -529,46 +586,115 @@ function createHandlerMap(options) {
   };
 }
 
-// src/uploadHandler.ts
-async function uploadHandler(payload, sendProgress) {
-  const attachmentId = crypto.randomUUID();
-  for (const progress of [25, 50, 75, 100]) {
-    await new Promise((r) => setTimeout(r, 400));
-    sendProgress({ attachmentId, progress });
+// src/handlerMap.ts
+function createHandlerMap(options) {
+  const client2 = createVibeApiClient(options);
+  return {
+    ...accountingHandlers(client2),
+    ...activityHandlers(client2),
+    ...auditTrailHandlers(client2),
+    ...periodManagerHandlers(client2),
+    ...tenancyHandlers(client2)
+  };
+}
+
+// src/rateLimiter.ts
+var DEFAULT_RATE_LIMIT = 60;
+function createRateLimiter(limit = DEFAULT_RATE_LIMIT, windowMs = 6e4) {
+  return { timestamps: [], limit, windowMs };
+}
+function checkRateLimit(state) {
+  const now = Date.now();
+  const cutoff = now - state.windowMs;
+  state.timestamps = state.timestamps.filter((t) => t > cutoff);
+  if (state.timestamps.length >= state.limit) {
+    return false;
   }
-  return { attachmentId, name: payload.fileName };
+  state.timestamps.push(now);
+  return true;
+}
+
+// src/unwired.ts
+function warnUnwired(command) {
+  return () => {
+    console.warn(`[vibe-host] Received "${command}" command but no handler is wired \u2014 ignoring.`);
+  };
+}
+function rejectUnwired(op) {
+  return () => Promise.reject(
+    new BridgeError("NOT_WIRED", `[vibe-host] Received "${op}" request but no handler is wired.`)
+  );
 }
 
 // src/VibeAppHost.ts
 var VibeAppHost = class {
-  constructor({ trustedOrigins, getContext, appBasePath, clientConfig }) {
+  constructor(opts) {
     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.kindHandlers = {
       request: (msg, source, origin) => this.handleRequest(msg, source, origin),
       command: (msg) => this.dispatchCommand(msg)
     };
-    this.commandHandlers = {
-      REPORT_SUBROUTE: (payload) => {
-        const newPath = payload.subroute === "/" ? this.appBasePath : `${this.appBasePath}${payload.subroute}`;
-        const method = payload.replace ? "replaceState" : "pushState";
-        window.history[method](null, "", newPath);
-      }
-    };
+    const { trustedOrigins, getContext, appBasePath, clientConfig } = opts;
     this.trustedOrigins = new Set(trustedOrigins);
     this.getContext = getContext;
     this.appBasePath = appBasePath;
+    this.onRequestComplete = opts.onRequestComplete;
+    this.rateLimiter = createRateLimiter(opts.rateLimit ?? DEFAULT_RATE_LIMIT);
     this.boundHandleMessage = this.handleMessage.bind(this);
     this.boundHandlePopState = this.handlePopState.bind(this);
-    this.handlers = this.initializeHandlers(clientConfig || { baseUrl: "", stripApiPrefix: false });
+    this.handlers = this.initializeHandlers(
+      clientConfig || { baseUrl: "", stripApiPrefix: false },
+      opts
+    );
+    this.commandHandlers = this.buildCommandHandlers(opts);
   }
   dispatchCommand(msg) {
     const handler = this.commandHandlers[msg.type];
-    handler(msg.payload);
+    if (!handler) {
+      console.warn(`[vibe-host] Received unknown command "${msg.type}" \u2014 ignoring.`);
+      return;
+    }
+    try {
+      handler(msg.payload);
+    } catch (err) {
+      console.warn(`[vibe-host] Command "${msg.type}" handler threw \u2014 ignoring.`, err);
+    }
   }
-  initializeHandlers(clientConfig) {
+  /**
+   * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+   * guard, item `l`); navigation/UI side effects are injected by the consumer,
+   * falling back to warn-and-ignore (DP4).
+   */
+  buildCommandHandlers(opts) {
+    return {
+      REPORT_SUBROUTE: (payload) => {
+        const safe = normalizeSubroute(payload.subroute);
+        if (safe === null) return;
+        const newPath = safe === "/" ? this.appBasePath : `${this.appBasePath}${safe}`;
+        const method = payload.replace ? "replaceState" : "pushState";
+        window.history[method](null, "", newPath);
+      },
+      NAVIGATE: opts.onNavigate ?? warnUnwired("NAVIGATE"),
+      SET_SIDE_NAV: opts.onSetSideNav ?? warnUnwired("SET_SIDE_NAV"),
+      SWITCH_SUBSIDIARY: opts.onSwitchSubsidiary ?? warnUnwired("SWITCH_SUBSIDIARY")
+    };
+  }
+  /**
+   * Requests: the built-in API map (hey-api), plus the injected/awaited side
+   * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+   * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+   */
+  initializeHandlers(clientConfig, opts) {
     return {
       ...createHandlerMap(clientConfig),
-      UPLOAD_FILE: uploadHandler
+      UPLOAD_FILE: opts.onUpload ?? rejectUnwired("UPLOAD_FILE"),
+      INVALIDATE_CACHE: opts.onInvalidateCache ?? (async () => ({ invalidated: false }))
     };
   }
   /**
@@ -640,12 +766,33 @@ var VibeAppHost = class {
   async handleRequest(msg, source, origin) {
     const { requestId, type } = msg;
     if (type === "GET_CONTEXT") {
-      const ctx = { ...this.getContext(), hostVersion: version };
-      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 });
+      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",
+        type,
+        requestId,
+        ok: false,
+        error: `Too many requests. Limit is ${this.rateLimiter.limit} per minute.`,
+        code: "RATE_LIMITED"
+      });
+      this.onRequestComplete?.({ type, ok: false, payload: msg.payload });
       return;
     }
     const sendProgress = (payload) => {
@@ -663,9 +810,21 @@ var VibeAppHost = class {
       const handler = this.handlers[type];
       const data = await handler(msg.payload, sendProgress);
       this.respond(source, origin, { kind: "response", type, requestId, ok: true, data });
+      this.onRequestComplete?.({ type, ok: true, payload: msg.payload });
     } catch (err) {
       const error = err instanceof Error ? err.message : String(err);
-      this.respond(source, origin, { kind: "response", type, requestId, ok: false, error });
+      const code = err instanceof BridgeError ? err.code : void 0;
+      const status = err instanceof HttpBridgeError ? err.status : void 0;
+      this.respond(source, origin, {
+        kind: "response",
+        type,
+        requestId,
+        ok: false,
+        error,
+        code,
+        status
+      });
+      this.onRequestComplete?.({ type, ok: false, payload: msg.payload });
     }
   }
   respond(target, origin, response) {
@@ -677,5 +836,7 @@ var VibeAppHost = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BridgeError,
+  HttpBridgeError,
   VibeAppHost
 });

package/dist/index.d.cts

@@ -3201,15 +3201,6 @@ interface GetContextPayload {
     bridgeVersion: string;
 }
 
-/**
- * All operations the iframe can invoke on the host, each with a typed request
- * payload and a typed response. Adding a new operation here is all that's
- * required — message union types and handler types below are derived
- * automatically.
- *
- * Operations that also emit intermediate progress events should include a
- * `progress` field with the progress payload type.
- */
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3220,11 +3211,57 @@ interface UploadPayload {
 interface UploadResponse {
     attachmentId: string;
     name: string;
+    /** Public/presigned URL of the stored file, when the host returns one. */
+    url?: string;
 }
 interface UploadProgress {
     attachmentId: string;
     progress: number;
 }
+/** How the host should apply a navigation. Defaults to `'push'`. */
+type NavigateAction = 'push' | 'replace' | 'refresh';
+/**
+ * Tells the host to navigate. Provide **either** a raw `path` (relative to the
+ * app's tenant/subsidiary base) **or** a named `route` resolved host-side.
+ */
+interface NavigatePayload {
+    /** Raw path relative to the app's base, e.g. `'/journal-entries/123'`. */
+    path?: string;
+    /** Named route key the host resolves, e.g. `'CHART_OF_ACCOUNTS'`. */
+    route?: string;
+    /** Values for route placeholders, e.g. `{ id: '123' }`. */
+    routeParams?: Record<string, string>;
+    /** Navigation method. Defaults to `'push'`. */
+    action?: NavigateAction;
+}
+/** Collapse/expand the host's side navigation. */
+interface SetSideNavPayload {
+    collapsed: boolean;
+}
+/** Switch the host to a different subsidiary. */
+interface SwitchSubsidiaryPayload {
+    subsidiaryId: number;
+}
+/** Targets for a host cache invalidation. */
+interface InvalidateCachePayload {
+    /** API path prefixes to invalidate, e.g. `['/accounting/accounts']`. */
+    paths?: string[];
+    /** Cache tag keys to invalidate, e.g. `['REPORTS', 'SUBSIDIARIES']`. */
+    tags?: string[];
+}
+/** Result of a host cache invalidation. */
+interface InvalidateResult {
+    invalidated: boolean;
+}
+
+/**
+ * All operations the iframe can invoke on the host, each with a typed request
+ * payload and a typed response. Adding a new operation here is all that's
+ * required — message union types and handler types are derived automatically.
+ *
+ * Operations that also emit intermediate progress events should include a
+ * `progress` field with the progress payload type.
+ */
 interface RequestRegistry {
     GET_CHART_OF_ACCOUNTS: {
         payload: Omit<GetCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGetData, 'url'>;
@@ -3410,6 +3447,10 @@ interface RequestRegistry {
         payload: Omit<GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetData, 'url'>;
         data: GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetResponse;
     };
+    INVALIDATE_CACHE: {
+        payload: InvalidateCachePayload;
+        data: InvalidateResult;
+    };
     GET_CONTEXT: {
         payload: GetContextPayload;
         data: ContextPayload;
@@ -3434,6 +3475,53 @@ type RequestHandlers = {
     } ? (payload: RequestRegistry[K]['payload'], sendProgress: (p: P) => void) => Promise<RequestRegistry[K]['data']> : (payload: RequestRegistry[K]['payload']) => Promise<RequestRegistry[K]['data']>;
 };
 
+/**
+ * An error that crossed the bridge, carrying a machine-readable {@link code}
+ * alongside the human-readable message.
+ *
+ * The host attaches a `code` to failed responses (e.g. `'RATE_LIMITED'`,
+ * `'FILE_TOO_LARGE'`, `'REQUEST_FAILED'`); the bridge rehydrates it into a
+ * `BridgeError` so app `catch` blocks can branch on `error.code` instead of
+ * string-matching `error.message`. A failed Nominal API call rehydrates as the
+ * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccounts({})
+ * } catch (err) {
+ *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
+ * `'REQUEST_FAILED'`; the HTTP {@link status} is carried as a structured field
+ * so callers can branch on it (e.g. `err.status === 404`) instead of parsing
+ * the code string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccount({ path: { account_id: 'missing' } })
+ * } catch (err) {
+ *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *     // handle not-found
+ *   }
+ * }
+ * ```
+ */
+declare class HttpBridgeError extends BridgeError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
 interface VibeApiClientOptions {
     baseUrl: string;
     /**
@@ -3446,6 +3534,18 @@ interface VibeApiClientOptions {
 
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
+/**
+ * Notified after each request resolves — except the `GET_CONTEXT` connect poll,
+ * which is exempt. Used by nom-ui for SWR busting (SSOT §5j).
+ */
+interface RequestCompleteInfo {
+    /** The operation type, e.g. `'POST_TASK_OUTPUT'`. */
+    type: string;
+    /** Whether the operation succeeded. */
+    ok: boolean;
+    /** The request payload that was handled. */
+    payload: unknown;
+}
 interface VibeAppHostOptions {
     /**
      * Iframe origins allowed to talk to this host. Messages from any other origin
@@ -3467,13 +3567,33 @@ interface VibeAppHostOptions {
      * `{ baseUrl: '', stripApiPrefix: false }`.
      */
     clientConfig?: VibeApiClientOptions;
+    /** Fire-and-forget. Resolve a path / named route and push to the host router. */
+    onNavigate?: (payload: NavigatePayload) => void;
+    /** Fire-and-forget. Collapse/expand the host side nav. */
+    onSetSideNav?: (payload: SetSideNavPayload) => void;
+    /** Fire-and-forget. Switch subsidiary (host owns validation + navigation). */
+    onSwitchSubsidiary?: (payload: SwitchSubsidiaryPayload) => void;
+    /** Awaited. Invalidate host cache by tags/paths. Defaults to a no-op. */
+    onInvalidateCache?: (payload: InvalidateCachePayload) => Promise<InvalidateResult>;
+    /**
+     * Awaited. Real file upload — replaces the built-in stub (DP2). When omitted,
+     * `UPLOAD_FILE` requests reject with a `'NOT_WIRED'` coded error.
+     */
+    onUpload?: (payload: UploadPayload, sendProgress: (p: UploadProgress) => void) => Promise<UploadResponse>;
+    /** Optional. Notified after each request resolves (except the `GET_CONTEXT` connect poll) — used by nom-ui for SWR busting (SSOT §5j). */
+    onRequestComplete?: (info: RequestCompleteInfo) => void;
+    /** Requests/min before a request trips `RATE_LIMITED` (DP5). Default 60. */
+    rateLimit?: number;
 }
+
 /**
  * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
  * iframe origin(s), a `getContext` callback, the app's base path, and a
  * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
- * to start listening. The handler map for all protocol operations is built
- * automatically — you do not pass handlers.
+ * to start listening. The handler map for all protocol API operations is built
+ * automatically — you do not pass those handlers. Non-API side effects
+ * (navigation, side nav, subsidiary switch, cache invalidation, upload) are
+ * supplied via the optional injected callbacks.
  *
  * @example
  * ```tsx
@@ -3483,6 +3603,8 @@ interface VibeAppHostOptions {
  *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
  *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
  *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ *   onNavigate: (p) => router.push(resolve(p)),
+ *   onUpload: (p, sendProgress) => uploadToS3(p, sendProgress),
  * })
  *
  * useEffect(() => {
@@ -3501,16 +3623,35 @@ interface VibeAppHostOptions {
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
+    private readonly commandHandlers;
     private readonly getContext;
     private readonly appBasePath;
+    private readonly onRequestComplete?;
+    private readonly rateLimiter;
     private readonly boundHandleMessage;
     private readonly boundHandlePopState;
     private iframeWindow;
+    /**
+     * Source windows we've already logged a successful handshake for. The bridge
+     * polls `GET_CONTEXT` on an interval until it connects, so without this the
+     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
+     */
+    private readonly handshakeLoggedWindows;
     private readonly kindHandlers;
     private dispatchCommand;
-    private readonly commandHandlers;
+    /**
+     * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+     * guard, item `l`); navigation/UI side effects are injected by the consumer,
+     * falling back to warn-and-ignore (DP4).
+     */
+    private buildCommandHandlers;
+    /**
+     * Requests: the built-in API map (hey-api), plus the injected/awaited side
+     * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+     * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+     */
     private initializeHandlers;
-    constructor({ trustedOrigins, getContext, appBasePath, clientConfig }: VibeAppHostOptions);
+    constructor(opts: VibeAppHostOptions);
     /**
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
@@ -3535,4 +3676,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type ContextPayload, type HostContext, type HostHandlers, type RequestHandlers, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.d.ts

@@ -3201,15 +3201,6 @@ interface GetContextPayload {
     bridgeVersion: string;
 }
 
-/**
- * All operations the iframe can invoke on the host, each with a typed request
- * payload and a typed response. Adding a new operation here is all that's
- * required — message union types and handler types below are derived
- * automatically.
- *
- * Operations that also emit intermediate progress events should include a
- * `progress` field with the progress payload type.
- */
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3220,11 +3211,57 @@ interface UploadPayload {
 interface UploadResponse {
     attachmentId: string;
     name: string;
+    /** Public/presigned URL of the stored file, when the host returns one. */
+    url?: string;
 }
 interface UploadProgress {
     attachmentId: string;
     progress: number;
 }
+/** How the host should apply a navigation. Defaults to `'push'`. */
+type NavigateAction = 'push' | 'replace' | 'refresh';
+/**
+ * Tells the host to navigate. Provide **either** a raw `path` (relative to the
+ * app's tenant/subsidiary base) **or** a named `route` resolved host-side.
+ */
+interface NavigatePayload {
+    /** Raw path relative to the app's base, e.g. `'/journal-entries/123'`. */
+    path?: string;
+    /** Named route key the host resolves, e.g. `'CHART_OF_ACCOUNTS'`. */
+    route?: string;
+    /** Values for route placeholders, e.g. `{ id: '123' }`. */
+    routeParams?: Record<string, string>;
+    /** Navigation method. Defaults to `'push'`. */
+    action?: NavigateAction;
+}
+/** Collapse/expand the host's side navigation. */
+interface SetSideNavPayload {
+    collapsed: boolean;
+}
+/** Switch the host to a different subsidiary. */
+interface SwitchSubsidiaryPayload {
+    subsidiaryId: number;
+}
+/** Targets for a host cache invalidation. */
+interface InvalidateCachePayload {
+    /** API path prefixes to invalidate, e.g. `['/accounting/accounts']`. */
+    paths?: string[];
+    /** Cache tag keys to invalidate, e.g. `['REPORTS', 'SUBSIDIARIES']`. */
+    tags?: string[];
+}
+/** Result of a host cache invalidation. */
+interface InvalidateResult {
+    invalidated: boolean;
+}
+
+/**
+ * All operations the iframe can invoke on the host, each with a typed request
+ * payload and a typed response. Adding a new operation here is all that's
+ * required — message union types and handler types are derived automatically.
+ *
+ * Operations that also emit intermediate progress events should include a
+ * `progress` field with the progress payload type.
+ */
 interface RequestRegistry {
     GET_CHART_OF_ACCOUNTS: {
         payload: Omit<GetCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGetData, 'url'>;
@@ -3410,6 +3447,10 @@ interface RequestRegistry {
         payload: Omit<GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetData, 'url'>;
         data: GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetResponse;
     };
+    INVALIDATE_CACHE: {
+        payload: InvalidateCachePayload;
+        data: InvalidateResult;
+    };
     GET_CONTEXT: {
         payload: GetContextPayload;
         data: ContextPayload;
@@ -3434,6 +3475,53 @@ type RequestHandlers = {
     } ? (payload: RequestRegistry[K]['payload'], sendProgress: (p: P) => void) => Promise<RequestRegistry[K]['data']> : (payload: RequestRegistry[K]['payload']) => Promise<RequestRegistry[K]['data']>;
 };
 
+/**
+ * An error that crossed the bridge, carrying a machine-readable {@link code}
+ * alongside the human-readable message.
+ *
+ * The host attaches a `code` to failed responses (e.g. `'RATE_LIMITED'`,
+ * `'FILE_TOO_LARGE'`, `'REQUEST_FAILED'`); the bridge rehydrates it into a
+ * `BridgeError` so app `catch` blocks can branch on `error.code` instead of
+ * string-matching `error.message`. A failed Nominal API call rehydrates as the
+ * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccounts({})
+ * } catch (err) {
+ *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
+ * `'REQUEST_FAILED'`; the HTTP {@link status} is carried as a structured field
+ * so callers can branch on it (e.g. `err.status === 404`) instead of parsing
+ * the code string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccount({ path: { account_id: 'missing' } })
+ * } catch (err) {
+ *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *     // handle not-found
+ *   }
+ * }
+ * ```
+ */
+declare class HttpBridgeError extends BridgeError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
 interface VibeApiClientOptions {
     baseUrl: string;
     /**
@@ -3446,6 +3534,18 @@ interface VibeApiClientOptions {
 
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
+/**
+ * Notified after each request resolves — except the `GET_CONTEXT` connect poll,
+ * which is exempt. Used by nom-ui for SWR busting (SSOT §5j).
+ */
+interface RequestCompleteInfo {
+    /** The operation type, e.g. `'POST_TASK_OUTPUT'`. */
+    type: string;
+    /** Whether the operation succeeded. */
+    ok: boolean;
+    /** The request payload that was handled. */
+    payload: unknown;
+}
 interface VibeAppHostOptions {
     /**
      * Iframe origins allowed to talk to this host. Messages from any other origin
@@ -3467,13 +3567,33 @@ interface VibeAppHostOptions {
      * `{ baseUrl: '', stripApiPrefix: false }`.
      */
     clientConfig?: VibeApiClientOptions;
+    /** Fire-and-forget. Resolve a path / named route and push to the host router. */
+    onNavigate?: (payload: NavigatePayload) => void;
+    /** Fire-and-forget. Collapse/expand the host side nav. */
+    onSetSideNav?: (payload: SetSideNavPayload) => void;
+    /** Fire-and-forget. Switch subsidiary (host owns validation + navigation). */
+    onSwitchSubsidiary?: (payload: SwitchSubsidiaryPayload) => void;
+    /** Awaited. Invalidate host cache by tags/paths. Defaults to a no-op. */
+    onInvalidateCache?: (payload: InvalidateCachePayload) => Promise<InvalidateResult>;
+    /**
+     * Awaited. Real file upload — replaces the built-in stub (DP2). When omitted,
+     * `UPLOAD_FILE` requests reject with a `'NOT_WIRED'` coded error.
+     */
+    onUpload?: (payload: UploadPayload, sendProgress: (p: UploadProgress) => void) => Promise<UploadResponse>;
+    /** Optional. Notified after each request resolves (except the `GET_CONTEXT` connect poll) — used by nom-ui for SWR busting (SSOT §5j). */
+    onRequestComplete?: (info: RequestCompleteInfo) => void;
+    /** Requests/min before a request trips `RATE_LIMITED` (DP5). Default 60. */
+    rateLimit?: number;
 }
+
 /**
  * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
  * iframe origin(s), a `getContext` callback, the app's base path, and a
  * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
- * to start listening. The handler map for all protocol operations is built
- * automatically — you do not pass handlers.
+ * to start listening. The handler map for all protocol API operations is built
+ * automatically — you do not pass those handlers. Non-API side effects
+ * (navigation, side nav, subsidiary switch, cache invalidation, upload) are
+ * supplied via the optional injected callbacks.
  *
  * @example
  * ```tsx
@@ -3483,6 +3603,8 @@ interface VibeAppHostOptions {
  *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
  *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
  *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ *   onNavigate: (p) => router.push(resolve(p)),
+ *   onUpload: (p, sendProgress) => uploadToS3(p, sendProgress),
  * })
  *
  * useEffect(() => {
@@ -3501,16 +3623,35 @@ interface VibeAppHostOptions {
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
+    private readonly commandHandlers;
     private readonly getContext;
     private readonly appBasePath;
+    private readonly onRequestComplete?;
+    private readonly rateLimiter;
     private readonly boundHandleMessage;
     private readonly boundHandlePopState;
     private iframeWindow;
+    /**
+     * Source windows we've already logged a successful handshake for. The bridge
+     * polls `GET_CONTEXT` on an interval until it connects, so without this the
+     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
+     */
+    private readonly handshakeLoggedWindows;
     private readonly kindHandlers;
     private dispatchCommand;
-    private readonly commandHandlers;
+    /**
+     * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+     * guard, item `l`); navigation/UI side effects are injected by the consumer,
+     * falling back to warn-and-ignore (DP4).
+     */
+    private buildCommandHandlers;
+    /**
+     * Requests: the built-in API map (hey-api), plus the injected/awaited side
+     * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+     * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+     */
     private initializeHandlers;
-    constructor({ trustedOrigins, getContext, appBasePath, clientConfig }: VibeAppHostOptions);
+    constructor(opts: VibeAppHostOptions);
     /**
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
@@ -3535,4 +3676,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type ContextPayload, type HostContext, type HostHandlers, type RequestHandlers, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.js

@@ -1,7 +1,19 @@
 // package.json
-var version = "0.1.0";
+var version = "0.2.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,6 +30,20 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
+  }
+};
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
+  }
+};
 
 // ../api-client/dist/index.js
 import {
@@ -352,10 +378,6 @@ var getSubsidiaryParentCurrenciesApiTenancySubsidiarySubsidiaryIdParentCurrencie
 };
 function createVibeApiClient({ baseUrl, stripApiPrefix }) {
   const client2 = createClient2(createConfig2({ baseUrl }));
-  client2.interceptors.request.use((request) => {
-    console.log("[vibe-api-client] request url:", request.url);
-    return request;
-  });
   if (stripApiPrefix) {
     client2.interceptors.request.use(
       (request) => new Request(request.url.replace(`${baseUrl}/api/`, `${baseUrl}/`), request)
@@ -364,16 +386,28 @@ function createVibeApiClient({ baseUrl, stripApiPrefix }) {
   return client2;
 }
 
-// src/handlerMap.ts
+// src/handlers/call.ts
 async function call(fn, payload, client2) {
-  const { data } = await fn({ ...payload, client: client2 });
-  if (data == null) throw new Error("API returned no data");
+  const { data, response } = await fn({ ...payload, client: client2 });
+  if (data == null) {
+    if (response && !response.ok) {
+      throw new HttpBridgeError(
+        response.status,
+        `API request failed with status ${response.status}`
+      );
+    }
+    if (!response) {
+      throw new Error("API request produced no response");
+    }
+    return null;
+  }
   return data;
 }
-function createHandlerMap(options) {
-  const client2 = createVibeApiClient(options);
+
+// src/handlers/accounting.ts
+function accountingHandlers(client2) {
   return {
-    // Accounting — chart of accounts
+    // Chart of accounts
     GET_CHART_OF_ACCOUNTS: (p) => call(getCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGet, p, client2),
     GET_COA_TREE: (p) => call(getCoaTreeApiAccountingSubsidiarySubsidiaryIdCoaGet, p, client2),
     GET_COA_FLAT_SIMPLE: (p) => call(
@@ -398,7 +432,7 @@ function createHandlerMap(options) {
     ),
     GET_ACCOUNTS: (p) => call(getAccountsApiAccountingAccountGet, p, client2),
     GET_ACCOUNT: (p) => call(getAccountApiAccountingAccountAccountIdGet, p, client2),
-    // Accounting — exchange rates
+    // Exchange rates
     GET_CONVERSION_RATES: (p) => call(getConversionRateApiAccountingCurrencyCurrencyConversionRatesGet, p, client2),
     GET_EFFECTIVE_EXCHANGE_RATE: (p) => call(getEffectiveExchangeRateApiAccountingConsolidationExchangeRateGet, p, client2),
     GET_EXCHANGE_RATE_BY_DATE: (p) => call(
@@ -406,7 +440,7 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Accounting — dimensions
+    // Dimensions
     GET_DIMENSIONS: (p) => call(getDimensionsApiAccountingDimensionGet, p, client2),
     GET_DIMENSION_VALUES: (p) => call(getDimensionValuesApiAccountingDimensionValueGet, p, client2),
     GET_DIMENSION_VALUES_HIERARCHICAL: (p) => call(
@@ -419,7 +453,7 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Accounting — journal entries
+    // Journal entries
     GET_JOURNAL_ENTRIES: (p) => call(
       getSubsidiaryJournalApiAccountingSubsidiarySubsidiaryIdJournalEntryGet,
       p,
@@ -434,8 +468,14 @@ function createHandlerMap(options) {
       getJournalEntryApiAccountingSubsidiarySubsidiaryIdJournalEntryJournalEntryIdGet,
       p,
       client2
-    ),
-    // Activity — period instances
+    )
+  };
+}
+
+// src/handlers/activity.ts
+function activityHandlers(client2) {
+  return {
+    // Period instances
     GET_PERIODS: (p) => call(getPeriodInstancesApiActivityPeriodInstanceGet, p, client2),
     GET_PERIOD_INSTANCE: (p) => call(getPeriodInstanceApiActivityPeriodInstancePeriodInstanceIdGet, p, client2),
     GET_PERIOD_INSTANCE_BY_SLUG: (p) => call(
@@ -448,14 +488,14 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Activity — activity definitions
+    // Activity definitions
     GET_ACTIVITY_DEFINITIONS: (p) => call(getActivityDefinitionsApiActivityActivityDefinitionGet, p, client2),
     GET_ACTIVITY_DEFINITION: (p) => call(
       getActivityDefinitionByIdApiActivityActivityDefinitionActivityDefinitionIdGet,
       p,
       client2
     ),
-    // Activity — activity instances
+    // Activity instances
     GET_ACTIVITY_INSTANCES: (p) => call(getActivityInstancesApiActivityActivityInstanceGet, p, client2),
     GET_ACTIVITY_INSTANCE: (p) => call(getActivityInstanceApiActivityActivityInstanceActivityInstanceIdGet, p, client2),
     GET_ACTIVITY_INSTANCE_BY_PERIOD: (p) => call(
@@ -473,28 +513,43 @@ function createHandlerMap(options) {
       p,
       client2
     ),
-    // Activity — task definitions
+    // Task definitions
     GET_TASK_DEFINITIONS: (p) => call(getAllTasksDefinitionsApiActivityTaskDefinitionGet, p, client2),
     GET_TASK_DEFINITION: (p) => call(getTaskDefinitionByIdApiActivityTaskDefinitionTaskDefinitionIdGet, p, client2),
     CREATE_TASK_DEFINITION: (p) => call(createTaskDefinitionApiActivityTaskDefinitionPost, p, client2),
     UPDATE_TASK_DEFINITION: (p) => call(updateTaskDefinitionApiActivityTaskDefinitionTaskDefinitionIdPut, p, client2),
     GET_TASK_DEFINITIONS_BY_FILTER: (p) => call(getAllTasksDefinitionsByFilterApiActivityTaskDefinitionQueryPost, p, client2),
-    // Activity — task instances
+    // Task instances
     GET_TASK_INSTANCES: (p) => call(getAllTaskInstancesApiActivityTaskInstanceGet, p, client2),
     GET_TASK_INSTANCE: (p) => call(getTaskInstanceByIdApiActivityTaskInstanceTaskInstanceIdGet, p, client2),
     POST_TASK_OUTPUT: (p) => call(updateTaskInstanceApiActivityTaskInstanceTaskInstanceIdPut, p, client2),
-    GET_TASK_INSTANCES_BY_FILTER: (p) => call(getAllTaskInstancesByFilterApiActivityTaskInstanceQueryPost, p, client2),
-    // Audit trail
+    GET_TASK_INSTANCES_BY_FILTER: (p) => call(getAllTaskInstancesByFilterApiActivityTaskInstanceQueryPost, p, client2)
+  };
+}
+
+// src/handlers/audit-trail.ts
+function auditTrailHandlers(client2) {
+  return {
     GET_AUDIT_EVENTS: (p) => call(getEventsApiAuditTrailEventGet, p, client2),
-    GET_ENTITY_AUDIT_EVENTS: (p) => call(getEntityEventsApiAuditTrailEventEntityTargetTypeTargetIdPost, p, client2),
-    // Period manager
+    GET_ENTITY_AUDIT_EVENTS: (p) => call(getEntityEventsApiAuditTrailEventEntityTargetTypeTargetIdPost, p, client2)
+  };
+}
+
+// src/handlers/period-manager.ts
+function periodManagerHandlers(client2) {
+  return {
     GET_FISCAL_CALENDARS: (p) => call(
       getFiscalCalendarsBySubsidiaryApiPeriodManagerFiscalCalendarBySubsidiarySubsidiaryIdGet,
       p,
       client2
     ),
-    GET_FISCAL_CALENDAR: (p) => call(getFiscalCalendarByIdApiPeriodManagerFiscalCalendarCalendarIdGet, p, client2),
-    // Tenancy
+    GET_FISCAL_CALENDAR: (p) => call(getFiscalCalendarByIdApiPeriodManagerFiscalCalendarCalendarIdGet, p, client2)
+  };
+}
+
+// src/handlers/tenancy.ts
+function tenancyHandlers(client2) {
+  return {
     GET_SUBSIDIARIES: (p) => call(getAllSubsidiariesApiTenancySubsidiaryGet, p, client2),
     GET_SUBSIDIARY: (p) => call(getSubsidiaryApiTenancySubsidiarySubsidiaryIdGet, p, client2),
     GET_SUBSIDIARY_PARENT_CURRENCIES: (p) => call(
@@ -506,46 +561,115 @@ function createHandlerMap(options) {
   };
 }
 
-// src/uploadHandler.ts
-async function uploadHandler(payload, sendProgress) {
-  const attachmentId = crypto.randomUUID();
-  for (const progress of [25, 50, 75, 100]) {
-    await new Promise((r) => setTimeout(r, 400));
-    sendProgress({ attachmentId, progress });
+// src/handlerMap.ts
+function createHandlerMap(options) {
+  const client2 = createVibeApiClient(options);
+  return {
+    ...accountingHandlers(client2),
+    ...activityHandlers(client2),
+    ...auditTrailHandlers(client2),
+    ...periodManagerHandlers(client2),
+    ...tenancyHandlers(client2)
+  };
+}
+
+// src/rateLimiter.ts
+var DEFAULT_RATE_LIMIT = 60;
+function createRateLimiter(limit = DEFAULT_RATE_LIMIT, windowMs = 6e4) {
+  return { timestamps: [], limit, windowMs };
+}
+function checkRateLimit(state) {
+  const now = Date.now();
+  const cutoff = now - state.windowMs;
+  state.timestamps = state.timestamps.filter((t) => t > cutoff);
+  if (state.timestamps.length >= state.limit) {
+    return false;
   }
-  return { attachmentId, name: payload.fileName };
+  state.timestamps.push(now);
+  return true;
+}
+
+// src/unwired.ts
+function warnUnwired(command) {
+  return () => {
+    console.warn(`[vibe-host] Received "${command}" command but no handler is wired \u2014 ignoring.`);
+  };
+}
+function rejectUnwired(op) {
+  return () => Promise.reject(
+    new BridgeError("NOT_WIRED", `[vibe-host] Received "${op}" request but no handler is wired.`)
+  );
 }
 
 // src/VibeAppHost.ts
 var VibeAppHost = class {
-  constructor({ trustedOrigins, getContext, appBasePath, clientConfig }) {
+  constructor(opts) {
     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.kindHandlers = {
       request: (msg, source, origin) => this.handleRequest(msg, source, origin),
       command: (msg) => this.dispatchCommand(msg)
     };
-    this.commandHandlers = {
-      REPORT_SUBROUTE: (payload) => {
-        const newPath = payload.subroute === "/" ? this.appBasePath : `${this.appBasePath}${payload.subroute}`;
-        const method = payload.replace ? "replaceState" : "pushState";
-        window.history[method](null, "", newPath);
-      }
-    };
+    const { trustedOrigins, getContext, appBasePath, clientConfig } = opts;
     this.trustedOrigins = new Set(trustedOrigins);
     this.getContext = getContext;
     this.appBasePath = appBasePath;
+    this.onRequestComplete = opts.onRequestComplete;
+    this.rateLimiter = createRateLimiter(opts.rateLimit ?? DEFAULT_RATE_LIMIT);
     this.boundHandleMessage = this.handleMessage.bind(this);
     this.boundHandlePopState = this.handlePopState.bind(this);
-    this.handlers = this.initializeHandlers(clientConfig || { baseUrl: "", stripApiPrefix: false });
+    this.handlers = this.initializeHandlers(
+      clientConfig || { baseUrl: "", stripApiPrefix: false },
+      opts
+    );
+    this.commandHandlers = this.buildCommandHandlers(opts);
   }
   dispatchCommand(msg) {
     const handler = this.commandHandlers[msg.type];
-    handler(msg.payload);
+    if (!handler) {
+      console.warn(`[vibe-host] Received unknown command "${msg.type}" \u2014 ignoring.`);
+      return;
+    }
+    try {
+      handler(msg.payload);
+    } catch (err) {
+      console.warn(`[vibe-host] Command "${msg.type}" handler threw \u2014 ignoring.`, err);
+    }
   }
-  initializeHandlers(clientConfig) {
+  /**
+   * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+   * guard, item `l`); navigation/UI side effects are injected by the consumer,
+   * falling back to warn-and-ignore (DP4).
+   */
+  buildCommandHandlers(opts) {
+    return {
+      REPORT_SUBROUTE: (payload) => {
+        const safe = normalizeSubroute(payload.subroute);
+        if (safe === null) return;
+        const newPath = safe === "/" ? this.appBasePath : `${this.appBasePath}${safe}`;
+        const method = payload.replace ? "replaceState" : "pushState";
+        window.history[method](null, "", newPath);
+      },
+      NAVIGATE: opts.onNavigate ?? warnUnwired("NAVIGATE"),
+      SET_SIDE_NAV: opts.onSetSideNav ?? warnUnwired("SET_SIDE_NAV"),
+      SWITCH_SUBSIDIARY: opts.onSwitchSubsidiary ?? warnUnwired("SWITCH_SUBSIDIARY")
+    };
+  }
+  /**
+   * Requests: the built-in API map (hey-api), plus the injected/awaited side
+   * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+   * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+   */
+  initializeHandlers(clientConfig, opts) {
     return {
       ...createHandlerMap(clientConfig),
-      UPLOAD_FILE: uploadHandler
+      UPLOAD_FILE: opts.onUpload ?? rejectUnwired("UPLOAD_FILE"),
+      INVALIDATE_CACHE: opts.onInvalidateCache ?? (async () => ({ invalidated: false }))
     };
   }
   /**
@@ -617,12 +741,33 @@ var VibeAppHost = class {
   async handleRequest(msg, source, origin) {
     const { requestId, type } = msg;
     if (type === "GET_CONTEXT") {
-      const ctx = { ...this.getContext(), hostVersion: version };
-      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 });
+      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",
+        type,
+        requestId,
+        ok: false,
+        error: `Too many requests. Limit is ${this.rateLimiter.limit} per minute.`,
+        code: "RATE_LIMITED"
+      });
+      this.onRequestComplete?.({ type, ok: false, payload: msg.payload });
       return;
     }
     const sendProgress = (payload) => {
@@ -640,9 +785,21 @@ var VibeAppHost = class {
       const handler = this.handlers[type];
       const data = await handler(msg.payload, sendProgress);
       this.respond(source, origin, { kind: "response", type, requestId, ok: true, data });
+      this.onRequestComplete?.({ type, ok: true, payload: msg.payload });
     } catch (err) {
       const error = err instanceof Error ? err.message : String(err);
-      this.respond(source, origin, { kind: "response", type, requestId, ok: false, error });
+      const code = err instanceof BridgeError ? err.code : void 0;
+      const status = err instanceof HttpBridgeError ? err.status : void 0;
+      this.respond(source, origin, {
+        kind: "response",
+        type,
+        requestId,
+        ok: false,
+        error,
+        code,
+        status
+      });
+      this.onRequestComplete?.({ type, ok: false, payload: msg.payload });
     }
   }
   respond(target, origin, response) {
@@ -653,5 +810,7 @@ var VibeAppHost = class {
   }
 };
 export {
+  BridgeError,
+  HttpBridgeError,
   VibeAppHost
 };

package/package.json

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