@salesforce/sf-embedding-bridge 2.2.1-rc.8 → 2.2.3-rc.0

package/dist/bootstrap-session.d.ts

@@ -1,9 +1,10 @@
-import { JsonRpcClient } from "@salesforce/jsonrpc";
-import { type HostMetaData } from "@salesforce/sf-embedding-contract";
+import { type JsonRpcMeta, type Transport } from "@salesforce/jsonrpc";
+import { type EventsDispatchParams, type EventsSubscribeResult, type HostMetaData, type ResizeParams, type UiStateChangedParams, type UiStateSubscribeResult } from "@salesforce/sf-embedding-contract";
+import { EmbeddingResizer, JsonRpcRouter, type RequestHandler, type Unregister } from "utils";
 import { type BootstrapFailureReason } from "./bootstrap-listener";
 export type HostInitializedPayload = Record<string, unknown>;
 export interface SessionHandle {
-    client: JsonRpcClient;
+    bridge: EmbeddingBridge;
     hostMetaData: HostMetaData;
     hostInitialized: HostInitializedPayload;
 }
@@ -13,17 +14,49 @@ export declare class SessionFailureError extends Error {
     constructor(reason: SessionFailureReason, cause?: unknown);
 }
 export 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.
  */
+export 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;
+}
+export type { RequestHandler, Unregister };
+/** Single-attempt per iframe; recovery from failure requires a host-driven remount. */
 export declare function bootstrapSession(options?: BootstrapSessionOptions): Promise<SessionHandle>;
 //# sourceMappingURL=bootstrap-session.d.ts.map

package/dist/index.cjs.js

@@ -51,6 +51,11 @@ const NON_RETRYABLE_CODES = new Set([
     SfEmbeddingErrorCode.ORIGIN_MISMATCH,
 ]);
 
+// Bidirectional custom-event channel.
+const EVENTS_DISPATCH_METHOD = "ui/events/dispatch";
+const EVENTS_SUBSCRIBE_METHOD = "ui/events/subscribe";
+const EVENTS_UNSUBSCRIBE_METHOD = "ui/events/unsubscribe";
+
 // Host LWC reserved DOM event names and detail shapes. Spec §12.3.
 //
 // These are dispatched by the host LWC on its own element so application
