@salesforce/sf-embedding-bridge 2.2.2 → 2.2.3

package/dist/index.d.ts

@@ -1,5 +1,199 @@
-import { BootstrapEnvelope, HostMetaData } from '@salesforce/sf-embedding-contract';
-import { JsonRpcClient, JsonRpcErrorPayload } from '@salesforce/jsonrpc';
+/** Wire identifier for this protocol. Carried verbatim on every bootstrap envelope. */
+declare const PROTOCOL_NAME: "sf-embedding";
+/** Discriminator for the host → embedding bootstrap envelope. */
+declare const BOOTSTRAP_ENVELOPE_TYPE: "sf-embedding.bootstrap";
+/** Discriminator for the embedding → host content-free heartbeat. */
+declare const HEARTBEAT_TYPE: "sf-embedding/ready";
+/**
+ * Discriminator for the embedding → host fail-closed shutdown signal
+ * (e.g., duplicate-transfer detection). Posted via window-level postMessage,
+ * not over the JSON-RPC port.
+ */
+declare const SHUTDOWN_TYPE: "sf-embedding/shutdown";
+/** Bootstrap envelope the host transfers to the embedding alongside `port1`. */
+interface BootstrapEnvelope {
+    type: typeof BOOTSTRAP_ENVELOPE_TYPE;
+    protocol: typeof PROTOCOL_NAME;
+    /** Host-minted; byte-for-byte identical to `hostMetaData.instanceId` (MC-10). */
+    instanceId: string;
+    /** Origins the host expects its wrapper chrome to load on; embedding reverse-checks. */
+    allowedOrigins: string[];
+}
+/** Heartbeat the embedding posts to `window.parent` before the port is transferred. */
+interface HeartbeatEnvelope {
+    type: typeof HEARTBEAT_TYPE;
+    /** Mirrors the URL-supplied `hostMetaData.instanceId`; binds the heartbeat to this iframe instance. */
+    instanceId: string;
+    /** SemVer protocol version the bridge speaks; host validates against its supported set. */
+    protocolVersion: string;
+}
+/** Embedding-initiated fail-closed shutdown payload (sibling-race detected, etc.). */
+interface ShutdownEnvelope {
+    type: typeof SHUTDOWN_TYPE;
+    /** Free-form; common values: `"DUPLICATE_PORT_TRANSFER"`. */
+    reason?: string;
+}
+
+/** sf-embedding protocol-specific error codes (§8.2 numeric assignments). */
+declare const SfEmbeddingErrorCode: {
+    /** Method exists at selected version but is not granted (§6.5). */
+    readonly CAPABILITY_NOT_ALLOWED: -32010;
+    /** In-flight request gated on a capability that was just revoked (§6.6). */
+    readonly CAPABILITY_REVOKED: -32011;
+    /** Frame arrived before the required handshake step completed (§5.2, §4.2). */
+    readonly NOT_INITIALIZED: -32012;
+    /** Embedding's protocol version is not supported by the host (§4.2, §3.1.2). */
+    readonly PROTOCOL_VERSION_MISMATCH: -32013;
+    /** Frame's origin does not match the bound peer origin (§3.1). */
+    readonly ORIGIN_MISMATCH: -32014;
+    /** Catch-all — duplicate ui/select-version, duplicate ui/discover-capabilities, etc. */
+    readonly PROTOCOL_VIOLATION: -32020;
+    /** Embedding observed a second valid bootstrap envelope and shut down (§3.1.2). */
+    readonly BOOTSTRAP_DUPLICATE_TRANSFER: -32023;
+};
+/** Numeric type of any value in `SfEmbeddingErrorCode`. */
+type SfEmbeddingErrorCodeValue = (typeof SfEmbeddingErrorCode)[keyof typeof SfEmbeddingErrorCode];
+/**
+ * Codes that are non-retryable by default (§8.4). Consumers building error
+ * payloads SHOULD set `retryable: false` automatically for these.
+ */
+declare const NON_RETRYABLE_CODES: ReadonlySet<number>;
+
+declare const EVENTS_DISPATCH_METHOD: "ui/events/dispatch";
+declare const EVENTS_SUBSCRIBE_METHOD: "ui/events/subscribe";
+declare const EVENTS_UNSUBSCRIBE_METHOD: "ui/events/unsubscribe";
+interface EventsDispatchParams {
+    eventType: string;
+    detail: unknown;
+    /** Whether the dispatched DOM event bubbles. Default: true. */
+    bubbles?: boolean;
+    /** Whether the dispatched DOM event crosses shadow-DOM boundaries. Default: true. */
+    composed?: boolean;
+    /** Whether the dispatched DOM event is cancelable via `preventDefault()`. Default: false. */
+    cancelable?: boolean;
+}
+interface EventsSubscribeParams {
+}
+interface EventsSubscribeResult {
+    subscriptionId: string;
+}
+interface EventsUnsubscribeParams {
+    subscriptionId: string;
+}
+
+/** Event names the host LWC dispatches on its own element. Reserved by the protocol. */
+declare const HostLwcEvent: {
+    /** Synchronous with `ui/discover-capabilities` response; session reaches READY. */
+    readonly READY: "sf-embedding.component.ready";
+    /** Misconfiguration, bootstrap failure, embedding-reported fatal, or protocol violation. */
+    readonly ERROR: "sf-embedding.component.error";
+};
+/** Type-level union of the reserved event names. */
+type HostLwcEventName = (typeof HostLwcEvent)[keyof typeof HostLwcEvent];
+/** Detail of `sf-embedding.component.ready`. */
+interface HostReadyEventDetail {
+    instanceId: string;
+}
+/** Detail of `sf-embedding.component.error` (§12.3). */
+interface HostErrorEventDetail {
+    instanceId?: string;
+    /** Failure category — drives consumer reaction. */
+    phase: "configuration" | "bootstrap" | "session";
+    /** ErrorCode constant or a configuration-error string (e.g. `"SAME_ORIGIN_SRC"`). */
+    code: string;
+    message: string;
+    /**
+     * Whether remount is plausibly fruitful (per spec §12.3).
+     * `true` — transient failures where a fresh attempt may succeed: bootstrap
+     *   handshake timeout, embedding-reported runtime error.
+     * `false` — fix the underlying problem first: configuration errors
+     *   (same-origin src, allow-scripts stripped, malformed src) and protocol
+     *   violations (duplicate port transfer).
+     */
+    retryable: boolean;
+    cause?: unknown;
+}
+
+/** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
+declare const HOST_META_DATA_PARAM: "hostMetaData";
+/**
+ * Shape of the JSON-encoded `hostMetaData` query parameter on the iframe URL.
+ *
+ * The host MUST write this onto `iframe.src` when assigning it; the embedding
+ * MUST read it before emitting the heartbeat. `hostAppOrigin` is the trust
+ * root for the embedding's inbound bootstrap envelope (MC-8). `instanceId`
+ * binds the inbound bootstrap envelope to this iframe instance (MC-10).
+ */
+interface HostMetaData {
+    hostAppOrigin: string;
+    instanceId: string;
+}
+
+/** Throw from a request handler to surface a specific JSON-RPC error code. */
+declare class JsonRpcHandlerError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+
+/** Host announces session identity to the embedding over the port. */
+declare const HOST_INITIALIZED_METHOD: "ui/notifications/host-initialized";
+/** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
+declare const EMBEDDING_INITIALIZED_METHOD: "ui/notifications/embedding-initialized";
+/** Identity of the host or embedding product. */
+interface PeerInfo {
+    name: string;
+    version: string;
+}
+/** Params for `ui/notifications/host-initialized`. */
+interface HostInitializedParams {
+    instanceId: string;
+    hostInfo: PeerInfo;
+}
+/** Params for `ui/notifications/embedding-initialized`. */
+interface EmbeddingInitializedParams {
+    embeddingInfo: PeerInfo;
+}
+
+declare const RESIZE_METHOD: "ui/notifications/resize";
+interface ResizeParams {
+    width?: number;
+    height: number;
+}
+
+declare const UI_STATE_SUBSCRIBE_METHOD: "ui/subscribe/ui-state";
+declare const UI_STATE_UNSUBSCRIBE_METHOD: "ui/unsubscribe/ui-state";
+declare const UI_STATE_CHANGED_METHOD: "ui/notifications/ui-state-changed";
+/** Styling hints the host wants the embedding to mirror. */
+interface HostStyles {
+    /** CSS custom properties (`--*`) read from the host element's inline style. */
+    variables?: Record<string, string>;
+    /** Mirrored a11y/i18n/input attributes from the host LWC element. */
+    attributes?: Record<string, string>;
+}
+/** Host → embedding rendering snapshot. */
+interface UiState {
+    props: Record<string, unknown>;
+    styles: HostStyles;
+    theme: string;
+    locale: {
+        tag: string;
+        dir: "ltr" | "rtl";
+    };
+    formFactor: "Small" | "Medium" | "Large";
+}
+interface UiStateSubscribeParams {
+}
+interface UiStateSubscribeResult {
+    subscriptionId: string;
+    current: UiState;
+}
+interface UiStateUnsubscribeParams {
+    subscriptionId: string;
+}
+interface UiStateChangedParams {
+    subscriptionId: string;
+    current: UiState;
+}
 
 type BootstrapEnvelopeValidationFailure = "INVALID_SHAPE" | "WRONG_SOURCE" | "ORIGIN_NOT_ALLOWED" | "WRONG_PORT_COUNT" | "INSTANCE_ID_MISMATCH" | "DUPLICATE_TRANSFER";
 type BootstrapEnvelopeValidationResult = {
@@ -31,9 +225,436 @@ declare class BootstrapFailureError extends Error {
     constructor(reason: BootstrapFailureReason);
 }
 
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * JSON-RPC 2.0 Protocol Types
+ *
+ * This module provides TypeScript types and runtime guards for implementing
+ * JSON-RPC 2.0 as specified in https://www.jsonrpc.org/specification.
+ *
+ * JSON-RPC 2.0 is a stateless, light-weight remote procedure call (RPC)
+ * protocol. Used for cross-realm communication via postMessage in iframe-
+ * embedded surfaces (MCP Apps, sf-embedding, and any future surface that
+ * speaks the same wire format).
+ *
+ * Protocol extension: this module relaxes JSON-RPC 2.0's "no other
+ * members" rule for one optional `_meta` field on every envelope. The
+ * underscore signals "protocol-meta, not method semantics." `_meta`
+ * carries fields applying to every method uniformly (currently `traceId`);
+ * method-specific data lives in `params` / `result` / `error`.
+ *
+ * @example
+ * // Creating a request
+ * const request: JsonRpcRequest = {
+ *   jsonrpc: "2.0",
+ *   id: 1,
+ *   method: "ui/message",
+ *   params: { role: "user", content: { type: "text", text: "Hello" } }
+ * };
+ *
+ * @example
+ * // Validating a response
+ * window.addEventListener("message", (event) => {
+ *   if (isJsonRpcResponse(event.data)) {
+ *     if (isJsonRpcErrorResponse(event.data)) {
+ *       console.error("Error:", event.data.error.message);
+ *     } else {
+ *       console.log("Result:", event.data.result);
+ *     }
+ *   }
+ * });
+ */
+/**
+ * Protocol-meta envelope. Future minors may add fields additively; old peers
+ * ignore unknown fields per the standard JSON-RPC forward-compat behavior.
+ */
+interface JsonRpcMeta {
+    /** Per-request trace identifier for cross-realm log correlation. */
+    traceId?: string;
+}
+/**
+ * JSON-RPC 2.0 base message with the required version field and the
+ * optional `_meta` extension.
+ */
+interface JsonRpcBase {
+    jsonrpc: "2.0";
+    _meta?: JsonRpcMeta;
+}
+/**
+ * JSON-RPC 2.0 Request — has both `id` and `method`.
+ */
+interface JsonRpcRequest<TParams = unknown> extends JsonRpcBase {
+    id: number;
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Notification — has `method` but NO `id`. Fire-and-forget.
+ */
+interface JsonRpcNotification<TParams = unknown> extends JsonRpcBase {
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Success Response — has `id` and `result`.
+ */
+interface JsonRpcSuccessResponse<TResult = unknown> extends JsonRpcBase {
+    id: number;
+    result: TResult;
+}
+/**
+ * JSON-RPC 2.0 Error payload (carried under `error` on an error response).
+ */
+interface JsonRpcError {
+    code: number;
+    message?: string;
+    data?: unknown;
+}
+/**
+ * JSON-RPC 2.0 Error Response — has `id` and `error`.
+ */
+interface JsonRpcErrorResponse extends JsonRpcBase {
+    id: number;
+    error: JsonRpcError;
+}
+/**
+ * Either flavor of response.
+ */
+type JsonRpcResponse<TResult = unknown> = JsonRpcSuccessResponse<TResult> | JsonRpcErrorResponse;
+/**
+ * Any JSON-RPC frame the dispatcher might receive.
+ */
+type JsonRpcFrame = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Abstract transport for a JSON-RPC 2.0 client.
+ *
+ * A `Transport` is a bidirectional, structured-message pipe. The
+ * `JsonRpcClient` uses it to send JSON-RPC messages (`post`) and subscribe
+ * to inbound ones (`onMessage`). The transport itself is agnostic to the
+ * JSON-RPC framing — it simply moves `unknown` payloads between two
+ * endpoints.
+ *
+ * Concrete transports plug into the same shape:
+ *   - `WindowPostMessageTransport` (window.parent.postMessage; used by
+ *     MCP Apps)
+ *   - `MessageChannelTransport` (a transferred `MessagePort`; used by
+ *     sf-embedding and any future surface that bootstraps with a
+ *     dedicated channel)
+ */
+interface Transport {
+    /**
+     * Deliver a single structured message to the peer. Implementations MUST
+     * NOT throw on transient conditions (closed port, missing parent
+     * window, etc.) — drop the message silently instead, matching the
+     * prior `window.parent?.postMessage` behaviour.
+     */
+    post(message: unknown): void;
+    /**
+     * Subscribe to inbound structured messages from the peer. The callback
+     * receives the already-unwrapped message payload (never a
+     * `MessageEvent`).
+     *
+     * @returns an unsubscribe function that removes this listener.
+     */
+    onMessage(callback: (message: unknown) => void): () => void;
+}
+
+/**
+ * Base class for JSON-RPC 2.0 clients.
+ *
+ * This class provides core JSON-RPC client functionality for any cross-realm
+ * surface that speaks JSON-RPC 2.0 (MCP Apps, sf-embedding, future
+ * surfaces). It handles request/response correlation, message validation,
+ * and notification dispatch.
+ *
+ * The transport layer is pluggable via the `Transport` interface and is
+ * REQUIRED at construction. There is no default transport — wildcard-targeted
+ * `window.postMessage` is structurally unsafe, so callers must construct a
+ * transport with an explicit origin (`WindowPostMessageTransport`) or a
+ * port-bound transport (`MessageChannelTransport`).
+ *
+ * Subclasses should extend this class and use the protected `request()`
+ * method to send JSON-RPC requests to the peer.
+ *
+ * @example
+ * export class MCPAppsViewSDK extends JsonRpcClient implements ViewSDK {
+ *   async displayAlert(options: AlertOptions): Promise<void> {
+ *     await this.request("ui/message", {
+ *       role: "user",
+ *       content: { type: "text", text: options.message }
+ *     });
+ *   }
+ * }
+ *
+ * @example
+ * // Injecting a transport (window.parent.postMessage to a known origin).
+ * class MyClient extends JsonRpcClient {
+ *   constructor(targetOrigin: string) {
+ *     super(new WindowPostMessageTransport(targetOrigin));
+ *   }
+ * }
+ */
+declare class JsonRpcClient {
+    private nextRequestId;
+    private pending;
+    private notificationHandlers;
+    private readonly transport;
+    /**
+     * Construct a JSON-RPC client bound to the given transport.
+     *
+     * @param transport - the transport to use.
+     */
+    constructor(transport: Transport);
+    /**
+     * Register a handler for a specific JSON-RPC notification method.
+     *
+     * Subclasses can register handlers to process specific notification
+     * types. When a notification with the registered method is received,
+     * the handler will be invoked with the notification params.
+     *
+     * @param method - The notification method to handle (e.g.
+     *   "ui/notifications/host-context-changed")
+     * @param handler - Callback function to process the notification params
+     *
+     * @example
+     * this.registerNotificationHandler("ui/notifications/host-context-changed", (params) => {
+     *   this.handleHostContextChanged(params);
+     * });
+     */
+    protected registerNotificationHandler(method: string, handler: (params: unknown, meta?: JsonRpcMeta) => void): void;
+    /**
+     * Handle inbound JSON-RPC messages from the transport.
+     *
+     * Processes both responses (for requests) and notifications.
+     * Non-JSON-RPC payloads are silently ignored so that a shared transport
+     * can be used for multiple protocols without cross-talk.
+     */
+    private onMessage;
+    /**
+     * Send a JSON-RPC request to the peer.
+     *
+     * @param method - The JSON-RPC method name
+     * @param params - The method parameters
+     * @returns Promise that resolves with the result or rejects with error
+     *
+     * @example
+     * const result = await this.request("ui/message", {
+     *   role: "user",
+     *   content: { type: "text", text: "Hello" }
+     * });
+     */
+    protected request<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /**
+     * Send a JSON-RPC notification to the peer.
+     *
+     * Notifications are one-way messages that do not expect a response.
+     * Use notifications for:
+     * - Informing the host of state changes
+     * - Fire-and-forget operations
+     * - Events that don't require confirmation
+     *
+     * Use request() instead when you need:
+     * - A response from the host
+     * - Confirmation of success/failure
+     * - Return values from the operation
+     *
+     * @param method - The JSON-RPC method name
+     * @param params - Optional method parameters
+     *
+     * @example
+     * this.sendNotification("ui/notifications/size-changed", {
+     *   width: 800,
+     *   height: 600
+     * });
+     */
+    protected sendNotification<TParams = unknown>(method: string, params?: TParams): void;
+    /**
+     * Outbound `_meta` hook. Override to attach protocol-meta (e.g. a
+     * per-message `traceId`) to every outgoing request and notification.
+     *
+     * Default returns `undefined` so the envelope ships without `_meta`,
+     * matching JSON-RPC 2.0 baseline behavior.
+     */
+    protected getOutboundMeta(_method: string): JsonRpcMeta | undefined;
+    /**
+     * Inbound `_meta` hook. Invoked once per validated inbound frame
+     * (response or notification) before the value is dispatched to the
+     * pending-request resolver or notification handlers.
+     *
+     * Default is a no-op. Override to feed log correlation, tracing, etc.
+     */
+    protected onInboundMeta(_frame: JsonRpcFrame, _meta: JsonRpcMeta | undefined): void;
+    private applyOutboundMeta;
+}
+
+/** Structure of the `data` field on a JSON-RPC error payload. */
+interface JsonRpcErrorData {
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+/** Shape of a JSON-RPC error payload (the value under `error` on an error response). */
+interface JsonRpcErrorPayload {
+    code: number;
+    message?: string;
+    data?: JsonRpcErrorData;
+}
+
+/**
+ * EmbeddingResizer - Handles dynamic iframe/container resizing
+ * Uses ResizeObserver to monitor element size changes and notify the host
+ */
+interface ResizeCallback {
+    (height: number): void;
+}
+interface EmbeddingResizerOptions {
+    /**
+     * The element to observe for size changes
+     * Defaults to document.body
+     */
+    targetElement?: Element;
+    /**
+     * Callback function invoked when resize is detected
+     */
+    onResize: ResizeCallback;
+    /**
+     * Callback function invoked when the resizer is ready
+     */
+    onReady?: () => void;
+    /**
+     * Whether to wait for DOMContentLoaded before starting observation
+     * Defaults to true
+     */
+    waitForDOMReady?: boolean;
+}
+declare class EmbeddingResizer {
+    #private;
+    constructor(options: EmbeddingResizerOptions);
+    /**
+     * Start observing the target element for size changes
+     */
+    start(): void;
+    /**
+     * Stop observing and clean up resources
+     */
+    stop(): void;
+    /**
+     * Get the current observed height
+     */
+    getLastHeight(): number;
+    /**
+     * Check if currently observing
+     */
+    isObserving(): boolean;
+}
+
+/**
+ * JSON-RPC plumbing shared by both peers of the sf-embedding protocol.
+ *
+ * Two layers live here:
+ *
+ *  - `BridgeClient` — the OUTBOUND half plus inbound responses/notifications.
+ *    Extends the library `JsonRpcClient`, so it already correlates outbound
+ *    `send()` requests with their inbound responses, dispatches inbound
+ *    notifications to `onNotification` handlers, and stamps every outbound
+ *    frame with a `_meta.traceId`. It owns the single `Transport`.
+ *
+ *  - `JsonRpcRouter` — the INBOUND-REQUEST half. It HOLDS a `BridgeClient`
+ *    and adds the one thing the client deliberately lacks: routing inbound
+ *    JSON-RPC *requests* to registered handlers and replying success/error
+ *    on the same transport (echoing `_meta` for tracing). Notifications,
+ *    responses, and outbound traffic are delegated straight to the client —
+ *    no duplicate handler tables.
+ *
+ * Request vs response/notification dispatch does not collide on the shared
+ * transport: `JsonRpcClient` ignores frames carrying both an `id` and a
+ * `method` (requests), so the router is free to claim them.
+ *
+ * Each peer subclasses `JsonRpcRouter` (see `HostBridge` /
+ * `EmbeddingBridge`): the subclass registers its inbound handlers in the
+ * constructor and exposes named methods for its outbound requests.
+ */
+
+/** Function signature for an inbound-request handler. */
+type RequestHandler<TParams = unknown, TResult = unknown> = (params: TParams, meta?: JsonRpcMeta) => TResult | Promise<TResult>;
+/** Function signature for an inbound-notification handler. */
+type NotificationHandler<TParams = unknown> = (params: TParams, meta?: JsonRpcMeta) => void;
+/** Disposer returned by `onRequest`. */
+type Unregister = () => void;
+/**
+ * Outbound + response/notification half of a JSON-RPC peer, bound to one
+ * transport. Promotes the library client's `protected` send/notify/register
+ * methods to a `public` surface the router (and its subclasses) can call, and
+ * exposes `post`/`subscribe` so the router can reply to and listen for inbound
+ * requests over the same transport.
+ *
+ * Stamps `_meta.traceId` on every outbound frame; both peers want tracing.
+ */
+declare class BridgeClient extends JsonRpcClient {
+    private readonly sharedTransport;
+    constructor(transport: Transport);
+    /** Send a request and await its correlated response. */
+    send<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /** Send a fire-and-forget notification. */
+    notify<TParams = unknown>(method: string, params?: TParams): void;
+    /** Register an inbound-notification handler. */
+    onNotification<TParams = unknown>(method: string, handler: NotificationHandler<TParams>): void;
+    /** @internal — used by JsonRpcRouter to reply to inbound requests. */
+    post(frame: unknown): void;
+    /** @internal — used by JsonRpcRouter to claim inbound requests. */
+    subscribe(callback: (data: unknown) => void): Unregister;
+    /** Tear down the underlying transport if it is disposable (e.g. MessageChannelTransport closes its port). */
+    dispose(): void;
+    /** Mints `_meta.traceId` for every outbound request and notification. */
+    protected getOutboundMeta(_method: string): JsonRpcMeta;
+}
+/**
+ * Inbound-request router. Holds a `BridgeClient` for everything else
+ * (outbound requests/notifications, inbound responses, inbound notifications)
+ * and adds inbound-request routing + replies on the shared transport.
+ *
+ * Subclass it per peer: register handlers in the constructor, add named
+ * outbound methods that call `send`/`notify`.
+ */
+declare class JsonRpcRouter {
+    protected readonly client: BridgeClient;
+    private readonly requestHandlers;
+    private readonly log;
+    private unsubscribe;
+    constructor(client: BridgeClient, log?: (...args: unknown[]) => void);
+    /** Register a handler for an inbound request method. Returns a disposer; re-registering overwrites. */
+    onRequest<TParams = unknown, TResult = unknown>(method: string, handler: RequestHandler<TParams, TResult>): Unregister;
+    /** Register an inbound-notification handler (delegates to the client). */
+    onNotification<TParams = unknown>(method: string, handler: NotificationHandler<TParams>): void;
+    /** Send an outbound request and await its response (delegates to the client). */
+    send<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /** Send an outbound notification (delegates to the client). */
+    notify<TParams = unknown>(method: string, params?: TParams): void;
+    /**
+     * Tear down: drop the inbound-request subscription, clear handlers, and
+     * dispose the client's transport (closes the port). Idempotent.
+     */
+    dispose(): void;
+    /** Route one inbound frame. Only requests are handled here; the rest is the client's. */
+    private handle;
+    private handleRequest;
+    private respondSuccess;
+    private respondError;
+    private postSafely;
+}
+
 type HostInitializedPayload = Record<string, unknown>;
 interface SessionHandle {
-    client: JsonRpcClient;
+    bridge: EmbeddingBridge;
     hostMetaData: HostMetaData;
     hostInitialized: HostInitializedPayload;
 }
@@ -43,18 +664,50 @@ declare class SessionFailureError extends Error {
     constructor(reason: SessionFailureReason, cause?: unknown);
 }
 interface BootstrapSessionOptions {
-    /**
-     * Cancellation signal. The browser MessagePort API has no port-close event,
-     * so the consumer owns the deadline (e.g. AbortSignal.timeout(30_000)).
-     * Honored only on the first call; subsequent calls return the cached promise.
-     */
+    /** Cancellation signal. Consumer owns the deadline (e.g. AbortSignal.timeout(30_000)). */
     signal?: AbortSignal;
 }
 /**
- * Bootstraps the sf-embedding session. Single-attempt per iframe — recovery
- * from failure requires a host-driven remount (`port1` is one-shot; a new
- * session needs a new `MessageChannel` + `instanceId`).
+ * Embedding-side peer. One object that routes inbound requests (via
+ * `JsonRpcRouter`), handles inbound notifications, and exposes named methods
+ * for the embedding's outbound traffic. Register inbound handlers in the
+ * constructor; add outbound methods as the protocol grows.
  */
+declare class EmbeddingBridge extends JsonRpcRouter {
+    private readonly hostInitialized;
+    private resizer;
+    constructor(transport: Transport);
+    /** Await the host's `host-initialized` notification. */
+    waitForHostInitialized(): Promise<HostInitializedPayload>;
+    /** Announce that the embedding has initialized. */
+    sendInitializedNotification(): void;
+    /** Subscribe to host UI-state. Returns the initial snapshot + active subscription id. */
+    sendUiStateSubscribe(): Promise<UiStateSubscribeResult>;
+    /** Tear down an active UI-state subscription. */
+    sendUiStateUnsubscribe(subscriptionId: string): Promise<void>;
+    /** Register a handler for `ui/notifications/ui-state-changed`. */
+    onUiStateChanged(handler: (params: UiStateChangedParams, meta?: JsonRpcMeta) => void): void;
+    /** Fire-and-forget dispatch of a custom event (bidirectional `ui/events/dispatch`).
+     * `options` controls DOM-event flags on the receiving side; defaults bubble + composed = true. */
+    sendEventDispatch(eventType: string, detail: unknown, options?: {
+        bubbles?: boolean;
+        composed?: boolean;
+        cancelable?: boolean;
+    }): void;
+    /** Subscribe to host-driven events. One subscription per session — local fan-out by eventType is the SDK's job. */
+    sendEventSubscribe(): Promise<EventsSubscribeResult>;
+    /** Tear down a host-event subscription. */
+    sendEventUnsubscribe(subscriptionId: string): Promise<void>;
+    /** Register a handler for inbound `ui/events/dispatch` (host → embedding). */
+    onEventDispatch(handler: (params: EventsDispatchParams, meta?: JsonRpcMeta) => void): void;
+    /** Fire-and-forget resize hint (`ui/notifications/resize`). */
+    sendResize(dimensions: ResizeParams): void;
+    /** Attach an auto-emit resizer; stopped on dispose. Replaces any prior resizer. */
+    attachResizer(resizer: EmbeddingResizer): void;
+    dispose(): void;
+}
+
+/** Single-attempt per iframe; recovery from failure requires a host-driven remount. */
 declare function bootstrapSession(options?: BootstrapSessionOptions): Promise<SessionHandle>;
 
 /** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
@@ -93,5 +746,5 @@ declare function makeJsonRpcError(code: number, options?: {
  */
 declare function readHostMetaData(search: string): HostMetaData | null;
 
-export { BootstrapFailureError, ErrorCode, SessionFailureError, bootstrapSession, isBootstrapEnvelope, makeJsonRpcError, readHostMetaData, validateBootstrapEnvelope };
-export type { BootstrapEnvelopeValidationFailure, BootstrapEnvelopeValidationInput, BootstrapEnvelopeValidationResult, BootstrapFailureReason, BootstrapSessionOptions, ErrorCodeValue, HostInitializedPayload, SessionFailureReason, SessionHandle };
+export { BOOTSTRAP_ENVELOPE_TYPE, BootstrapFailureError, BridgeClient, EMBEDDING_INITIALIZED_METHOD, EVENTS_DISPATCH_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, EmbeddingBridge, ErrorCode, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, JsonRpcHandlerError, JsonRpcRouter, NON_RETRYABLE_CODES, PROTOCOL_NAME, RESIZE_METHOD, SHUTDOWN_TYPE, SessionFailureError, SfEmbeddingErrorCode, UI_STATE_CHANGED_METHOD, UI_STATE_SUBSCRIBE_METHOD, UI_STATE_UNSUBSCRIBE_METHOD, bootstrapSession, isBootstrapEnvelope, makeJsonRpcError, readHostMetaData, validateBootstrapEnvelope };
+export type { BootstrapEnvelope, BootstrapEnvelopeValidationFailure, BootstrapEnvelopeValidationInput, BootstrapEnvelopeValidationResult, BootstrapFailureReason, BootstrapSessionOptions, EmbeddingInitializedParams, ErrorCodeValue, EventsDispatchParams, EventsSubscribeParams, EventsSubscribeResult, EventsUnsubscribeParams, HeartbeatEnvelope, HostErrorEventDetail, HostInitializedParams, HostInitializedPayload, HostLwcEventName, HostMetaData, HostReadyEventDetail, HostStyles, NotificationHandler, PeerInfo, RequestHandler, ResizeParams, SessionFailureReason, SessionHandle, SfEmbeddingErrorCodeValue, ShutdownEnvelope, UiState, UiStateChangedParams, UiStateSubscribeParams, UiStateSubscribeResult, UiStateUnsubscribeParams, Unregister };