@ethisyscore/extension-runtime 1.6.0

package/dist/transport-73otePiw.d.cts

@@ -0,0 +1,307 @@
+/**
+ * Worker-side host transport for `renderMode: remote-runtime` extensions
+ * (Contract B). Owns the lifecycle of:
+ *
+ *   1. A path-pinned module `Worker` spawned from a host-issued bootstrap URL.
+ *   2. A `MessagePort`-based RPC channel (handed to the worker on spawn).
+ *   3. A Shopify Remote DOM root receiver — wired here so the worker's UI
+ *      tree mounts into a host React tree.
+ *   4. Event coalescing (default ≤16ms, one rAF) for high-frequency input
+ *      events before they cross the port.
+ *   5. MCP tool/resource calls forwarded through the port — but **the
+ *      capability token never crosses the boundary**. The token is bound
+ *      to the worker scope on the HOST side: the host transport intercepts
+ *      the plugin's MCP request, attaches the token to the outbound HTTP
+ *      call, and forwards ONLY the response payload back through the port.
+ *
+ * This module is intentionally framework-thin: callers wire `mount(root)`
+ * onto a React tree (typically inside a `<WorkerSurfaceMount>`), and the
+ * Remote DOM receiver is responsible for translating worker-side
+ * RemoteRoot mutations into host-side component renders.
+ */
+/**
+ * Structural subset of the DOM `Worker` interface that the transport needs.
+ * Tests inject a fake; production callers pass the global `Worker`.
+ */
+interface WorkerLike {
+    onmessage: ((ev: MessageEvent) => void) | null;
+    onerror: ((ev: ErrorEvent) => void) | null;
+    onmessageerror: ((ev: MessageEvent) => void) | null;
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+/**
+ * Constructor signature compatible with the DOM `Worker` constructor. The
+ * `workerCtor` option exists exclusively so tests can swap in a fake — in
+ * production the caller passes the global `Worker`.
+ */
+type WorkerCtor = new (url: string | URL, options?: WorkerOptions) => WorkerLike;
+/**
+ * Discriminated union of MCP fetch shapes the host transport issues. The
+ * `capabilityToken` is attached on the host side ONLY — it is never present
+ * in any message that crosses the worker port.
+ */
+type McpHttpRequest = {
+    kind: "invokeTool";
+    name: string;
+    args: unknown;
+    capabilityToken: string;
+    signal?: AbortSignal;
+} | {
+    kind: "getResource";
+    uri: string;
+    capabilityToken: string;
+    signal?: AbortSignal;
+};
+/**
+ * Host-side HTTP client for MCP calls. Implementations are responsible for
+ * carrying the supplied `capabilityToken` on the outbound request (typically
+ * via `Authorization: Bearer`).
+ */
+interface McpHttpClient {
+    fetch(request: McpHttpRequest): Promise<{
+        ok: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+}
+/**
+ * Construction options for {@link WorkerRemoteDomTransport}.
+ */
+interface WorkerRemoteDomTransportOptions {
+    /**
+     * Canonical host-origin URL for the worker bootstrap script. This MUST
+     * be supplied by the host — never built from user input or extension
+     * manifest values — so the worker spawn is path-pinned.
+     */
+    bootstrapUrl: string;
+    /**
+     * Mints (or fetches a cached) capability token. The host transport
+     * resolves this for each outbound MCP HTTP call. The token NEVER leaves
+     * host scope — plugin code (the worker side) cannot read it.
+     */
+    capabilityToken: () => Promise<string>;
+    /**
+     * Host-side MCP HTTP client. The transport bridges port-side plugin
+     * MCP requests to this client and returns only the response payload
+     * back through the port.
+     */
+    mcpClient: McpHttpClient;
+    /**
+     * Injectable Worker constructor (tests use a fake). Defaults to the
+     * global `Worker`.
+     */
+    workerCtor?: WorkerCtor;
+    /**
+     * Coalescing window in milliseconds for high-frequency events. Defaults
+     * to 16ms (~one animation frame). Trailing-edge: the most recent payload
+     * within the window is delivered after the window elapses.
+     */
+    coalesceMs?: number;
+    /**
+     * Maximum number of MCP requests (combined `invokeTool` + `getResource`)
+     * the transport will forward to {@link mcpClient} concurrently. Defaults
+     * to 8. Requests above the cap are rejected with a deterministic error
+     * reply over the port — the worker MUST handle that response shape.
+     *
+     * Bounded concurrency is a back-pressure boundary, not a quota: it stops
+     * a compromised or buggy worker from saturating the host's HTTP / token
+     * pool. Production hosts may want to lower this in multi-tenant pools
+     * where many extensions share one host process.
+     */
+    maxConcurrentMcpRequests?: number;
+}
+/**
+ * Wire shape of a host-sourced input event forwarded to the worker over the
+ * port. Pointer / wheel / keyboard payloads share a single envelope type so
+ * the worker has one inbound dispatch site. The transport is structurally
+ * agnostic to the payload — it forwards verbatim.
+ *
+ * `kind` discriminates the event family. Coordinates are CSS pixels relative
+ * to the host canvas; coalescing happens host-side before the call to
+ * {@link WorkerRemoteDomTransport.postInputEvent}.
+ */
+type InputEventPayload = {
+    kind: "pointermove" | "pointerdown" | "pointerup" | "pointercancel";
+    surfaceId: string;
+    x: number;
+    y: number;
+    buttons: number;
+    pointerType: string;
+} | {
+    kind: "wheel";
+    surfaceId: string;
+    deltaX: number;
+    deltaY: number;
+    deltaMode: number;
+} | {
+    kind: "keydown" | "keyup";
+    surfaceId: string;
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+};
+/**
+ * Documented wire protocol identifier embedded in handshake / message
+ * envelopes. Bumped when the worker ↔ host message shape changes in a
+ * backward-incompatible way.
+ */
+declare const WORKER_TRANSPORT_PROTOCOL = "ethisys.worker.remotedom.v1";
+/**
+ * Wire shape of the handshake message the host posts to the worker on
+ * {@link WorkerRemoteDomTransport.connect}. Locked here so the SDK side and the
+ * API-hosted bootstrap script (`WorkerBootstrapScriptProvider`) read from the
+ * same field names — see the API tests pinning `event.data.moduleUrl` and
+ * `event.data.importMap`.
+ *
+ * The handshake is the SOLE message that ever carries `moduleUrl` or
+ * `importMap`; subsequent port traffic uses the discriminated message types
+ * declared below. The capability token NEVER appears in this payload (or any
+ * other postMessage payload) — it is bound on the host side via
+ * {@link WorkerRemoteDomTransportOptions.capabilityToken}.
+ */
+interface WorkerHandshakePayload {
+    readonly type: "ethisys:worker:handshake";
+    readonly protocol: string;
+    /** Host-origin URL of the plugin's worker bundle entry. */
+    readonly moduleUrl: string;
+    /**
+     * Frozen bare-specifier → host-origin URL map that the bootstrap installs
+     * before importing {@link moduleUrl}. Pulled from the plugin's
+     * `worker-bundle.import-map.json` at runtime by the host mount.
+     */
+    readonly importMap: Readonly<Record<string, string>>;
+}
+/**
+ * Worker-side host transport for Contract B extensions.
+ *
+ * Construction immediately spawns the worker and transfers one end of a
+ * fresh `MessageChannel`; the host retains `port1`, the worker receives
+ * `port2`. Both sides exchange messages via their port and the worker port
+ * is the *only* channel for plugin ↔ host traffic after handshake.
+ */
+/**
+ * Default cap for in-flight MCP requests forwarded by the transport. Chosen to
+ * cover typical interactive UI traffic (dashboards, list views, detail panels)
+ * without letting a runaway worker saturate the host's HTTP / token pool.
+ */
+declare const DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = 8;
+declare class WorkerRemoteDomTransport {
+    private readonly worker;
+    private readonly hostPort;
+    private readonly workerPort;
+    private readonly mcpClient;
+    private readonly capabilityTokenProvider;
+    private readonly coalesceMs;
+    private readonly maxConcurrentMcpRequests;
+    private readonly abortController;
+    private inFlightMcpRequests;
+    private remoteDomConsumer;
+    private disposed;
+    private connected;
+    constructor(options: WorkerRemoteDomTransportOptions);
+    /**
+     * Post the handshake to the worker. Idempotent — only the FIRST call
+     * transfers the {@link MessagePort} and posts the handshake payload;
+     * subsequent calls are silent no-ops. Splitting this off from the
+     * constructor lets the host mount fetch the per-plugin
+     * `worker-bundle.import-map.json` (and resolve the bundle's module URL)
+     * before the bootstrap script consumes them.
+     *
+     * Wire shape: {@link WorkerHandshakePayload}. The capability token NEVER
+     * appears in the payload — it's bound on the host side via the
+     * {@link WorkerRemoteDomTransportOptions.capabilityToken} provider.
+     *
+     * The `moduleUrl` and `importMap` are forwarded to the worker so the
+     * bootstrap script (served from the host-pinned
+     * `/extensions/runtime/worker-bootstrap.js`) can:
+     *   1. Compose the frozen, same-origin-validated `IMPORT_MAP` from the
+     *      handshake payload (rejecting any cross-origin entries).
+     *   2. `safeImport(moduleUrl)` the plugin's entry module.
+     *
+     * Same-origin enforcement is the bootstrap's job — this transport is
+     * structurally agnostic to the host origin and only forwards what it's
+     * handed.
+     */
+    connect(moduleUrl: string, importMap: Record<string, string>): void;
+    /**
+     * Bind a consumer for Remote DOM mutation payloads emitted by the worker.
+     * The Remote DOM receiver wiring is owned by the caller (typically a host
+     * React component); this method exposes the raw stream so the receiver
+     * can integrate cleanly without a circular package import.
+     */
+    onRemoteDom(consumer: (payload: unknown) => void): void;
+    /**
+     * Transfer control of a host-owned `<canvas>` to the worker so plugin code
+     * can render via `OffscreenCanvas`. The host retains the `<canvas>` for
+     * layout / accessibility purposes only — every pixel is produced inside the
+     * worker, so the main thread is never blocked per frame.
+     *
+     * The transfer rides the established MessagePort (not the worker global
+     * `postMessage`) so it is multiplexed with the rest of the host ↔ worker
+     * traffic on the same channel. The `OffscreenCanvas` handle is the sole
+     * `Transferable` in the envelope; no capability token, MCP context, or
+     * other host-only data crosses the boundary.
+     *
+     * Throws if the environment lacks `transferControlToOffscreen()` or if the
+     * canvas has already been transferred — see {@link createOffscreenCanvasTransfer}
+     * for the exact diagnostics.
+     */
+    transferCanvas(canvas: HTMLCanvasElement, options: {
+        surfaceId: string;
+    }): {
+        offscreen: OffscreenCanvas;
+    };
+    /**
+     * Forward a host-sourced input event to the worker over the port. The
+     * payload shape is opaque to the transport — pointer / wheel / keyboard
+     * envelopes share the same wire type. Callers are expected to wrap
+     * high-frequency (pointer-move, wheel, scroll) events in
+     * {@link createCoalescer} or {@link createInputEventCoalescer} BEFORE
+     * calling this method so the port never sees the un-coalesced flood.
+     *
+     * Keyboard / pointer-down / pointer-up events are discrete and should be
+     * delivered without coalescing — pass them straight through.
+     */
+    postInputEvent(payload: InputEventPayload): void;
+    /**
+     * Build a trailing-edge coalescer keyed to {@link WorkerRemoteDomTransportOptions.coalesceMs}.
+     *
+     * Use it to wrap pointer-move / scroll / resize callbacks **before**
+     * they cross the port. The last payload in any coalescing window is the
+     * one that wins.
+     */
+    createCoalescer<T>(consumer: (payload: T) => void): (payload: T) => void;
+    /**
+     * Tear down the worker and port. Idempotent.
+     *
+     * Order matters: we abort BEFORE closing the port so any in-flight
+     * `mcpClient.fetch` that observes the signal short-circuits and the
+     * subsequent attempt to post a reply lands in the disposed-guard branch
+     * (which silently drops the post) instead of throwing on a closed port.
+     */
+    dispose(): void;
+    /**
+     * Best-effort wrapper around `hostPort.postMessage` that tolerates posts
+     * arriving after {@link dispose}. The browser throws on a closed port and
+     * the async handlers below can race dispose, so any post initiated by an
+     * awaited continuation must be guarded.
+     */
+    private safePostMessage;
+    private handlePortMessage;
+    /**
+     * Gate inbound MCP requests through the bounded concurrency window,
+     * reject with a deterministic error reply when the cap is exceeded, and
+     * decrement the counter unconditionally when the underlying handler
+     * settles (regardless of resolution/rejection shape).
+     */
+    private dispatchMcp;
+    private handleInvokeTool;
+    private handleGetResource;
+    private replyError;
+}
+
+export { DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, type InputEventPayload as I, type McpHttpClient as M, WORKER_TRANSPORT_PROTOCOL as W, type McpHttpRequest as a, type WorkerCtor as b, type WorkerHandshakePayload as c, type WorkerLike as d, WorkerRemoteDomTransport as e, type WorkerRemoteDomTransportOptions as f };

package/dist/transport-73otePiw.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Worker-side host transport for `renderMode: remote-runtime` extensions
+ * (Contract B). Owns the lifecycle of:
+ *
+ *   1. A path-pinned module `Worker` spawned from a host-issued bootstrap URL.
+ *   2. A `MessagePort`-based RPC channel (handed to the worker on spawn).
+ *   3. A Shopify Remote DOM root receiver — wired here so the worker's UI
+ *      tree mounts into a host React tree.
+ *   4. Event coalescing (default ≤16ms, one rAF) for high-frequency input
+ *      events before they cross the port.
+ *   5. MCP tool/resource calls forwarded through the port — but **the
+ *      capability token never crosses the boundary**. The token is bound
+ *      to the worker scope on the HOST side: the host transport intercepts
+ *      the plugin's MCP request, attaches the token to the outbound HTTP
+ *      call, and forwards ONLY the response payload back through the port.
+ *
+ * This module is intentionally framework-thin: callers wire `mount(root)`
+ * onto a React tree (typically inside a `<WorkerSurfaceMount>`), and the
+ * Remote DOM receiver is responsible for translating worker-side
+ * RemoteRoot mutations into host-side component renders.
+ */
+/**
+ * Structural subset of the DOM `Worker` interface that the transport needs.
+ * Tests inject a fake; production callers pass the global `Worker`.
+ */
+interface WorkerLike {
+    onmessage: ((ev: MessageEvent) => void) | null;
+    onerror: ((ev: ErrorEvent) => void) | null;
+    onmessageerror: ((ev: MessageEvent) => void) | null;
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+/**
+ * Constructor signature compatible with the DOM `Worker` constructor. The
+ * `workerCtor` option exists exclusively so tests can swap in a fake — in
+ * production the caller passes the global `Worker`.
+ */
+type WorkerCtor = new (url: string | URL, options?: WorkerOptions) => WorkerLike;
+/**
+ * Discriminated union of MCP fetch shapes the host transport issues. The
+ * `capabilityToken` is attached on the host side ONLY — it is never present
+ * in any message that crosses the worker port.
+ */
+type McpHttpRequest = {
+    kind: "invokeTool";
+    name: string;
+    args: unknown;
+    capabilityToken: string;
+    signal?: AbortSignal;
+} | {
+    kind: "getResource";
+    uri: string;
+    capabilityToken: string;
+    signal?: AbortSignal;
+};
+/**
+ * Host-side HTTP client for MCP calls. Implementations are responsible for
+ * carrying the supplied `capabilityToken` on the outbound request (typically
+ * via `Authorization: Bearer`).
+ */
+interface McpHttpClient {
+    fetch(request: McpHttpRequest): Promise<{
+        ok: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+}
+/**
+ * Construction options for {@link WorkerRemoteDomTransport}.
+ */
+interface WorkerRemoteDomTransportOptions {
+    /**
+     * Canonical host-origin URL for the worker bootstrap script. This MUST
+     * be supplied by the host — never built from user input or extension
+     * manifest values — so the worker spawn is path-pinned.
+     */
+    bootstrapUrl: string;
+    /**
+     * Mints (or fetches a cached) capability token. The host transport
+     * resolves this for each outbound MCP HTTP call. The token NEVER leaves
+     * host scope — plugin code (the worker side) cannot read it.
+     */
+    capabilityToken: () => Promise<string>;
+    /**
+     * Host-side MCP HTTP client. The transport bridges port-side plugin
+     * MCP requests to this client and returns only the response payload
+     * back through the port.
+     */
+    mcpClient: McpHttpClient;
+    /**
+     * Injectable Worker constructor (tests use a fake). Defaults to the
+     * global `Worker`.
+     */
+    workerCtor?: WorkerCtor;
+    /**
+     * Coalescing window in milliseconds for high-frequency events. Defaults
+     * to 16ms (~one animation frame). Trailing-edge: the most recent payload
+     * within the window is delivered after the window elapses.
+     */
+    coalesceMs?: number;
+    /**
+     * Maximum number of MCP requests (combined `invokeTool` + `getResource`)
+     * the transport will forward to {@link mcpClient} concurrently. Defaults
+     * to 8. Requests above the cap are rejected with a deterministic error
+     * reply over the port — the worker MUST handle that response shape.
+     *
+     * Bounded concurrency is a back-pressure boundary, not a quota: it stops
+     * a compromised or buggy worker from saturating the host's HTTP / token
+     * pool. Production hosts may want to lower this in multi-tenant pools
+     * where many extensions share one host process.
+     */
+    maxConcurrentMcpRequests?: number;
+}
+/**
+ * Wire shape of a host-sourced input event forwarded to the worker over the
+ * port. Pointer / wheel / keyboard payloads share a single envelope type so
+ * the worker has one inbound dispatch site. The transport is structurally
+ * agnostic to the payload — it forwards verbatim.
+ *
+ * `kind` discriminates the event family. Coordinates are CSS pixels relative
+ * to the host canvas; coalescing happens host-side before the call to
+ * {@link WorkerRemoteDomTransport.postInputEvent}.
+ */
+type InputEventPayload = {
+    kind: "pointermove" | "pointerdown" | "pointerup" | "pointercancel";
+    surfaceId: string;
+    x: number;
+    y: number;
+    buttons: number;
+    pointerType: string;
+} | {
+    kind: "wheel";
+    surfaceId: string;
+    deltaX: number;
+    deltaY: number;
+    deltaMode: number;
+} | {
+    kind: "keydown" | "keyup";
+    surfaceId: string;
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+};
+/**
+ * Documented wire protocol identifier embedded in handshake / message
+ * envelopes. Bumped when the worker ↔ host message shape changes in a
+ * backward-incompatible way.
+ */
+declare const WORKER_TRANSPORT_PROTOCOL = "ethisys.worker.remotedom.v1";
+/**
+ * Wire shape of the handshake message the host posts to the worker on
+ * {@link WorkerRemoteDomTransport.connect}. Locked here so the SDK side and the
+ * API-hosted bootstrap script (`WorkerBootstrapScriptProvider`) read from the
+ * same field names — see the API tests pinning `event.data.moduleUrl` and
+ * `event.data.importMap`.
+ *
+ * The handshake is the SOLE message that ever carries `moduleUrl` or
+ * `importMap`; subsequent port traffic uses the discriminated message types
+ * declared below. The capability token NEVER appears in this payload (or any
+ * other postMessage payload) — it is bound on the host side via
+ * {@link WorkerRemoteDomTransportOptions.capabilityToken}.
+ */
+interface WorkerHandshakePayload {
+    readonly type: "ethisys:worker:handshake";
+    readonly protocol: string;
+    /** Host-origin URL of the plugin's worker bundle entry. */
+    readonly moduleUrl: string;
+    /**
+     * Frozen bare-specifier → host-origin URL map that the bootstrap installs
+     * before importing {@link moduleUrl}. Pulled from the plugin's
+     * `worker-bundle.import-map.json` at runtime by the host mount.
+     */
+    readonly importMap: Readonly<Record<string, string>>;
+}
+/**
+ * Worker-side host transport for Contract B extensions.
+ *
+ * Construction immediately spawns the worker and transfers one end of a
+ * fresh `MessageChannel`; the host retains `port1`, the worker receives
+ * `port2`. Both sides exchange messages via their port and the worker port
+ * is the *only* channel for plugin ↔ host traffic after handshake.
+ */
+/**
+ * Default cap for in-flight MCP requests forwarded by the transport. Chosen to
+ * cover typical interactive UI traffic (dashboards, list views, detail panels)
+ * without letting a runaway worker saturate the host's HTTP / token pool.
+ */
+declare const DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = 8;
+declare class WorkerRemoteDomTransport {
+    private readonly worker;
+    private readonly hostPort;
+    private readonly workerPort;
+    private readonly mcpClient;
+    private readonly capabilityTokenProvider;
+    private readonly coalesceMs;
+    private readonly maxConcurrentMcpRequests;
+    private readonly abortController;
+    private inFlightMcpRequests;
+    private remoteDomConsumer;
+    private disposed;
+    private connected;
+    constructor(options: WorkerRemoteDomTransportOptions);
+    /**
+     * Post the handshake to the worker. Idempotent — only the FIRST call
+     * transfers the {@link MessagePort} and posts the handshake payload;
+     * subsequent calls are silent no-ops. Splitting this off from the
+     * constructor lets the host mount fetch the per-plugin
+     * `worker-bundle.import-map.json` (and resolve the bundle's module URL)
+     * before the bootstrap script consumes them.
+     *
+     * Wire shape: {@link WorkerHandshakePayload}. The capability token NEVER
+     * appears in the payload — it's bound on the host side via the
+     * {@link WorkerRemoteDomTransportOptions.capabilityToken} provider.
+     *
+     * The `moduleUrl` and `importMap` are forwarded to the worker so the
+     * bootstrap script (served from the host-pinned
+     * `/extensions/runtime/worker-bootstrap.js`) can:
+     *   1. Compose the frozen, same-origin-validated `IMPORT_MAP` from the
+     *      handshake payload (rejecting any cross-origin entries).
+     *   2. `safeImport(moduleUrl)` the plugin's entry module.
+     *
+     * Same-origin enforcement is the bootstrap's job — this transport is
+     * structurally agnostic to the host origin and only forwards what it's
+     * handed.
+     */
+    connect(moduleUrl: string, importMap: Record<string, string>): void;
+    /**
+     * Bind a consumer for Remote DOM mutation payloads emitted by the worker.
+     * The Remote DOM receiver wiring is owned by the caller (typically a host
+     * React component); this method exposes the raw stream so the receiver
+     * can integrate cleanly without a circular package import.
+     */
+    onRemoteDom(consumer: (payload: unknown) => void): void;
+    /**
+     * Transfer control of a host-owned `<canvas>` to the worker so plugin code
+     * can render via `OffscreenCanvas`. The host retains the `<canvas>` for
+     * layout / accessibility purposes only — every pixel is produced inside the
+     * worker, so the main thread is never blocked per frame.
+     *
+     * The transfer rides the established MessagePort (not the worker global
+     * `postMessage`) so it is multiplexed with the rest of the host ↔ worker
+     * traffic on the same channel. The `OffscreenCanvas` handle is the sole
+     * `Transferable` in the envelope; no capability token, MCP context, or
+     * other host-only data crosses the boundary.
+     *
+     * Throws if the environment lacks `transferControlToOffscreen()` or if the
+     * canvas has already been transferred — see {@link createOffscreenCanvasTransfer}
+     * for the exact diagnostics.
+     */
+    transferCanvas(canvas: HTMLCanvasElement, options: {
+        surfaceId: string;
+    }): {
+        offscreen: OffscreenCanvas;
+    };
+    /**
+     * Forward a host-sourced input event to the worker over the port. The
+     * payload shape is opaque to the transport — pointer / wheel / keyboard
+     * envelopes share the same wire type. Callers are expected to wrap
+     * high-frequency (pointer-move, wheel, scroll) events in
+     * {@link createCoalescer} or {@link createInputEventCoalescer} BEFORE
+     * calling this method so the port never sees the un-coalesced flood.
+     *
+     * Keyboard / pointer-down / pointer-up events are discrete and should be
+     * delivered without coalescing — pass them straight through.
+     */
+    postInputEvent(payload: InputEventPayload): void;
+    /**
+     * Build a trailing-edge coalescer keyed to {@link WorkerRemoteDomTransportOptions.coalesceMs}.
+     *
+     * Use it to wrap pointer-move / scroll / resize callbacks **before**
+     * they cross the port. The last payload in any coalescing window is the
+     * one that wins.
+     */
+    createCoalescer<T>(consumer: (payload: T) => void): (payload: T) => void;
+    /**
+     * Tear down the worker and port. Idempotent.
+     *
+     * Order matters: we abort BEFORE closing the port so any in-flight
+     * `mcpClient.fetch` that observes the signal short-circuits and the
+     * subsequent attempt to post a reply lands in the disposed-guard branch
+     * (which silently drops the post) instead of throwing on a closed port.
+     */
+    dispose(): void;
+    /**
+     * Best-effort wrapper around `hostPort.postMessage` that tolerates posts
+     * arriving after {@link dispose}. The browser throws on a closed port and
+     * the async handlers below can race dispose, so any post initiated by an
+     * awaited continuation must be guarded.
+     */
+    private safePostMessage;
+    private handlePortMessage;
+    /**
+     * Gate inbound MCP requests through the bounded concurrency window,
+     * reject with a deterministic error reply when the cap is exceeded, and
+     * decrement the counter unconditionally when the underlying handler
+     * settles (regardless of resolution/rejection shape).
+     */
+    private dispatchMcp;
+    private handleInvokeTool;
+    private handleGetResource;
+    private replyError;
+}
+
+export { DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, type InputEventPayload as I, type McpHttpClient as M, WORKER_TRANSPORT_PROTOCOL as W, type McpHttpRequest as a, type WorkerCtor as b, type WorkerHandshakePayload as c, type WorkerLike as d, WorkerRemoteDomTransport as e, type WorkerRemoteDomTransportOptions as f };

package/dist/transport-DVn2GVZh.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Transport contract used by the plugin-side React hooks
+ * (`useMcpResource`, `useMcpTool`) to talk to the host.
+ *
+ * The hooks are deliberately transport-agnostic: the concrete implementation
+ * (postMessage bridge, in-process direct call, fetch-based, …) is injected
+ * via {@link ExtensionRuntimeProvider} or the per-hook `transport` option.
+ * This keeps the React surface stable across Contract A (host-rendered) and
+ * Contract B (worker remote-runtime) execution modes.
+ *
+ * Implementations must honour the supplied {@link AbortSignal} for
+ * cancellation — hooks rely on it to tear down in-flight calls on unmount
+ * or argument changes.
+ */
+interface McpTransport {
+    /**
+     * Fetch a resource by URI. Implementations should reject with an `Error`
+     * when the host returns a failure, and should observe `signal` to abort
+     * any in-flight work.
+     */
+    getResource<T>(uri: string, signal?: AbortSignal): Promise<{
+        uri: string;
+        data: T;
+    }>;
+    /**
+     * Invoke a tool by name. The request object is opaque to the transport.
+     * Implementations should observe `signal` to abort in-flight work.
+     */
+    invokeTool<TReq, TRes>(name: string, args: TReq, signal?: AbortSignal): Promise<TRes>;
+}
+
+export type { McpTransport as M };

package/dist/transport-DVn2GVZh.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Transport contract used by the plugin-side React hooks
+ * (`useMcpResource`, `useMcpTool`) to talk to the host.
+ *
+ * The hooks are deliberately transport-agnostic: the concrete implementation
+ * (postMessage bridge, in-process direct call, fetch-based, …) is injected
+ * via {@link ExtensionRuntimeProvider} or the per-hook `transport` option.
+ * This keeps the React surface stable across Contract A (host-rendered) and
+ * Contract B (worker remote-runtime) execution modes.
+ *
+ * Implementations must honour the supplied {@link AbortSignal} for
+ * cancellation — hooks rely on it to tear down in-flight calls on unmount
+ * or argument changes.
+ */
+interface McpTransport {
+    /**
+     * Fetch a resource by URI. Implementations should reject with an `Error`
+     * when the host returns a failure, and should observe `signal` to abort
+     * any in-flight work.
+     */
+    getResource<T>(uri: string, signal?: AbortSignal): Promise<{
+        uri: string;
+        data: T;
+    }>;
+    /**
+     * Invoke a tool by name. The request object is opaque to the transport.
+     * Implementations should observe `signal` to abort in-flight work.
+     */
+    invokeTool<TReq, TRes>(name: string, args: TReq, signal?: AbortSignal): Promise<TRes>;
+}
+
+export type { McpTransport as M };