@@ -67,12 +72,33 @@ const HostLwcEvent = {
 /** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
 const HOST_META_DATA_PARAM = "hostMetaData";
 
+// Shared error class for inbound-request handlers on either side of the wire.
+// Routers translate it into a JSON-RPC error response with the carried `code`;
+// any other thrown value falls back to INTERNAL_ERROR (-32603).
+/** Throw from a request handler to surface a specific JSON-RPC error code. */
+class JsonRpcHandlerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "JsonRpcHandlerError";
+    }
+}
+
 // JSON-RPC method names on the wire today.
 /** Host announces session identity to the embedding over the port. */
 const HOST_INITIALIZED_METHOD = "ui/notifications/host-initialized";
 /** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
 const EMBEDDING_INITIALIZED_METHOD = "ui/notifications/embedding-initialized";
 
+// Resize hint channel: embedding → host, fire-and-forget. CSS pixels.
+const RESIZE_METHOD = "ui/notifications/resize";
+
+// UI-state subscription axis. Snapshot in subscribe response; full-replacement change pushes.
+const UI_STATE_SUBSCRIBE_METHOD = "ui/subscribe/ui-state";
+const UI_STATE_UNSUBSCRIBE_METHOD = "ui/unsubscribe/ui-state";
+const UI_STATE_CHANGED_METHOD = "ui/notifications/ui-state-changed";
+
 // Bootstrap envelope validator for the iframe (embedding) side of the
 // sf-embedding handshake.
 //
@@ -161,6 +187,7 @@ function readHostMetaData(search) {
     return { instanceId, hostAppOrigin };
 }
 
+const BRIDGE_PROTOCOL_VERSION = "1.0.0";
 class BootstrapFailureError extends Error {
     reason;
     constructor(reason) {
@@ -175,7 +202,8 @@ function installBootstrapListener() {
         return Promise.reject(new BootstrapFailureError("MISSING_HOST_METADATA"));
     }
     return new Promise((resolve) => {
-        let accepted = false;
+        // Non-null after first accept; needed to close on duplicate transfer.
+        let acceptedPort = null;
         const handler = (event) => {
             const result = validateBootstrapEnvelope({
                 data: event.data,
@@ -185,7 +213,7 @@ function installBootstrapListener() {
                 expectedSource: window.parent,
                 allowedOrigins: [meta.hostAppOrigin],
                 expectedInstanceId: meta.instanceId,
-                alreadyAccepted: accepted,
+                alreadyAccepted: acceptedPort !== null,
             });
             if (!result.ok) {
                 if (result.reason === "DUPLICATE_TRANSFER") {
@@ -195,18 +223,26 @@ function installBootstrapListener() {
                     catch {
                         // ignore
                     }
+                    // Cannot disambiguate which envelope is real; fail closed.
+                    try {
+                        acceptedPort?.close();
+                    }
+                    catch {
+                        // already-closed ports throw on some runtimes
+                    }
+                    acceptedPort = null;
+                    console.error("[sf-embedding]", "DUPLICATE_PORT_TRANSFER: session shut down");
                     window.removeEventListener("message", handler);
                 }
                 return;
             }
-            accepted = true;
+            acceptedPort = result.port;
             resolve({ port: result.port, hostMetaData: meta });
-            // Listener stays registered per spec §3.1 — a second valid
-            // envelope MUST trigger the fail-closed shutdown branch above.
+            // Listener stays registered: a second valid envelope must shut down.
         };
         window.addEventListener("message", handler);
         try {
-            window.parent.postMessage({ type: HEARTBEAT_TYPE, instanceId: meta.instanceId }, meta.hostAppOrigin);
+            window.parent.postMessage({ type: HEARTBEAT_TYPE, instanceId: meta.instanceId, protocolVersion: BRIDGE_PROTOCOL_VERSION }, meta.hostAppOrigin);
         }
         catch {
             // ignore
@@ -214,10 +250,310 @@ function installBootstrapListener() {
     });
 }
 
+/**
+ * EmbeddingResizer - Handles dynamic iframe/container resizing
+ * Uses ResizeObserver to monitor element size changes and notify the host
+ */
+class EmbeddingResizer {
+    #observer = null;
+    #targetElement;
+    #onResize;
+    #onReady;
+    #waitForDOMReady;
+    #lastHeight = -1;
+    #scheduled = false;
+    #isObserving = false;
+    constructor(options) {
+        this.#targetElement = options.targetElement || document.body;
+        this.#onResize = options.onResize;
+        this.#onReady = options.onReady;
+        this.#waitForDOMReady = options.waitForDOMReady ?? true;
+    }
+    /**
+     * Start observing the target element for size changes
+     */
+    start() {
+        if (this.#isObserving) {
+            return;
+        }
+        if (this.#waitForDOMReady && document.readyState === "loading") {
+            document.addEventListener("DOMContentLoaded", () => this.#startObserver(), { once: true });
+        }
+        else {
+            this.#startObserver();
+        }
+    }
+    /**
+     * Stop observing and clean up resources
+     */
+    stop() {
+        if (this.#observer) {
+            this.#observer.disconnect();
+            this.#observer = null;
+        }
+        this.#isObserving = false;
+        this.#lastHeight = -1;
+        this.#scheduled = false;
+    }
+    /**
+     * Get the current observed height
+     */
+    getLastHeight() {
+        return this.#lastHeight;
+    }
+    /**
+     * Check if currently observing
+     */
+    isObserving() {
+        return this.#isObserving;
+    }
+    #startObserver = () => {
+        this.#observer = new ResizeObserver((entries) => {
+            this.#handleResize(entries);
+        });
+        this.#observer.observe(this.#targetElement, { box: "border-box" });
+        this.#isObserving = true;
+        // Invoke ready callback if provided
+        if (this.#onReady) {
+            this.#onReady();
+        }
+    };
+    #handleResize = (entries) => {
+        if (!entries || entries.length === 0) {
+            return;
+        }
+        const entry = entries[0];
+        const measuredHeight = this.#extractHeight(entry);
+        const heightPx = Math.max(0, Math.ceil(Number(measuredHeight)));
+        if (!Number.isFinite(heightPx)) {
+            return;
+        }
+        if (heightPx === this.#lastHeight) {
+            return;
+        }
+        this.#lastHeight = heightPx;
+        if (!this.#scheduled) {
+            this.#scheduled = true;
+            // eslint-disable-next-line @lwc/lwc/no-async-operation
+            requestAnimationFrame(() => {
+                this.#scheduled = false;
+                if (!this.#isObserving)
+                    return;
+                try {
+                    this.#onResize(this.#lastHeight);
+                }
+                catch {
+                    // Swallow: a throwing consumer (e.g. disposed bridge) must not wedge the rAF loop.
+                }
+            });
+        }
+    };
+    #extractHeight = (entry) => {
+        // Try borderBoxSize first (more accurate)
+        if (entry.borderBoxSize) {
+            if (Array.isArray(entry.borderBoxSize)) {
+                return entry.borderBoxSize[0]?.blockSize || 0;
+            }
+            // Some browsers return a single object instead of array
+            return entry.borderBoxSize.blockSize || 0;
+        }
+        // Fallback to contentRect
+        if (entry.contentRect && typeof entry.contentRect.height === "number") {
+            return entry.contentRect.height;
+        }
+        // Last resort: getBoundingClientRect
+        if (entry.target && typeof entry.target.getBoundingClientRect === "function") {
+            return entry.target.getBoundingClientRect().height;
+        }
+        return 0;
+    };
+}
+
+/**
+ * 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.
+ */
+// makeJsonRpcError is the upstream factory; sf-embedding's NON_RETRYABLE_CODES wrapper
+// (in sf-embedding-bridge/src/errors.ts) is bypassed here because `utils` cannot depend
+// on the bridge package. A ratchet test in sf-embedding-contract guards the invariant
+// that NON_RETRYABLE_CODES never overlaps the upstream RETRYABLE set.
+function isRequestHandlerError(err) {
+    return err instanceof Error && typeof err.code === "number";
+}
+/**
+ * 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.
+ */
+class BridgeClient extends jsonrpc.JsonRpcClient {
+    sharedTransport;
+    constructor(transport) {
+        super(transport);
+        this.sharedTransport = transport;
+    }
+    /** Send a request and await its correlated response. */
+    send(method, params) {
+        return this.request(method, params);
+    }
+    /** Send a fire-and-forget notification. */
+    notify(method, params) {
+        this.sendNotification(method, params);
+    }
+    /** Register an inbound-notification handler. */
+    onNotification(method, handler) {
+        this.registerNotificationHandler(method, handler);
+    }
+    /** @internal — used by JsonRpcRouter to reply to inbound requests. */
+    post(frame) {
+        this.sharedTransport.post(frame);
+    }
+    /** @internal — used by JsonRpcRouter to claim inbound requests. */
+    subscribe(callback) {
+        return this.sharedTransport.onMessage(callback);
+    }
+    /** Tear down the underlying transport if it is disposable (e.g. MessageChannelTransport closes its port). */
+    dispose() {
+        const transport = this.sharedTransport;
+        if (typeof transport.dispose === "function") {
+            transport.dispose();
+        }
+    }
+    /** Mints `_meta.traceId` for every outbound request and notification. */
+    getOutboundMeta(_method) {
+        return { traceId: crypto.randomUUID() };
+    }
+}
+/**
+ * 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`.
+ */
+class JsonRpcRouter {
+    client;
+    requestHandlers = new Map();
+    log;
+    unsubscribe = null;
+    constructor(client, log = () => { }) {
+        this.client = client;
+        this.log = log;
+        // Claim inbound *requests*; the client already handles responses and
+        // notifications on the same transport and ignores request frames.
+        this.unsubscribe = this.client.subscribe((data) => this.handle(data));
+    }
+    /** Register a handler for an inbound request method. Returns a disposer; re-registering overwrites. */
+    onRequest(method, handler) {
+        this.requestHandlers.set(method, handler);
+        return () => {
+            if (this.requestHandlers.get(method) === handler) {
+                this.requestHandlers.delete(method);
+            }
+        };
+    }
+    /** Register an inbound-notification handler (delegates to the client). */
+    onNotification(method, handler) {
+        this.client.onNotification(method, handler);
+    }
+    /** Send an outbound request and await its response (delegates to the client). */
+    send(method, params) {
+        return this.client.send(method, params);
+    }
+    /** Send an outbound notification (delegates to the client). */
+    notify(method, params) {
+        this.client.notify(method, params);
+    }
+    /**
+     * Tear down: drop the inbound-request subscription, clear handlers, and
+     * dispose the client's transport (closes the port). Idempotent.
+     */
+    dispose() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+        this.requestHandlers.clear();
+        this.client.dispose();
+    }
+    /** Route one inbound frame. Only requests are handled here; the rest is the client's. */
+    handle(data) {
+        if (!jsonrpc.isJsonRpcRequest(data))
+            return;
+        this.handleRequest(data);
+    }
+    handleRequest(req) {
+        const handler = this.requestHandlers.get(req.method);
+        if (!handler) {
+            this.respondError(req.id, jsonrpc.StandardErrorCode.METHOD_NOT_FOUND, `Method not found: ${req.method}`, req._meta);
+            return;
+        }
+        Promise.resolve()
+            .then(() => handler(req.params, req._meta))
+            .then((result) => this.respondSuccess(req.id, result, req._meta), (err) => {
+            const code = isRequestHandlerError(err) ? err.code : jsonrpc.StandardErrorCode.INTERNAL_ERROR;
+            const message = err instanceof Error ? err.message : String(err);
+            this.respondError(req.id, code, message, req._meta);
+        });
+    }
+    respondSuccess(id, result, meta) {
+        const frame = { jsonrpc: "2.0", id, result };
+        if (meta)
+            frame._meta = meta;
+        this.postSafely(frame);
+    }
+    respondError(id, code, message, meta) {
+        const frame = {
+            jsonrpc: "2.0",
+            id,
+            error: jsonrpc.makeJsonRpcError(code, { message }),
+        };
+        if (meta)
+            frame._meta = meta;
+        this.postSafely(frame);
+    }
+    postSafely(frame) {
+        try {
+            this.client.post(frame);
+        }
+        catch (err) {
+            // Transport.post should not throw on transient failure, but guard so a
+            // misbehaving transport can't take down request handling.
+            this.log("response post threw —", err);
+        }
+    }
+}
+
 /** Identity emitted on `ui/notifications/embedding-initialized`. */
 const EMBEDDING_INFO = {
     name: "@salesforce/sf-embedding-bridge",
-    version: "2.2.1-rc.8",
+    version: "2.2.3-rc.0",
 };
 
 class SessionFailureError extends Error {
@@ -231,10 +567,20 @@ class SessionFailureError extends Error {
         }
     }
 }
