@ethisyscore/extension-runtime 1.9.2 → 1.11.0

package/dist/bridge-client-CIThO7jZ.d.cts

@@ -0,0 +1,102 @@
+import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-BRKGSiSC.cjs';
+
+/**
+ * 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>;
+}
+
+/**
+ * Plugin-side bridge client for the host ↔ plugin platform contract
+ * (WI 4858 sub-plan 2).
+ *
+ * `createPortBridgeClient` wraps a MessagePort (or an in-realm shim) and
+ * exposes typed subscription callbacks for each host push (theme, locale,
+ * density, a11y, nav, session token) and typed fire-and-wait calls for
+ * chrome requests and a11y live-region announcements.
+ *
+ * For in-realm (Tier T) plugins, use `InMemoryBridgeTransport` from the
+ * mock-host package instead — it calls callbacks synchronously without
+ * any serialisation.
+ */
+
+type ThemePayload = Omit<BridgePushThemeEnvelope, "type">;
+type LocalePayload = Omit<BridgePushLocaleEnvelope, "type">;
+type DensityPayload = Omit<BridgePushDensityEnvelope, "type">;
+type A11yPayload = Omit<BridgePushA11yEnvelope, "type">;
+type NavPayload = Omit<BridgeNavPushEnvelope, "type">;
+type SessionTokenPayload = Omit<BridgeSessionTokenPushEnvelope, "type">;
+/**
+ * Minimal port surface `createPortBridgeClient` actually uses. Matches
+ * `PortShim` in `createPortMcpTransport` — same test-injection pattern.
+ */
+interface BridgePortShim {
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(msg: unknown): void;
+}
+interface PortBridgeClient {
+    /** Replace the theme subscriber. Only the latest subscriber is called. */
+    onTheme(cb: (payload: ThemePayload) => void): void;
+    /** Replace the locale subscriber. */
+    onLocale(cb: (payload: LocalePayload) => void): void;
+    /** Replace the density subscriber. */
+    onDensity(cb: (payload: DensityPayload) => void): void;
+    /** Replace the a11y-preferences subscriber. */
+    onA11y(cb: (payload: A11yPayload) => void): void;
+    /** Replace the nav-state subscriber. */
+    onNav(cb: (payload: NavPayload) => void): void;
+    /** Replace the session-token subscriber. */
+    onSessionToken(cb: (payload: SessionTokenPayload) => void): void;
+    /**
+     * Request a host chrome action. Returns the host's result or rejects with
+     * the host's error string. Callers should catch and surface gracefully.
+     *
+     * @param action "toast" | "confirm" | "openUrl"
+     * @param payload Action-specific payload.
+     */
+    requestChrome(action: string, payload: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Ask the host to make a live-region announcement on behalf of the plugin.
+     * Prefers this over writing directly to the DOM so the host can manage
+     * ARIA live regions centrally.
+     */
+    announceA11y(message: string, politeness: "polite" | "assertive"): void;
+}
+/**
+ * Construct a bridge client backed by a `MessagePort` (or shim).
+ *
+ * Registers a single `onmessage` handler on the port that dispatches each
+ * bridge push to the appropriate subscriber. Unknown message types are
+ * silently ignored — the port carries MCP traffic on the same channel and
+ * those messages must not trigger an error here.
+ */
+declare function createPortBridgeClient(port: BridgePortShim): PortBridgeClient;
+
+export { type A11yPayload as A, type BridgePortShim as B, type DensityPayload as D, type LocalePayload as L, type McpTransport as M, type NavPayload as N, type PortBridgeClient as P, type SessionTokenPayload as S, type ThemePayload as T, createPortBridgeClient as c };

package/dist/bridge-client-UK3qcGoi.d.ts

@@ -0,0 +1,102 @@
+import { d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope, e as BridgeSessionTokenPushEnvelope } from './bridge-envelopes-BRKGSiSC.js';
+
+/**
+ * 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>;
+}
+
+/**
+ * Plugin-side bridge client for the host ↔ plugin platform contract
+ * (WI 4858 sub-plan 2).
+ *
+ * `createPortBridgeClient` wraps a MessagePort (or an in-realm shim) and
+ * exposes typed subscription callbacks for each host push (theme, locale,
+ * density, a11y, nav, session token) and typed fire-and-wait calls for
+ * chrome requests and a11y live-region announcements.
+ *
+ * For in-realm (Tier T) plugins, use `InMemoryBridgeTransport` from the
+ * mock-host package instead — it calls callbacks synchronously without
+ * any serialisation.
+ */
+
+type ThemePayload = Omit<BridgePushThemeEnvelope, "type">;
+type LocalePayload = Omit<BridgePushLocaleEnvelope, "type">;
+type DensityPayload = Omit<BridgePushDensityEnvelope, "type">;
+type A11yPayload = Omit<BridgePushA11yEnvelope, "type">;
+type NavPayload = Omit<BridgeNavPushEnvelope, "type">;
+type SessionTokenPayload = Omit<BridgeSessionTokenPushEnvelope, "type">;
+/**
+ * Minimal port surface `createPortBridgeClient` actually uses. Matches
+ * `PortShim` in `createPortMcpTransport` — same test-injection pattern.
+ */
+interface BridgePortShim {
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(msg: unknown): void;
+}
+interface PortBridgeClient {
+    /** Replace the theme subscriber. Only the latest subscriber is called. */
+    onTheme(cb: (payload: ThemePayload) => void): void;
+    /** Replace the locale subscriber. */
+    onLocale(cb: (payload: LocalePayload) => void): void;
+    /** Replace the density subscriber. */
+    onDensity(cb: (payload: DensityPayload) => void): void;
+    /** Replace the a11y-preferences subscriber. */
+    onA11y(cb: (payload: A11yPayload) => void): void;
+    /** Replace the nav-state subscriber. */
+    onNav(cb: (payload: NavPayload) => void): void;
+    /** Replace the session-token subscriber. */
+    onSessionToken(cb: (payload: SessionTokenPayload) => void): void;
+    /**
+     * Request a host chrome action. Returns the host's result or rejects with
+     * the host's error string. Callers should catch and surface gracefully.
+     *
+     * @param action "toast" | "confirm" | "openUrl"
+     * @param payload Action-specific payload.
+     */
+    requestChrome(action: string, payload: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Ask the host to make a live-region announcement on behalf of the plugin.
+     * Prefers this over writing directly to the DOM so the host can manage
+     * ARIA live regions centrally.
+     */
+    announceA11y(message: string, politeness: "polite" | "assertive"): void;
+}
+/**
+ * Construct a bridge client backed by a `MessagePort` (or shim).
+ *
+ * Registers a single `onmessage` handler on the port that dispatches each
+ * bridge push to the appropriate subscriber. Unknown message types are
+ * silently ignored — the port carries MCP traffic on the same channel and
+ * those messages must not trigger an error here.
+ */
+declare function createPortBridgeClient(port: BridgePortShim): PortBridgeClient;
+
+export { type A11yPayload as A, type BridgePortShim as B, type DensityPayload as D, type LocalePayload as L, type McpTransport as M, type NavPayload as N, type PortBridgeClient as P, type SessionTokenPayload as S, type ThemePayload as T, createPortBridgeClient as c };

package/dist/bridge-envelopes-BRKGSiSC.d.cts

@@ -0,0 +1,63 @@
+/**
+ * Wire-shape constants and type guards for host→plugin bridge push messages
+ * (WI 4858 sub-plan 2). These types ride the existing MessagePort channel
+ * alongside the `ethisys:mcp:*` and `ethisys:remotedom` envelopes — the
+ * `type` discriminant keeps them fully separate at the dispatch site.
+ *
+ * The host posts bridge pushes through `WorkerRemoteDomTransport.hostPort`;
+ * the plugin side reads them in `createPortBridgeClient` (plugin-ui package).
+ * In-realm (Tier T) plugins use `InMemoryBridgeTransport` which calls the
+ * subscriber callbacks directly — no serialisation needed.
+ */
+declare const BRIDGE_PUSH_THEME: "ethisys:bridge:theme";
+declare const BRIDGE_PUSH_LOCALE: "ethisys:bridge:locale";
+declare const BRIDGE_PUSH_DENSITY: "ethisys:bridge:density";
+declare const BRIDGE_PUSH_A11Y: "ethisys:bridge:a11y";
+declare const BRIDGE_NAV_PUSH: "ethisys:bridge:nav";
+declare const BRIDGE_SESSION_TOKEN_PUSH: "ethisys:bridge:token";
+/** Theme push: host → plugin whenever the host theme changes. */
+interface BridgePushThemeEnvelope {
+    readonly type: typeof BRIDGE_PUSH_THEME;
+    /** "light" | "dark" | "high-contrast" */
+    readonly mode: string;
+    /** Flat design-token map (CSS-variable-name → value). May be empty. */
+    readonly tokens: Readonly<Record<string, string>>;
+}
+/** Locale push: host → plugin whenever the active locale changes. */
+interface BridgePushLocaleEnvelope {
+    readonly type: typeof BRIDGE_PUSH_LOCALE;
+    /** BCP 47 tag, e.g. "en-GB". */
+    readonly locale: string;
+    /** "ltr" | "rtl" */
+    readonly dir: "ltr" | "rtl";
+}
+/** Density push: host → plugin when the UI density preference changes. */
+interface BridgePushDensityEnvelope {
+    readonly type: typeof BRIDGE_PUSH_DENSITY;
+    /** "comfortable" | "compact" */
+    readonly density: string;
+}
+/** A11y push: host → plugin when accessibility prefs change. */
+interface BridgePushA11yEnvelope {
+    readonly type: typeof BRIDGE_PUSH_A11Y;
+    readonly reducedMotion: boolean;
+    readonly highContrast: boolean;
+}
+/** Nav push: host → plugin when the SPA location changes. */
+interface BridgeNavPushEnvelope {
+    readonly type: typeof BRIDGE_NAV_PUSH;
+    /** Current SPA path (pathname + search). */
+    readonly path: string;
+    /** `window.history.length` at the time of push. */
+    readonly historyLength: number;
+}
+/** Host → plugin: push a short-lived frontend-session token. */
+interface BridgeSessionTokenPushEnvelope {
+    readonly type: typeof BRIDGE_SESSION_TOKEN_PUSH;
+    /** Opaque JWT string — audience-restricted to the plugin's own backend. */
+    readonly token: string;
+    /** Absolute epoch-ms at which the token expires. Refresh fires 30 s before. */
+    readonly expiresAtMs: number;
+}
+
+export type { BridgeNavPushEnvelope as B, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e };

package/dist/bridge-envelopes-BRKGSiSC.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Wire-shape constants and type guards for host→plugin bridge push messages
+ * (WI 4858 sub-plan 2). These types ride the existing MessagePort channel
+ * alongside the `ethisys:mcp:*` and `ethisys:remotedom` envelopes — the
+ * `type` discriminant keeps them fully separate at the dispatch site.
+ *
+ * The host posts bridge pushes through `WorkerRemoteDomTransport.hostPort`;
+ * the plugin side reads them in `createPortBridgeClient` (plugin-ui package).
+ * In-realm (Tier T) plugins use `InMemoryBridgeTransport` which calls the
+ * subscriber callbacks directly — no serialisation needed.
+ */
+declare const BRIDGE_PUSH_THEME: "ethisys:bridge:theme";
+declare const BRIDGE_PUSH_LOCALE: "ethisys:bridge:locale";
+declare const BRIDGE_PUSH_DENSITY: "ethisys:bridge:density";
+declare const BRIDGE_PUSH_A11Y: "ethisys:bridge:a11y";
+declare const BRIDGE_NAV_PUSH: "ethisys:bridge:nav";
+declare const BRIDGE_SESSION_TOKEN_PUSH: "ethisys:bridge:token";
+/** Theme push: host → plugin whenever the host theme changes. */
+interface BridgePushThemeEnvelope {
+    readonly type: typeof BRIDGE_PUSH_THEME;
+    /** "light" | "dark" | "high-contrast" */
+    readonly mode: string;
+    /** Flat design-token map (CSS-variable-name → value). May be empty. */
+    readonly tokens: Readonly<Record<string, string>>;
+}
+/** Locale push: host → plugin whenever the active locale changes. */
+interface BridgePushLocaleEnvelope {
+    readonly type: typeof BRIDGE_PUSH_LOCALE;
+    /** BCP 47 tag, e.g. "en-GB". */
+    readonly locale: string;
+    /** "ltr" | "rtl" */
+    readonly dir: "ltr" | "rtl";
+}
+/** Density push: host → plugin when the UI density preference changes. */
+interface BridgePushDensityEnvelope {
+    readonly type: typeof BRIDGE_PUSH_DENSITY;
+    /** "comfortable" | "compact" */
+    readonly density: string;
+}
+/** A11y push: host → plugin when accessibility prefs change. */
+interface BridgePushA11yEnvelope {
+    readonly type: typeof BRIDGE_PUSH_A11Y;
+    readonly reducedMotion: boolean;
+    readonly highContrast: boolean;
+}
+/** Nav push: host → plugin when the SPA location changes. */
+interface BridgeNavPushEnvelope {
+    readonly type: typeof BRIDGE_NAV_PUSH;
+    /** Current SPA path (pathname + search). */
+    readonly path: string;
+    /** `window.history.length` at the time of push. */
+    readonly historyLength: number;
+}
+/** Host → plugin: push a short-lived frontend-session token. */
+interface BridgeSessionTokenPushEnvelope {
+    readonly type: typeof BRIDGE_SESSION_TOKEN_PUSH;
+    /** Opaque JWT string — audience-restricted to the plugin's own backend. */
+    readonly token: string;
+    /** Absolute epoch-ms at which the token expires. Refresh fires 30 s before. */
+    readonly expiresAtMs: number;
+}
+
+export type { BridgeNavPushEnvelope as B, BridgePushA11yEnvelope as a, BridgePushDensityEnvelope as b, BridgePushLocaleEnvelope as c, BridgePushThemeEnvelope as d, BridgeSessionTokenPushEnvelope as e };

package/dist/host/index.cjs

@@ -2,6 +2,7 @@
 
 var protocol = require('@ethisyscore/protocol');
 var react = require('react');
+var zod = require('zod');
 var receivers = require('@remote-dom/core/receivers');
 var host = require('@remote-dom/react/host');
 
@@ -286,6 +287,16 @@ function createInputEventCoalescer(sink, options = {}) {
   };
 }
 
+// src/host/worker/bridge-envelopes.ts
+var BRIDGE_PUSH_THEME = "ethisys:bridge:theme";
+var BRIDGE_PUSH_LOCALE = "ethisys:bridge:locale";
+var BRIDGE_PUSH_DENSITY = "ethisys:bridge:density";
+var BRIDGE_PUSH_A11Y = "ethisys:bridge:a11y";
+var BRIDGE_NAV_PUSH = "ethisys:bridge:nav";
+var BRIDGE_CHROME_REQUEST = "ethisys:bridge:chrome:request";
+var BRIDGE_LIFECYCLE_EVENT = "ethisys:bridge:lifecycle";
+var BRIDGE_A11Y_ANNOUNCE = "ethisys:bridge:a11y:announce";
+
 // src/host/worker/transport.ts
 var WORKER_TRANSPORT_PROTOCOL = "ethisys.worker.remotedom.v1";
 var DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = 8;
@@ -300,6 +311,7 @@ var WorkerRemoteDomTransport = class {
   abortController;
   inFlightMcpRequests = 0;
   remoteDomConsumer;
+  bridgeMessageConsumer;
   disposed = false;
   connected = false;
   constructor(options) {
@@ -436,6 +448,39 @@ var WorkerRemoteDomTransport = class {
       }
     };
   }
+  // ─── Bridge push methods (WI 4858 sub-plan 2) ─────────────────────────────
+  /**
+   * Register a consumer for inbound plugin→host bridge messages
+   * (chrome requests, a11y announce, lifecycle events). Only the most recently
+   * registered consumer is kept — the host mount wires exactly one.
+   */
+  onBridgeMessage(consumer) {
+    this.bridgeMessageConsumer = consumer;
+  }
+  /**
+   * Push the current host theme to the plugin worker. Safe to call on every
+   * host theme-context change — the transport coalesces nothing here; rate
+   * limiting at the call site is the host's responsibility.
+   */
+  pushTheme(payload) {
+    this.safePostMessage({ type: BRIDGE_PUSH_THEME, ...payload });
+  }
+  /** Push the current host locale and text direction to the plugin worker. */
+  pushLocale(payload) {
+    this.safePostMessage({ type: BRIDGE_PUSH_LOCALE, ...payload });
+  }
+  /** Push the current UI density preference to the plugin worker. */
+  pushDensity(payload) {
+    this.safePostMessage({ type: BRIDGE_PUSH_DENSITY, ...payload });
+  }
+  /** Push updated accessibility preferences to the plugin worker. */
+  pushA11y(payload) {
+    this.safePostMessage({ type: BRIDGE_PUSH_A11Y, ...payload });
+  }
+  /** Push the current SPA navigation state to the plugin worker. */
+  pushNav(payload) {
+    this.safePostMessage({ type: BRIDGE_NAV_PUSH, ...payload });
+  }
   /**
    * Tear down the worker and port. Idempotent.
    *
@@ -492,6 +537,11 @@ var WorkerRemoteDomTransport = class {
       case "ethisys:remotedom":
         this.remoteDomConsumer?.(message.payload);
         return;
+      case BRIDGE_CHROME_REQUEST:
+      case BRIDGE_A11Y_ANNOUNCE:
+      case BRIDGE_LIFECYCLE_EVENT:
+        this.bridgeMessageConsumer?.(message);
+        return;
       default:
         return;
     }
@@ -581,6 +631,253 @@ var WorkerRemoteDomTransport = class {
     this.safePostMessage({ id, type, ok: false, error: message });
   }
 };
+var IFRAME_BRIDGE_PROTOCOL = "ethisys.iframe.bridge.v1";
+var InboundEnvelope = zod.z.discriminatedUnion("type", [
+  zod.z.object({ type: zod.z.literal("ethisys:mcp:invokeTool"), id: zod.z.string().min(1), name: zod.z.string().min(1), args: zod.z.unknown(), nonce: zod.z.string() }),
+  zod.z.object({ type: zod.z.literal("ethisys:mcp:getResource"), id: zod.z.string().min(1), uri: zod.z.string().min(1), nonce: zod.z.string() }),
+  zod.z.object({ type: zod.z.literal("ethisys:event"), name: zod.z.string().min(1), payload: zod.z.unknown(), nonce: zod.z.string() })
+]);
+function base64url(bytes) {
+  let binary = "";
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function mintNonce() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+var IframeBridgeTransport = class {
+  frameWindowRef;
+  targetOrigin;
+  capabilityTokenProvider;
+  mcpClient;
+  maxConcurrentMcpRequests;
+  maxMessagesPerSecond;
+  onSecurityEvent;
+  abortController = new AbortController();
+  hostPort;
+  framePort;
+  nonce;
+  eventConsumer;
+  inFlightMcpRequests = 0;
+  windowTimestamps = [];
+  connected = false;
+  disposed = false;
+  constructor(options) {
+    this.frameWindowRef = { current: options.frameWindow };
+    this.targetOrigin = options.targetOrigin;
+    this.capabilityTokenProvider = options.capabilityToken;
+    this.mcpClient = options.mcpClient;
+    this.maxConcurrentMcpRequests = Math.max(1, options.maxConcurrentMcpRequests ?? DEFAULT_MAX_CONCURRENT_MCP_REQUESTS);
+    this.maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? 64);
+    this.onSecurityEvent = options.onSecurityEvent;
+  }
+  /**
+   * Post the handshake to the frame. Idempotent — only the FIRST call mints the
+   * nonce, creates the channel, wires the host port, and transfers the frame
+   * port. The handshake uses the exact `targetOrigin` (never `"*"`).
+   */
+  connect() {
+    if (this.connected || this.disposed) {
+      return;
+    }
+    this.connected = true;
+    this.nonce = mintNonce();
+    const channel = new MessageChannel();
+    this.hostPort = channel.port1;
+    this.framePort = channel.port2;
+    this.hostPort.onmessage = (ev) => this.handlePortMessage(ev.data);
+    this.hostPort.start();
+    const handshake = {
+      type: "ethisys:iframe:handshake",
+      protocol: IFRAME_BRIDGE_PROTOCOL,
+      nonce: this.nonce
+    };
+    const frameWindow = this.frameWindowRef.current;
+    frameWindow?.postMessage(handshake, this.targetOrigin, [this.framePort]);
+  }
+  /**
+   * The per-mount handshake nonce (set after {@link connect}, `undefined` before
+   * connect / after dispose). The host mount reads this to validate inbound
+   * cross-origin `window`-level messages (which carry no MessagePort identity).
+   */
+  get connectedNonce() {
+    return this.nonce;
+  }
+  /** Register a consumer for inbound plugin→host `ethisys:event` envelopes. */
+  onEvent(consumer) {
+    this.eventConsumer = consumer;
+  }
+  /**
+   * Push a host→plugin envelope (theme/nav/chrome). Always uses the exact
+   * `targetOrigin` (never `"*"`) and stamps the handshake nonce.
+   */
+  postOutbound(envelope) {
+    if (this.disposed || this.nonce === void 0) {
+      return;
+    }
+    const frameWindow = this.frameWindowRef.current;
+    frameWindow?.postMessage({ ...envelope, nonce: this.nonce }, this.targetOrigin);
+  }
+  /** Tear down. Idempotent. Does NOT remove the iframe (the host mount owns it). */
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    try {
+      this.abortController.abort();
+    } catch {
+    }
+    try {
+      this.hostPort?.close();
+    } catch {
+    }
+    this.nonce = void 0;
+    this.frameWindowRef.current = null;
+  }
+  // ─── Inbound port message handling ────────────────────────────────────────
+  handlePortMessage(data) {
+    if (this.disposed) {
+      return;
+    }
+    const parsed = InboundEnvelope.safeParse(data);
+    if (!parsed.success) {
+      this.onSecurityEvent?.({ reason: "schema-invalid" });
+      return;
+    }
+    const message = parsed.data;
+    if (message.nonce !== this.nonce) {
+      this.onSecurityEvent?.({ reason: "nonce-mismatch" });
+      return;
+    }
+    if (this.isRateLimited()) {
+      this.onSecurityEvent?.({ reason: "rate-limit-exceeded", type: message.type });
+      if (message.type === "ethisys:mcp:invokeTool" || message.type === "ethisys:mcp:getResource") {
+        this.safePostMessage({
+          id: message.id,
+          type: `${message.type}:result`,
+          ok: false,
+          error: "iframe-bridge rate limit exceeded"
+        });
+      }
+      return;
+    }
+    switch (message.type) {
+      case "ethisys:mcp:invokeTool":
+        this.dispatchMcp(message, "ethisys:mcp:invokeTool:result", (m) => this.handleInvokeTool(m));
+        return;
+      case "ethisys:mcp:getResource":
+        this.dispatchMcp(message, "ethisys:mcp:getResource:result", (m) => this.handleGetResource(m));
+        return;
+      case "ethisys:event":
+        this.eventConsumer?.(message.name, message.payload);
+        return;
+    }
+  }
+  isRateLimited() {
+    const now = Date.now();
+    const cutoff = now - 1e3;
+    this.windowTimestamps = this.windowTimestamps.filter((t) => t > cutoff);
+    if (this.windowTimestamps.length >= this.maxMessagesPerSecond) {
+      return true;
+    }
+    this.windowTimestamps.push(now);
+    return false;
+  }
+  // ─── MCP brokering (structurally identical to the worker transport) ───────
+  dispatchMcp(message, resultType, handler) {
+    if (this.inFlightMcpRequests >= this.maxConcurrentMcpRequests) {
+      this.safePostMessage({
+        id: message.id,
+        type: resultType,
+        ok: false,
+        error: `MCP back-pressure: in-flight cap of ${this.maxConcurrentMcpRequests} reached.`
+      });
+      return;
+    }
+    this.inFlightMcpRequests++;
+    handler(message).finally(() => {
+      this.inFlightMcpRequests = Math.max(0, this.inFlightMcpRequests - 1);
+    });
+  }
+  async handleInvokeTool(message) {
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:invokeTool:result", err);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "invokeTool",
+        name: message.name,
+        args: message.args,
+        capabilityToken: token,
+        signal: this.abortController.signal
+      });
+      this.safePostMessage({
+        id: message.id,
+        type: "ethisys:mcp:invokeTool:result",
+        ok: result.ok,
+        data: result.data,
+        error: result.error
+      });
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:invokeTool:result", err);
+    }
+  }
+  async handleGetResource(message) {
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:getResource:result", err);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "getResource",
+        uri: message.uri,
+        capabilityToken: token,
+        signal: this.abortController.signal
+      });
+      this.safePostMessage({
+        id: message.id,
+        type: "ethisys:mcp:getResource:result",
+        ok: result.ok,
+        data: result.data,
+        error: result.error
+      });
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:getResource:result", err);
+    }
+  }
+  replyError(id, type, err) {
+    const message = err instanceof Error ? err.message : "MCP request failed";
+    this.safePostMessage({ id, type, ok: false, error: message });
+  }
+  /** Best-effort reply over the host port; tolerates post-dispose races. */
+  safePostMessage(message) {
+    if (this.disposed || this.hostPort === void 0) {
+      return;
+    }
+    try {
+      this.hostPort.postMessage(message);
+    } catch {
+    }
+  }
+};
 
 Object.defineProperty(exports, "RemoteReceiver", {
   enumerable: true,
@@ -597,6 +894,8 @@ Object.defineProperty(exports, "createRemoteComponentRenderer", {
 exports.CONTRACT_B_PRIMITIVES = CONTRACT_B_PRIMITIVES;
 exports.DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = DEFAULT_MAX_CONCURRENT_MCP_REQUESTS;
 exports.DEFAULT_OFFSCREEN_COALESCE_MS = DEFAULT_OFFSCREEN_COALESCE_MS;
+exports.IFRAME_BRIDGE_PROTOCOL = IFRAME_BRIDGE_PROTOCOL;
+exports.IframeBridgeTransport = IframeBridgeTransport;
 exports.SemanticComponentRegistry = SemanticComponentRegistry;
 exports.WORKER_TRANSPORT_PROTOCOL = WORKER_TRANSPORT_PROTOCOL;
 exports.WorkerRemoteDomTransport = WorkerRemoteDomTransport;