@ethisyscore/extension-runtime 1.6.2 → 1.7.0

package/dist/plugin/index.d.cts

@@ -1,6 +1,7 @@
 import { M as McpTransport } from '../transport-DVn2GVZh.cjs';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
+import { RemoteConnection } from '@remote-dom/core';
 
 interface ExtensionRuntimeProviderProps {
     transport: McpTransport;
@@ -75,6 +76,66 @@ interface UseMcpToolResult<TReq, TRes> {
  */
 declare function useMcpTool<TReq, TRes>(toolName: string, opts?: UseMcpToolOptions): UseMcpToolResult<TReq, TRes>;
 
+/**
+ * Result shape returned by {@link useMcpQuery}. Mirrors the host-app
+ * `react-query`-style envelope so consumers can render loading / error /
+ * data states declaratively. `refetch` is stable across renders.
+ */
+interface UseMcpQueryResult<TRes> {
+    data: TRes | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    /** Re-run the fetch against the current args. Stable across renders. */
+    refetch: () => void;
+}
+/**
+ * Options for {@link useMcpQuery}.
+ */
+interface UseMcpQueryOptions {
+    /**
+     * Gate the fetch on a guard. When false, the hook returns idle state and
+     * never invokes — important because hooks must be called unconditionally
+     * at the top of the component, so an `enabled` flag is the standard way
+     * to express "fetch only when a selection is present" without violating
+     * the rules of hooks. Defaults to `true`.
+     */
+    enabled?: boolean;
+}
+/**
+ * Auto-fetch wrapper over the imperative {@link useMcpTool}. Fires the tool
+ * call on mount AND whenever the serialised `args` change. Use for
+ * read-shaped MCP tool calls that back a component's render data; for
+ * mutations, call {@link useMcpTool} directly and trigger
+ * `invoke(...)` from event handlers.
+ *
+ * Why this lives alongside {@link useMcpTool}: many plugin MCP tools are
+ * effectively queries (`list-tasks`, `get-pending-approvals`, …) — paginated
+ * lookups that change with filter inputs. The base hook's imperative
+ * `invoke` signature is correct for mutations but ergonomically wrong for
+ * reads, where every consumer ends up writing the same `useEffect` +
+ * AbortController + cancellation-on-unmount boilerplate. This hook absorbs
+ * that boilerplate once.
+ *
+ * @template TArgs The request shape sent to the tool.
+ * @template TRes  The response shape the tool returns.
+ */
+declare function useMcpQuery<TArgs, TRes>(toolName: string, args: TArgs, options?: UseMcpQueryOptions): UseMcpQueryResult<TRes>;
+/**
+ * Envelope shape that covers both `{ items: T[] }` and `{ rows: T[] }`
+ * conventions emitted by platform / plugin MCP read tools. Optional both
+ * sides so empty responses still type-check.
+ */
+interface ItemsResponse<T> {
+    items?: T[];
+    rows?: T[];
+}
+/**
+ * Normalise an {@link ItemsResponse} envelope to a plain array.
+ * Returns `[]` when the response is `undefined` (typical pre-first-fetch
+ * state) or when neither field is populated.
+ */
+declare function unwrapItems<T>(response: ItemsResponse<T> | undefined): T[];
+
 /**
  * Configuration accepted by {@link defineDeclarativePlugin}.
  *
@@ -117,4 +178,223 @@ declare const defineDeclarativePlugin: (cfg: DeclarativePluginConfig) => Declara
  */
 declare const defineEthisysPlugin: <TMount>(cfg: EthisysPluginConfig<TMount>) => EthisysPluginConfig<TMount>;
 
-export { type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, McpTransport, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, defineDeclarativePlugin, defineEthisysPlugin, useMcpResource, useMcpTool };
+/**
+ * Contract B (worker remote-runtime) plugin-side React root.
+ *
+ * # The problem this solves
+ *
+ * A Contract B plugin runs in a sandboxed Web Worker — no `document`, no
+ * `window`, no DOM. The host owns rendering: the worker constructs a
+ * `RemoteElement` tree via `@remote-dom/core`, mutations forward over a
+ * `MessagePort`, the host receives them and commits them to a real React tree
+ * (see `coreconnect-web/src/extensions/runtime/WorkerSurfaceMount.tsx` for the
+ * receiver side).
+ *
+ * Until now plugin authors had to hand-author the `RemoteElement` construction
+ * + mutation forwarding manually. `@remote-dom/react` ships only the host-side
+ * primitives (`createRemoteComponent`, `RemoteRootRenderer`, etc.) — there is
+ * no worker-side React reconciler in the package. This helper provides one.
+ *
+ * # What this is
+ *
+ * The public surface (`createRemoteRoot(port, options)`) plus a working
+ * `react-reconciler` HostConfig that commits to a Remote DOM tree and
+ * forwards mutation records over the `MessagePort` to the host receiver.
+ * Authors call `root.render(<App />)` and the host's `WorkerSurfaceMount`
+ * sees the result.
+ *
+ * # What's NOT plumbed yet (Phase 1 limitation)
+ *
+ * Event-listener round-trip. The host transport currently has no
+ * `ethisys:remotedom:call` channel — `WorkerRemoteDomTransport` only
+ * forwards `ethisys:remotedom` payloads from worker → host, never the
+ * other direction. So a worker-side `onClick={() => ...}` is **registered
+ * locally** but the host can't call it. The reconciler retains every
+ * listener on its in-memory `RemoteElementInstance` so the wiring is ready
+ * the moment the call channel lands; until then, plugin authors should
+ * keep interactive surfaces on Contract A.
+ *
+ * # The API
+ *
+ * ```ts
+ * import { createRemoteRoot } from "@ethisyscore/extension-runtime/plugin";
+ *
+ * export async function activate(port: MessagePort): Promise<void> {
+ *   const root = createRemoteRoot(port);
+ *   root.render(<App />);
+ * }
+ * ```
+ *
+ * `<App />` is plain React. Any component shipped by the host's frozen
+ * import-map allowlist (the closed Contract B primitive vocabulary —
+ * `Button`, `DataTable`, `Form`, `Card`, `Tabs`, `Select`, `Alert`, etc.)
+ * renders. The reconciler walks the React tree and commits to a
+ * `RemoteRootElement`; mutation records forward over the port; the host's
+ * `RemoteReceiver` commits the result into the real React tree.
+ *
+ * # Wire shape
+ *
+ * Every reconciler mutation is posted as
+ * `{ type: "ethisys:remotedom", payload: RemoteMutationRecord[] }` to match
+ * `WorkerRemoteDomTransport`'s `RemoteDomMessage` contract — the host
+ * extracts `payload` and feeds it straight into `receiver.mutate(records)`.
+ * `BatchingRemoteConnection` (controlled via `options.batchMutations`)
+ * collapses contiguous mutations into a single port post per commit.
+ */
+
+/**
+ * Options for {@link createRemoteRoot}. Reserved for forward compatibility —
+ * Phase 1 ships with zero required options. Adding fields here is additive;
+ * removing them is a breaking change.
+ */
+interface CreateRemoteRootOptions {
+    /**
+     * When supplied, the reconciler batches contiguous mutations into a single
+     * `port.postMessage` rather than firing one per mutation. Default `true`
+     * — measurably reduces host-side commit cost on the first render of a
+     * non-trivial tree.
+     */
+    batchMutations?: boolean;
+    /**
+     * Override the connection factory. Reserved for tests; production callers
+     * never pass this. The factory's contract is "build a RemoteConnection
+     * that forwards mutations over the supplied port"; the default uses
+     * `createRemoteConnection` from `@remote-dom/core`.
+     */
+    connectionFactory?: (port: MessagePort) => RemoteConnection;
+}
+/**
+ * Plugin-side React root. Mirrors the shape of `ReactDOMClient.Root` so
+ * authors familiar with `createRoot().render(...)` find the same API on the
+ * worker side.
+ */
+interface RemoteRoot {
+    /**
+     * Render a React element tree against the worker's `RemoteRootElement`.
+     * The reconciler commits to the root, the mutation observer forwards
+     * mutations over the port, the host re-renders. Idempotent — calling
+     * `render` twice with the same element is fine; the reconciler dedupes.
+     */
+    render(element: ReactNode): void;
+    /**
+     * Tear down the reconciled tree and stop forwarding mutations. Authors
+     * should call this from a `Symbol.dispose` or equivalent when the worker
+     * is shutting down — leaking the reconciler holds the `MessagePort` open
+     * and prevents the worker from being collected.
+     */
+    unmount(): void;
+}
+/**
+ * Construct a plugin-side React root that commits to a `RemoteRootElement`
+ * and forwards mutations over the supplied `MessagePort`.
+ *
+ * **API stability:** the function signature is stable for Phase 1. The
+ * options bag is forward-compatible (additive only).
+ *
+ * **Implementation status:** the connection + root construction lands in this
+ * commit. The `react-reconciler` `HostConfig` is a scaffold — `render()`
+ * throws a structured error directing authors to the W1A tracking issue.
+ * Authors should treat this commit as "the API is locked, the reconciler is
+ * being authored." See follow-on commits on the `feature/contract-b-create-remote-root-w1a`
+ * branch.
+ */
+declare function createRemoteRoot(port: MessagePort, options?: CreateRemoteRootOptions): RemoteRoot;
+
+/**
+ * W1B — MessagePort-backed McpTransport for Contract B (worker remote-runtime)
+ * plugins.
+ *
+ * The plugin-side React hooks (`useMcpResource`, `useMcpTool`) consume an
+ * {@link McpTransport} — an abstraction over the host call. Contract A
+ * (host-rendered) plugins pick up the host-injected transport via
+ * `ExtensionRuntimeProvider`. Contract B plugins run in a Web Worker with
+ * no shared object surface — the only channel is the `MessagePort` the
+ * host transferred via `activate(port)`. This helper bridges the two
+ * worlds: it exposes the {@link McpTransport} contract on the worker side
+ * and serialises every call into a request/response envelope over the
+ * port.
+ *
+ * # The protocol on the wire
+ *
+ * The wire shape mirrors `WorkerRemoteDomTransport` (in `host/worker/transport.ts`)
+ * one-for-one — that transport is the host receiver and decides what a "well-
+ * formed" message looks like. Two request shapes, two `:result`-suffixed reply
+ * shapes, one abort envelope. Each call mints a fresh request id (`req-{n}`).
+ *
+ * ```jsonc
+ * // worker → host
+ * { type: "ethisys:mcp:getResource", id: "req-3", uri: "tickets://home" }
+ * { type: "ethisys:mcp:invokeTool",  id: "req-4", name: "tickets:open", args: { ... } }
+ *
+ * // host → worker (matching id, suffixed type)
+ * { type: "ethisys:mcp:getResource:result", id: "req-3", ok: true,  data: { uri, data } }
+ * { type: "ethisys:mcp:invokeTool:result",  id: "req-4", ok: false, error: "..." }
+ * ```
+ *
+ * Requests honour the optional `AbortSignal`. On abort, the transport posts
+ * a `{ type: "ethisys:mcp:abort", id }` envelope so the host can cancel
+ * in-flight work, then rejects the pending promise with an `AbortError`-shaped
+ * `Error` so the consuming hooks see the same shape as native fetch cancellation.
+ *
+ * # Authoring shape
+ *
+ * ```ts
+ * export async function activate(port: MessagePort): Promise<void> {
+ *   const transport = createPortMcpTransport(port);
+ *   const root = createRemoteRoot(port);
+ *   root.render(
+ *     <ExtensionRuntimeProvider transport={transport}>
+ *       <App />
+ *     </ExtensionRuntimeProvider>,
+ *   );
+ * }
+ * ```
+ *
+ * `<App />` uses `useMcpResource` / `useMcpTool` as it would on the host
+ * side; the transport translates each call into the port envelope.
+ */
+
+/**
+ * Options for {@link createPortMcpTransport}. Reserved for forward
+ * compatibility — the public surface is empty in Phase 1.
+ */
+interface CreatePortMcpTransportOptions {
+    /**
+     * Override the request-id generator. Reserved for tests so they can
+     * make request ids deterministic. Production callers never pass this.
+     */
+    requestIdFactory?: () => string;
+    /**
+     * Override the port's `addEventListener` / `removeEventListener` /
+     * `postMessage` triple. Reserved for tests so the transport can be
+     * exercised without instantiating a real MessageChannel.
+     */
+    portShimForTests?: PortShim;
+}
+/**
+ * Minimal subset of the MessagePort surface the transport actually uses.
+ * Exposed so tests can construct a polyfill without faking the full
+ * MessagePort.
+ */
+interface PortShim {
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    postMessage(value: unknown): void;
+}
+/**
+ * Construct an {@link McpTransport} backed by a MessagePort.
+ *
+ * @param port The host-transferred MessagePort for the worker surface.
+ * @param options Reserved for forward compatibility / test injection.
+ *
+ * @returns A transport implementation honouring the {@link McpTransport}
+ *          contract — fetch a resource, invoke a tool, observe abort
+ *          signals, settle the promise on the host's reply envelope.
+ */
+declare function createPortMcpTransport(port: MessagePort | PortShim, options?: CreatePortMcpTransportOptions): McpTransport;
+
+export { type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type ItemsResponse, McpTransport, type PortShim, type RemoteRoot, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, createPortMcpTransport, createRemoteRoot, defineDeclarativePlugin, defineEthisysPlugin, unwrapItems, useMcpQuery, useMcpResource, useMcpTool };

package/dist/plugin/index.d.ts

@@ -1,6 +1,7 @@
 import { M as McpTransport } from '../transport-DVn2GVZh.js';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
+import { RemoteConnection } from '@remote-dom/core';
 
 interface ExtensionRuntimeProviderProps {
     transport: McpTransport;
@@ -75,6 +76,66 @@ interface UseMcpToolResult<TReq, TRes> {
  */
 declare function useMcpTool<TReq, TRes>(toolName: string, opts?: UseMcpToolOptions): UseMcpToolResult<TReq, TRes>;
 
+/**
+ * Result shape returned by {@link useMcpQuery}. Mirrors the host-app
+ * `react-query`-style envelope so consumers can render loading / error /
+ * data states declaratively. `refetch` is stable across renders.
+ */
+interface UseMcpQueryResult<TRes> {
+    data: TRes | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    /** Re-run the fetch against the current args. Stable across renders. */
+    refetch: () => void;
+}
+/**
+ * Options for {@link useMcpQuery}.
+ */
+interface UseMcpQueryOptions {
+    /**
+     * Gate the fetch on a guard. When false, the hook returns idle state and
+     * never invokes — important because hooks must be called unconditionally
+     * at the top of the component, so an `enabled` flag is the standard way
+     * to express "fetch only when a selection is present" without violating
+     * the rules of hooks. Defaults to `true`.
+     */
+    enabled?: boolean;
+}
+/**
+ * Auto-fetch wrapper over the imperative {@link useMcpTool}. Fires the tool
+ * call on mount AND whenever the serialised `args` change. Use for
+ * read-shaped MCP tool calls that back a component's render data; for
+ * mutations, call {@link useMcpTool} directly and trigger
+ * `invoke(...)` from event handlers.
+ *
+ * Why this lives alongside {@link useMcpTool}: many plugin MCP tools are
+ * effectively queries (`list-tasks`, `get-pending-approvals`, …) — paginated
+ * lookups that change with filter inputs. The base hook's imperative
+ * `invoke` signature is correct for mutations but ergonomically wrong for
+ * reads, where every consumer ends up writing the same `useEffect` +
+ * AbortController + cancellation-on-unmount boilerplate. This hook absorbs
+ * that boilerplate once.
+ *
+ * @template TArgs The request shape sent to the tool.
+ * @template TRes  The response shape the tool returns.
+ */
+declare function useMcpQuery<TArgs, TRes>(toolName: string, args: TArgs, options?: UseMcpQueryOptions): UseMcpQueryResult<TRes>;
+/**
+ * Envelope shape that covers both `{ items: T[] }` and `{ rows: T[] }`
+ * conventions emitted by platform / plugin MCP read tools. Optional both
+ * sides so empty responses still type-check.
+ */
+interface ItemsResponse<T> {
+    items?: T[];
+    rows?: T[];
+}
+/**
+ * Normalise an {@link ItemsResponse} envelope to a plain array.
+ * Returns `[]` when the response is `undefined` (typical pre-first-fetch
+ * state) or when neither field is populated.
+ */
+declare function unwrapItems<T>(response: ItemsResponse<T> | undefined): T[];
+
 /**
  * Configuration accepted by {@link defineDeclarativePlugin}.
  *
@@ -117,4 +178,223 @@ declare const defineDeclarativePlugin: (cfg: DeclarativePluginConfig) => Declara
  */
 declare const defineEthisysPlugin: <TMount>(cfg: EthisysPluginConfig<TMount>) => EthisysPluginConfig<TMount>;
 
-export { type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, McpTransport, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, defineDeclarativePlugin, defineEthisysPlugin, useMcpResource, useMcpTool };
+/**
+ * Contract B (worker remote-runtime) plugin-side React root.
+ *
+ * # The problem this solves
+ *
+ * A Contract B plugin runs in a sandboxed Web Worker — no `document`, no
+ * `window`, no DOM. The host owns rendering: the worker constructs a
+ * `RemoteElement` tree via `@remote-dom/core`, mutations forward over a
+ * `MessagePort`, the host receives them and commits them to a real React tree
+ * (see `coreconnect-web/src/extensions/runtime/WorkerSurfaceMount.tsx` for the
+ * receiver side).
+ *
+ * Until now plugin authors had to hand-author the `RemoteElement` construction
+ * + mutation forwarding manually. `@remote-dom/react` ships only the host-side
+ * primitives (`createRemoteComponent`, `RemoteRootRenderer`, etc.) — there is
+ * no worker-side React reconciler in the package. This helper provides one.
+ *
+ * # What this is
+ *
+ * The public surface (`createRemoteRoot(port, options)`) plus a working
+ * `react-reconciler` HostConfig that commits to a Remote DOM tree and
+ * forwards mutation records over the `MessagePort` to the host receiver.
+ * Authors call `root.render(<App />)` and the host's `WorkerSurfaceMount`
+ * sees the result.
+ *
+ * # What's NOT plumbed yet (Phase 1 limitation)
+ *
+ * Event-listener round-trip. The host transport currently has no
+ * `ethisys:remotedom:call` channel — `WorkerRemoteDomTransport` only
+ * forwards `ethisys:remotedom` payloads from worker → host, never the
+ * other direction. So a worker-side `onClick={() => ...}` is **registered
+ * locally** but the host can't call it. The reconciler retains every
+ * listener on its in-memory `RemoteElementInstance` so the wiring is ready
+ * the moment the call channel lands; until then, plugin authors should
+ * keep interactive surfaces on Contract A.
+ *
+ * # The API
+ *
+ * ```ts
+ * import { createRemoteRoot } from "@ethisyscore/extension-runtime/plugin";
+ *
+ * export async function activate(port: MessagePort): Promise<void> {
+ *   const root = createRemoteRoot(port);
+ *   root.render(<App />);
+ * }
+ * ```
+ *
+ * `<App />` is plain React. Any component shipped by the host's frozen
+ * import-map allowlist (the closed Contract B primitive vocabulary —
+ * `Button`, `DataTable`, `Form`, `Card`, `Tabs`, `Select`, `Alert`, etc.)
+ * renders. The reconciler walks the React tree and commits to a
+ * `RemoteRootElement`; mutation records forward over the port; the host's
+ * `RemoteReceiver` commits the result into the real React tree.
+ *
+ * # Wire shape
+ *
+ * Every reconciler mutation is posted as
+ * `{ type: "ethisys:remotedom", payload: RemoteMutationRecord[] }` to match
+ * `WorkerRemoteDomTransport`'s `RemoteDomMessage` contract — the host
+ * extracts `payload` and feeds it straight into `receiver.mutate(records)`.
+ * `BatchingRemoteConnection` (controlled via `options.batchMutations`)
+ * collapses contiguous mutations into a single port post per commit.
+ */
+
+/**
+ * Options for {@link createRemoteRoot}. Reserved for forward compatibility —
+ * Phase 1 ships with zero required options. Adding fields here is additive;
+ * removing them is a breaking change.
+ */
+interface CreateRemoteRootOptions {
+    /**
+     * When supplied, the reconciler batches contiguous mutations into a single
+     * `port.postMessage` rather than firing one per mutation. Default `true`
+     * — measurably reduces host-side commit cost on the first render of a
+     * non-trivial tree.
+     */
+    batchMutations?: boolean;
+    /**
+     * Override the connection factory. Reserved for tests; production callers
+     * never pass this. The factory's contract is "build a RemoteConnection
+     * that forwards mutations over the supplied port"; the default uses
+     * `createRemoteConnection` from `@remote-dom/core`.
+     */
+    connectionFactory?: (port: MessagePort) => RemoteConnection;
+}
+/**
+ * Plugin-side React root. Mirrors the shape of `ReactDOMClient.Root` so
+ * authors familiar with `createRoot().render(...)` find the same API on the
+ * worker side.
+ */
+interface RemoteRoot {
+    /**
+     * Render a React element tree against the worker's `RemoteRootElement`.
+     * The reconciler commits to the root, the mutation observer forwards
+     * mutations over the port, the host re-renders. Idempotent — calling
+     * `render` twice with the same element is fine; the reconciler dedupes.
+     */
+    render(element: ReactNode): void;
+    /**
+     * Tear down the reconciled tree and stop forwarding mutations. Authors
+     * should call this from a `Symbol.dispose` or equivalent when the worker
+     * is shutting down — leaking the reconciler holds the `MessagePort` open
+     * and prevents the worker from being collected.
+     */
+    unmount(): void;
+}
+/**
+ * Construct a plugin-side React root that commits to a `RemoteRootElement`
+ * and forwards mutations over the supplied `MessagePort`.
+ *
+ * **API stability:** the function signature is stable for Phase 1. The
+ * options bag is forward-compatible (additive only).
+ *
+ * **Implementation status:** the connection + root construction lands in this
+ * commit. The `react-reconciler` `HostConfig` is a scaffold — `render()`
+ * throws a structured error directing authors to the W1A tracking issue.
+ * Authors should treat this commit as "the API is locked, the reconciler is
+ * being authored." See follow-on commits on the `feature/contract-b-create-remote-root-w1a`
+ * branch.
+ */
+declare function createRemoteRoot(port: MessagePort, options?: CreateRemoteRootOptions): RemoteRoot;
+
+/**
+ * W1B — MessagePort-backed McpTransport for Contract B (worker remote-runtime)
+ * plugins.
+ *
+ * The plugin-side React hooks (`useMcpResource`, `useMcpTool`) consume an
+ * {@link McpTransport} — an abstraction over the host call. Contract A
+ * (host-rendered) plugins pick up the host-injected transport via
+ * `ExtensionRuntimeProvider`. Contract B plugins run in a Web Worker with
+ * no shared object surface — the only channel is the `MessagePort` the
+ * host transferred via `activate(port)`. This helper bridges the two
+ * worlds: it exposes the {@link McpTransport} contract on the worker side
+ * and serialises every call into a request/response envelope over the
+ * port.
+ *
+ * # The protocol on the wire
+ *
+ * The wire shape mirrors `WorkerRemoteDomTransport` (in `host/worker/transport.ts`)
+ * one-for-one — that transport is the host receiver and decides what a "well-
+ * formed" message looks like. Two request shapes, two `:result`-suffixed reply
+ * shapes, one abort envelope. Each call mints a fresh request id (`req-{n}`).
+ *
+ * ```jsonc
+ * // worker → host
+ * { type: "ethisys:mcp:getResource", id: "req-3", uri: "tickets://home" }
+ * { type: "ethisys:mcp:invokeTool",  id: "req-4", name: "tickets:open", args: { ... } }
+ *
+ * // host → worker (matching id, suffixed type)
+ * { type: "ethisys:mcp:getResource:result", id: "req-3", ok: true,  data: { uri, data } }
+ * { type: "ethisys:mcp:invokeTool:result",  id: "req-4", ok: false, error: "..." }
+ * ```
+ *
+ * Requests honour the optional `AbortSignal`. On abort, the transport posts
+ * a `{ type: "ethisys:mcp:abort", id }` envelope so the host can cancel
+ * in-flight work, then rejects the pending promise with an `AbortError`-shaped
+ * `Error` so the consuming hooks see the same shape as native fetch cancellation.
+ *
+ * # Authoring shape
+ *
+ * ```ts
+ * export async function activate(port: MessagePort): Promise<void> {
+ *   const transport = createPortMcpTransport(port);
+ *   const root = createRemoteRoot(port);
+ *   root.render(
+ *     <ExtensionRuntimeProvider transport={transport}>
+ *       <App />
+ *     </ExtensionRuntimeProvider>,
+ *   );
+ * }
+ * ```
+ *
+ * `<App />` uses `useMcpResource` / `useMcpTool` as it would on the host
+ * side; the transport translates each call into the port envelope.
+ */
+
+/**
+ * Options for {@link createPortMcpTransport}. Reserved for forward
+ * compatibility — the public surface is empty in Phase 1.
+ */
+interface CreatePortMcpTransportOptions {
+    /**
+     * Override the request-id generator. Reserved for tests so they can
+     * make request ids deterministic. Production callers never pass this.
+     */
+    requestIdFactory?: () => string;
+    /**
+     * Override the port's `addEventListener` / `removeEventListener` /
+     * `postMessage` triple. Reserved for tests so the transport can be
+     * exercised without instantiating a real MessageChannel.
+     */
+    portShimForTests?: PortShim;
+}
+/**
+ * Minimal subset of the MessagePort surface the transport actually uses.
+ * Exposed so tests can construct a polyfill without faking the full
+ * MessagePort.
+ */
+interface PortShim {
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    postMessage(value: unknown): void;
+}
+/**
+ * Construct an {@link McpTransport} backed by a MessagePort.
+ *
+ * @param port The host-transferred MessagePort for the worker surface.
+ * @param options Reserved for forward compatibility / test injection.
+ *
+ * @returns A transport implementation honouring the {@link McpTransport}
+ *          contract — fetch a resource, invoke a tool, observe abort
+ *          signals, settle the promise on the host's reply envelope.
+ */
+declare function createPortMcpTransport(port: MessagePort | PortShim, options?: CreatePortMcpTransportOptions): McpTransport;
+
+export { type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type ItemsResponse, McpTransport, type PortShim, type RemoteRoot, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, createPortMcpTransport, createRemoteRoot, defineDeclarativePlugin, defineEthisysPlugin, unwrapItems, useMcpQuery, useMcpResource, useMcpTool };