-class SessionClient extends jsonrpc.JsonRpcClient {
-    waitForHostInitialized() {
-        return new Promise((resolve) => {
-            this.registerNotificationHandler(HOST_INITIALIZED_METHOD, (params) => {
+/**
+ * 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.
+ */
+class EmbeddingBridge extends JsonRpcRouter {
+    hostInitialized;
+    resizer = null;
+    constructor(transport) {
+        super(new BridgeClient(transport));
+        // Resolve when the host announces it has initialized.
+        this.hostInitialized = new Promise((resolve) => {
+            this.onNotification(HOST_INITIALIZED_METHOD, (params) => {
                 const payload = params && typeof params === "object" && !Array.isArray(params)
                     ? params
                     : {};
@@ -242,48 +588,119 @@ class SessionClient extends jsonrpc.JsonRpcClient {
             });
         });
     }
+    /** Await the host's `host-initialized` notification. */
+    waitForHostInitialized() {
+        return this.hostInitialized;
+    }
+    /** Announce that the embedding has initialized. */
     sendInitializedNotification() {
         const params = { embeddingInfo: EMBEDDING_INFO };
-        this.sendNotification(EMBEDDING_INITIALIZED_METHOD, params);
+        this.notify(EMBEDDING_INITIALIZED_METHOD, params);
+    }
+    /** Subscribe to host UI-state. Returns the initial snapshot + active subscription id. */
+    sendUiStateSubscribe() {
+        return this.send(UI_STATE_SUBSCRIBE_METHOD, {});
+    }
+    /** Tear down an active UI-state subscription. */
+    sendUiStateUnsubscribe(subscriptionId) {
+        return this.send(UI_STATE_UNSUBSCRIBE_METHOD, { subscriptionId });
+    }
+    /** Register a handler for `ui/notifications/ui-state-changed`. */
+    onUiStateChanged(handler) {
+        this.onNotification(UI_STATE_CHANGED_METHOD, handler);
+    }
+    /** 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, detail, options) {
+        const params = { eventType, detail, ...options };
+        this.notify(EVENTS_DISPATCH_METHOD, params);
+    }
+    /** Subscribe to host-driven events. One subscription per session — local fan-out by eventType is the SDK's job. */
+    sendEventSubscribe() {
+        return this.send(EVENTS_SUBSCRIBE_METHOD, {});
+    }
+    /** Tear down a host-event subscription. */
+    sendEventUnsubscribe(subscriptionId) {
+        return this.send(EVENTS_UNSUBSCRIBE_METHOD, { subscriptionId });
+    }
+    /** Register a handler for inbound `ui/events/dispatch` (host → embedding). */
+    onEventDispatch(handler) {
+        this.onNotification(EVENTS_DISPATCH_METHOD, handler);
+    }
+    /** Fire-and-forget resize hint (`ui/notifications/resize`). */
+    sendResize(dimensions) {
+        this.notify(RESIZE_METHOD, dimensions);
+    }
+    /** Attach an auto-emit resizer; stopped on dispose. Replaces any prior resizer. */
+    attachResizer(resizer) {
+        if (this.resizer && this.resizer !== resizer)
+            this.resizer.stop();
+        this.resizer = resizer;
+    }
+    dispose() {
+        this.resizer?.stop();
+        this.resizer = null;
+        super.dispose();
     }
 }
-function rejectOnAbort(signal) {
+// `cleanup` lets the caller drop our listener from the consumer-owned signal once the race resolves.
+function rejectOnAbort(signal, cleanup) {
     if (!signal)
         return new Promise(() => { });
     if (signal.aborted)
         return Promise.reject(new SessionFailureError("ABORTED"));
     return new Promise((_, reject) => {
-        signal.addEventListener("abort", () => reject(new SessionFailureError("ABORTED")), { once: true });
+        signal.addEventListener("abort", () => reject(new SessionFailureError("ABORTED")), {
+            once: true,
+            signal: cleanup,
+        });
     });
 }
 let sessionPromise = null;
-/**
- * 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`).
- */
+/** Single-attempt per iframe; recovery from failure requires a host-driven remount. */
 function bootstrapSession(options = {}) {
     if (sessionPromise)
         return sessionPromise;
     sessionPromise = installBootstrapListener()
         .then(async (capture) => {
         const transport = new jsonrpc.MessageChannelTransport(capture.port);
-        const client = new SessionClient(transport);
-        const hostInitialized = await Promise.race([
-            client.waitForHostInitialized(),
-            rejectOnAbort(options.signal),
-        ]);
-        client.sendInitializedNotification();
-        return {
-            client,
-            hostMetaData: capture.hostMetaData,
-            hostInitialized,
-        };
+        const bridge = new EmbeddingBridge(transport);
+        const abortCleanup = new AbortController();
+        try {
+            const hostInitialized = await Promise.race([
+                bridge.waitForHostInitialized(),
+                rejectOnAbort(options.signal, abortCleanup.signal),
+            ]);
+            bridge.sendInitializedNotification();
+            const handle = {
+                bridge,
+                hostMetaData: capture.hostMetaData,
+                hostInitialized,
+            };
+            // Auto-emit resize hints on document.body (height-only, RAF-coalesced).
+            // Bridge owns the resizer's lifecycle so dispose() stops the observer.
+            const resizer = new EmbeddingResizer({
+                waitForDOMReady: true,
+                onResize: (height) => bridge.sendResize({ height }),
+            });
+            bridge.attachResizer(resizer);
+            resizer.start();
+            return handle;
+        }
+        catch (err) {
+            // Abort or unexpected failure after construction: dispose so the port doesn't leak.
+            bridge.dispose();
+            throw err;
+        }
+        finally {
+            // Detach our abort listener from the consumer-owned signal.
+            abortCleanup.abort();
+        }
     })
         .catch((err) => {
         if (err instanceof SessionFailureError)
             throw err;
-        if (err instanceof Error && "reason" in err) {
+        if (err instanceof BootstrapFailureError) {
             throw new SessionFailureError(err.reason, err);
         }
         throw err;
@@ -313,17 +730,28 @@ function makeJsonRpcError(code, options = {}) {
 
 exports.BOOTSTRAP_ENVELOPE_TYPE = BOOTSTRAP_ENVELOPE_TYPE;
 exports.BootstrapFailureError = BootstrapFailureError;
+exports.BridgeClient = BridgeClient;
 exports.EMBEDDING_INITIALIZED_METHOD = EMBEDDING_INITIALIZED_METHOD;
+exports.EVENTS_DISPATCH_METHOD = EVENTS_DISPATCH_METHOD;
+exports.EVENTS_SUBSCRIBE_METHOD = EVENTS_SUBSCRIBE_METHOD;
+exports.EVENTS_UNSUBSCRIBE_METHOD = EVENTS_UNSUBSCRIBE_METHOD;
+exports.EmbeddingBridge = EmbeddingBridge;
 exports.ErrorCode = ErrorCode;
 exports.HEARTBEAT_TYPE = HEARTBEAT_TYPE;
 exports.HOST_INITIALIZED_METHOD = HOST_INITIALIZED_METHOD;
 exports.HOST_META_DATA_PARAM = HOST_META_DATA_PARAM;
 exports.HostLwcEvent = HostLwcEvent;
+exports.JsonRpcHandlerError = JsonRpcHandlerError;
+exports.JsonRpcRouter = JsonRpcRouter;
 exports.NON_RETRYABLE_CODES = NON_RETRYABLE_CODES;
 exports.PROTOCOL_NAME = PROTOCOL_NAME;
+exports.RESIZE_METHOD = RESIZE_METHOD;
 exports.SHUTDOWN_TYPE = SHUTDOWN_TYPE;
 exports.SessionFailureError = SessionFailureError;
 exports.SfEmbeddingErrorCode = SfEmbeddingErrorCode;
+exports.UI_STATE_CHANGED_METHOD = UI_STATE_CHANGED_METHOD;
+exports.UI_STATE_SUBSCRIBE_METHOD = UI_STATE_SUBSCRIBE_METHOD;
+exports.UI_STATE_UNSUBSCRIBE_METHOD = UI_STATE_UNSUBSCRIBE_METHOD;
 exports.bootstrapSession = bootstrapSession;
 exports.isBootstrapEnvelope = isBootstrapEnvelope;
 exports.makeJsonRpcError = makeJsonRpcError;