@nominalso/vibe-host 0.1.0 → 0.3.0

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,11 +3534,36 @@ 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
-     * are ignored, and context/pushes are only sent to these origins. Must match
-     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     * are ignored, and context/pushes are only sent to allowed origins.
+     *
+     * Each entry is either an exact origin (`'https://my-vibe-app.lovable.app'`)
+     * or a **glob pattern** containing `*` (`'https://*.vercel.app'`), where `*`
+     * matches exactly one DNS label or port — anchored, scheme literal — so
+     * `https://*.vercel.app` matches `https://pr-7.vercel.app` but not
+     * `https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`.
+     *
+     * Patterns are honoured unconditionally, so **only add them for non-production
+     * environments** — gate this list on your own deploy env (e.g. pass exact
+     * origins only in production, exact + `*.vercel.app`/`*.lovable.app` in
+     * staging/dev) to test against dynamic preview deployments. Because you cannot
+     * `postMessage` to a pattern, proactive context/subroute pushes target the
+     * exact entries plus any origin seen on a validated inbound message; pattern-
+     * matched iframes still receive context via their `connect()` poll response.
      */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
@@ -3467,13 +3580,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 +3616,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(() => {
@@ -3499,18 +3634,51 @@ interface VibeAppHostOptions {
  * ```
  */
 declare class VibeAppHost {
+    /**
+     * Configured allowlist. Entries may be exact origins or glob patterns
+     * (`https://*.vercel.app`); inbound messages are validated against it with
+     * {@link isOriginAllowed}. Pattern entries are honoured — nom-ui is expected
+     * to supply patterns only in non-production environments.
+     */
     private readonly trustedOrigins;
+    /** The exact (non-pattern) subset of {@link trustedOrigins} — see {@link concreteTargets}. */
+    private readonly exactOrigins;
+    /**
+     * Concrete iframe origins observed on validated inbound messages. Because you
+     * cannot `postMessage` to a glob pattern, proactive pushes target these
+     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     */
+    private readonly connectedOrigins;
     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.
@@ -3531,8 +3699,15 @@ declare class VibeAppHost {
     private handlePopState;
     private pushToIframe;
     private handleMessage;
+    /**
+     * Concrete origins a proactive push may target: the exact allowlist entries
+     * plus any origins seen on validated inbound messages. Never includes glob
+     * patterns (you cannot `postMessage` to one). When only exact origins are
+     * configured this equals the configured set, so behaviour is unchanged.
+     */
+    private concreteTargets;
     private handleRequest;
     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,11 +3534,36 @@ 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
-     * are ignored, and context/pushes are only sent to these origins. Must match
-     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     * are ignored, and context/pushes are only sent to allowed origins.
+     *
+     * Each entry is either an exact origin (`'https://my-vibe-app.lovable.app'`)
+     * or a **glob pattern** containing `*` (`'https://*.vercel.app'`), where `*`
+     * matches exactly one DNS label or port — anchored, scheme literal — so
+     * `https://*.vercel.app` matches `https://pr-7.vercel.app` but not
+     * `https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`.
+     *
+     * Patterns are honoured unconditionally, so **only add them for non-production
+     * environments** — gate this list on your own deploy env (e.g. pass exact
+     * origins only in production, exact + `*.vercel.app`/`*.lovable.app` in
+     * staging/dev) to test against dynamic preview deployments. Because you cannot
+     * `postMessage` to a pattern, proactive context/subroute pushes target the
+     * exact entries plus any origin seen on a validated inbound message; pattern-
+     * matched iframes still receive context via their `connect()` poll response.
      */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
@@ -3467,13 +3580,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 +3616,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(() => {
@@ -3499,18 +3634,51 @@ interface VibeAppHostOptions {
  * ```
  */
 declare class VibeAppHost {
+    /**
+     * Configured allowlist. Entries may be exact origins or glob patterns
+     * (`https://*.vercel.app`); inbound messages are validated against it with
+     * {@link isOriginAllowed}. Pattern entries are honoured — nom-ui is expected
+     * to supply patterns only in non-production environments.
+     */
     private readonly trustedOrigins;
+    /** The exact (non-pattern) subset of {@link trustedOrigins} — see {@link concreteTargets}. */
+    private readonly exactOrigins;
+    /**
+     * Concrete iframe origins observed on validated inbound messages. Because you
+     * cannot `postMessage` to a glob pattern, proactive pushes target these
+     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     */
+    private readonly connectedOrigins;
     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.
@@ -3531,8 +3699,15 @@ declare class VibeAppHost {
     private handlePopState;
     private pushToIframe;
     private handleMessage;
+    /**
+     * Concrete origins a proactive push may target: the exact allowlist entries
+     * plus any origins seen on validated inbound messages. Never includes glob
+     * patterns (you cannot `postMessage` to one). When only exact origins are
+     * configured this equals the configured set, so behaviour is unchanged.
+     */
+    private concreteTargets;
     private handleRequest;
     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 };