@guuey/mcp-apps-host 0.4.0 → 0.5.0

package/dist/view-host-protocol.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The Host half of the MCP Apps (SEP-1865) App handshake, as a PURE state
+ * machine — message in, `{state, effects}` out, zero DOM (guuey#186 Gap 1).
+ *
+ * ## Why the view hangs without this
+ *
+ * A spec-following App (ggui's iframe-runtime included) opens with
+ * `ui/initialize` posted to its parent and BLOCKS — the handshake runs
+ * before the view reads any seeded boot data, so a frame whose parent
+ * never answers stays blank forever. `toolResultViewMount` prepares the
+ * document; THIS module answers the document. The two halves together are
+ * the Host role the package is named for.
+ *
+ * ## Why a pure machine
+ *
+ * Only a real browser runs the postMessage/sandbox physics, but the
+ * publish gate (guuey-sdks mirror CI) is Node-only — the exact blind spot
+ * that let the missing-host gap ship (mount-material assertions run in
+ * Node; nothing ran the negotiation). So the protocol logic lives here,
+ * exhaustively unit-tested against scripted message sequences, and the DOM
+ * glue in `view-host.ts` stays thin enough to carry no decisions. Even the
+ * negotiation timeout is a machine INPUT ({@link viewHostElapsed}), not a
+ * timer here.
+ *
+ * ## Spec posture
+ *
+ * Types and method names come from `@modelcontextprotocol/ext-apps` — the
+ * SEP-1865 surface itself, someone else's frozen contract. Zero ggui
+ * imports, deliberately (guuey#123): this host answers ANY spec-following
+ * view; everything ggui-specific stays in `ggui-render.ts` behind ggui's
+ * own published protocol package.
+ */
+import { type McpUiHostCapabilities, type McpUiHostContext, type McpUiInitializeResult } from "@modelcontextprotocol/ext-apps";
+import type { McpToolStructuredContent } from "./action.js";
+/**
+ * The host identity in the initialize result — structurally the spec's
+ * `Implementation` (which the ext-apps root does not re-export), narrowed
+ * to the two fields a host must supply.
+ */
+export interface ViewHostInfo {
+    name: string;
+    version: string;
+}
+/** The standard MCP method a view uses to reach host-proxied tools. */
+export declare const TOOLS_CALL_METHOD = "tools/call";
+/** A JSON-RPC id as the wire allows it. */
+export type ViewRequestId = number | string;
+/** The messages this host posts INTO the view frame. */
+export interface ViewHostOutbound {
+    jsonrpc: "2.0";
+    id?: ViewRequestId;
+    method?: string;
+    params?: {
+        [key: string]: unknown;
+    };
+    result?: {
+        [key: string]: unknown;
+    };
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/**
+ * Where the negotiation stands, from the host's side of the boundary.
+ *
+ *  - `"negotiating"` — attached; no `ui/initialize` seen yet. A plain-HTML
+ *    inline card may stay here forever, legitimately: the handshake is how
+ *    a spec App boots, not an obligation on arbitrary tenant HTML.
+ *  - `"connected"` — `ui/initialize` was answered. The view owns its own
+ *    pixels (and its own failures) from here on.
+ *  - `"no-handshake"` — the caller declared the negotiation window over
+ *    ({@link viewHostElapsed}) before any `ui/initialize` arrived. What
+ *    that MEANS depends on the mount channel and is the renderer's call:
+ *    a `"ggui"` shell always handshakes, so this phase is a boot failure
+ *    there; an `"inline"` card may simply not be an App.
+ *
+ * A renderer binds to this — the failure mode must be a labeled state,
+ * never a blank page (guuey#186 audit).
+ */
+export type ViewHostPhase = "negotiating" | "connected" | "no-handshake";
+/** The machine's whole state. Immutable — every transition returns a new one. */
+export interface ViewHostState {
+    phase: ViewHostPhase;
+    /** `ui/notifications/initialized` seen (the App's post-handshake ack). */
+    initializedSeen: boolean;
+}
+export declare function initialViewHostState(): ViewHostState;
+/**
+ * What the glue must DO after a transition. Effects are data so the machine
+ * stays synchronous and Node-testable; the glue performs them.
+ */
+export type ViewHostEffect = {
+    kind: "respond";
+    message: ViewHostOutbound;
+} | {
+    /**
+     * A `tools/call` the config accepted for relaying. The glue runs the
+     * (async) relay hook and posts {@link toolCallResponse} with the
+     * result. Only ever emitted when {@link ViewHostBehavior.toolRelay}
+     * is true — with no relay wired, the machine refuses the call
+     * in-band instead (an honest `method_not_supported`).
+     */
+    kind: "relay-tool-call";
+    id: ViewRequestId;
+    name: string;
+    arguments?: McpToolStructuredContent;
+};
+/**
+ * The host identity/behavior the machine answers with. Everything here is
+ * explicit config — the machine assumes nothing about the embedder.
+ */
+export interface ViewHostBehavior {
+    hostInfo: ViewHostInfo;
+    /**
+     * The capabilities to advertise. Empty is a correct, honest default for
+     * views that ride their own live channel (ggui views do — they boot from
+     * their seeded envelope and talk to their pod directly, so the host's
+     * whole job is unblocking the handshake). Advertise ONLY what the
+     * embedder actually implements: a capability the host does not honor
+     * makes the view attribute later failures to the wrong layer.
+     */
+    hostCapabilities: McpUiHostCapabilities;
+    /** The context handed to the view in the initialize result. */
+    hostContext: McpUiHostContext;
+    /** Whether a `tools/call` relay hook is wired (see `view-host.ts`). */
+    toolRelay: boolean;
+}
+/** The result of feeding one inbound frame (or the timeout) to the machine. */
+export interface ViewHostTransition {
+    state: ViewHostState;
+    effects: ViewHostEffect[];
+}
+/** The spec-canonical answer to `ui/initialize`. Exported for the glue/tests. */
+export declare function initializeResult(behavior: ViewHostBehavior, requestedProtocolVersion: unknown): McpUiInitializeResult;
+/** Build the in-band response for a relayed `tools/call`'s settled result. */
+export declare function toolCallResponse(id: ViewRequestId, result: {
+    [key: string]: unknown;
+}): ViewHostOutbound;
+/**
+ * The spec-mannered farewell a detaching host posts (`ui/resource-teardown`).
+ * Sent WITHOUT an id — a host that is tearing the frame down cannot await a
+ * response, and an id-less JSON-RPC message is a notification the view may
+ * use for cleanup or ignore.
+ */
+export declare function teardownMessage(): ViewHostOutbound;
+/**
+ * Feed one inbound postMessage payload to the machine.
+ *
+ * The contract, exactly:
+ *  - non-RPC data → ignored (not ours);
+ *  - notifications (no id) → consumed silently, JSON-RPC-correctly; the
+ *    `ui/notifications/initialized` ack is remembered on the state;
+ *  - `ui/initialize` → answered spec-canonically; phase → `"connected"`
+ *    (also from `"no-handshake"` — a late handshake still gets answered:
+ *    the timeout labels a state, it does not close the door);
+ *  - `tools/call` with a relay wired → `relay-tool-call` effect;
+ *  - every other REQUEST → `method_not_supported`, honestly.
+ */
+export declare function viewHostReceive(state: ViewHostState, behavior: ViewHostBehavior, data: unknown): ViewHostTransition;
+/**
+ * Declare the negotiation window over. Meaningful only while
+ * `"negotiating"`: a connected view stays connected, and an already-lapsed
+ * one stays lapsed. The caller owns the clock — this machine has none.
+ */
+export declare function viewHostElapsed(state: ViewHostState): ViewHostState;
+//# sourceMappingURL=view-host-protocol.d.ts.map

package/dist/view-host-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-host-protocol.d.ts","sourceRoot":"","sources":["../src/view-host-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,aAAa,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACpC,MAAM,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACpC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,WAAW,GAAG,cAAc,CAAC;AAEzE,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,CAAC;IACrB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAC9C;IACE;;;;;;OAMG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,aAAa,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC,CAAC;AAEN;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,+DAA+D;IAC/D,WAAW,EAAE,gBAAgB,CAAC;IAC9B,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAiCD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,wBAAwB,EAAE,OAAO,GAChC,qBAAqB,CAcvB;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACjC,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,OAAO,GACZ,kBAAkB,CAuDpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAEnE"}

package/dist/view-host-protocol.js

@@ -0,0 +1,168 @@
+/**
+ * The Host half of the MCP Apps (SEP-1865) App handshake, as a PURE state
+ * machine — message in, `{state, effects}` out, zero DOM (guuey#186 Gap 1).
+ *
+ * ## Why the view hangs without this
+ *
+ * A spec-following App (ggui's iframe-runtime included) opens with
+ * `ui/initialize` posted to its parent and BLOCKS — the handshake runs
+ * before the view reads any seeded boot data, so a frame whose parent
+ * never answers stays blank forever. `toolResultViewMount` prepares the
+ * document; THIS module answers the document. The two halves together are
+ * the Host role the package is named for.
+ *
+ * ## Why a pure machine
+ *
+ * Only a real browser runs the postMessage/sandbox physics, but the
+ * publish gate (guuey-sdks mirror CI) is Node-only — the exact blind spot
+ * that let the missing-host gap ship (mount-material assertions run in
+ * Node; nothing ran the negotiation). So the protocol logic lives here,
+ * exhaustively unit-tested against scripted message sequences, and the DOM
+ * glue in `view-host.ts` stays thin enough to carry no decisions. Even the
+ * negotiation timeout is a machine INPUT ({@link viewHostElapsed}), not a
+ * timer here.
+ *
+ * ## Spec posture
+ *
+ * Types and method names come from `@modelcontextprotocol/ext-apps` — the
+ * SEP-1865 surface itself, someone else's frozen contract. Zero ggui
+ * imports, deliberately (guuey#123): this host answers ANY spec-following
+ * view; everything ggui-specific stays in `ggui-render.ts` behind ggui's
+ * own published protocol package.
+ */
+import { INITIALIZE_METHOD, LATEST_PROTOCOL_VERSION, RESOURCE_TEARDOWN_METHOD, } from "@modelcontextprotocol/ext-apps";
+/** JSON-RPC `method not found` — the spec's code, not an invented one. */
+const METHOD_NOT_SUPPORTED = -32601;
+/** The standard MCP method a view uses to reach host-proxied tools. */
+export const TOOLS_CALL_METHOD = "tools/call";
+export function initialViewHostState() {
+    return { phase: "negotiating", initializedSeen: false };
+}
+/** Plain-object narrowing, same idiom as `action.ts`'s `isJsonObjectLike`. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrow untrusted postMessage data to a JSON-RPC envelope this host could
+ * answer. Anything else — other windows' chatter, the view's own non-RPC
+ * messages — is silently not ours (`undefined`), NOT an error: a shared
+ * `message` listener hears the whole page.
+ */
+function asInboundEnvelope(data) {
+    if (!isPlainObject(data))
+        return undefined;
+    if (data["jsonrpc"] !== "2.0")
+        return undefined;
+    const method = data["method"];
+    if (typeof method !== "string")
+        return undefined;
+    const id = data["id"];
+    const params = data["params"];
+    return {
+        ...(typeof id === "number" || typeof id === "string" ? { id } : {}),
+        method,
+        ...(isPlainObject(params) ? { params } : {}),
+    };
+}
+/** The spec-canonical answer to `ui/initialize`. Exported for the glue/tests. */
+export function initializeResult(behavior, requestedProtocolVersion) {
+    // Echo the version the view asked for when it names one — the view is
+    // the side with a fixed runtime; the host has no version-specific
+    // behavior to defend. Absent/malformed, answer with the spec's latest.
+    const protocolVersion = typeof requestedProtocolVersion === "string" && requestedProtocolVersion.length > 0
+        ? requestedProtocolVersion
+        : LATEST_PROTOCOL_VERSION;
+    return {
+        protocolVersion,
+        hostInfo: behavior.hostInfo,
+        hostCapabilities: behavior.hostCapabilities,
+        hostContext: behavior.hostContext,
+    };
+}
+/** Build the in-band response for a relayed `tools/call`'s settled result. */
+export function toolCallResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+/**
+ * The spec-mannered farewell a detaching host posts (`ui/resource-teardown`).
+ * Sent WITHOUT an id — a host that is tearing the frame down cannot await a
+ * response, and an id-less JSON-RPC message is a notification the view may
+ * use for cleanup or ignore.
+ */
+export function teardownMessage() {
+    return { jsonrpc: "2.0", method: RESOURCE_TEARDOWN_METHOD, params: {} };
+}
+/**
+ * Feed one inbound postMessage payload to the machine.
+ *
+ * The contract, exactly:
+ *  - non-RPC data → ignored (not ours);
+ *  - notifications (no id) → consumed silently, JSON-RPC-correctly; the
+ *    `ui/notifications/initialized` ack is remembered on the state;
+ *  - `ui/initialize` → answered spec-canonically; phase → `"connected"`
+ *    (also from `"no-handshake"` — a late handshake still gets answered:
+ *    the timeout labels a state, it does not close the door);
+ *  - `tools/call` with a relay wired → `relay-tool-call` effect;
+ *  - every other REQUEST → `method_not_supported`, honestly.
+ */
+export function viewHostReceive(state, behavior, data) {
+    const req = asInboundEnvelope(data);
+    if (req === undefined)
+        return { state, effects: [] };
+    if (req.id === undefined) {
+        // A notification. Track the one the handshake defines; consume the rest.
+        if (req.method === "ui/notifications/initialized" && !state.initializedSeen) {
+            return { state: { ...state, initializedSeen: true }, effects: [] };
+        }
+        return { state, effects: [] };
+    }
+    if (req.method === INITIALIZE_METHOD) {
+        const result = initializeResult(behavior, req.params?.["protocolVersion"]);
+        return {
+            state: { ...state, phase: "connected" },
+            effects: [{ kind: "respond", message: { jsonrpc: "2.0", id: req.id, result } }],
+        };
+    }
+    if (req.method === TOOLS_CALL_METHOD && behavior.toolRelay) {
+        const name = req.params?.["name"];
+        if (typeof name === "string") {
+            const args = req.params?.["arguments"];
+            return {
+                state,
+                effects: [
+                    {
+                        kind: "relay-tool-call",
+                        id: req.id,
+                        name,
+                        ...(isPlainObject(args) ? { arguments: args } : {}),
+                    },
+                ],
+            };
+        }
+        // fall through: a nameless tools/call is not a call we can relay.
+    }
+    return {
+        state,
+        effects: [
+            {
+                kind: "respond",
+                message: {
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    error: {
+                        code: METHOD_NOT_SUPPORTED,
+                        message: `method_not_supported: ${req.method} — this host answers ${INITIALIZE_METHOD}${behavior.toolRelay ? ` and ${TOOLS_CALL_METHOD}` : ""} only`,
+                    },
+                },
+            },
+        ],
+    };
+}
+/**
+ * Declare the negotiation window over. Meaningful only while
+ * `"negotiating"`: a connected view stays connected, and an already-lapsed
+ * one stays lapsed. The caller owns the clock — this machine has none.
+ */
+export function viewHostElapsed(state) {
+    return state.phase === "negotiating" ? { ...state, phase: "no-handshake" } : state;
+}

package/dist/view-host.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `attachViewHost` — the DOM glue around `view-host-protocol.ts`'s pure
+ * machine (guuey#186 Gap 1). Framework-agnostic: any embedder with an
+ * iframe can play the MCP Apps Host role with one call; `react.tsx` is one
+ * convenience composition of exactly this, and a future full transcript
+ * renderer composes the same primitive differently.
+ *
+ * This module is glue by DESIGN — every decision (what to answer, what to
+ * refuse, when the negotiation window lapses) lives in the machine, which
+ * the Node-only publish gate can test. What genuinely needs a browser is
+ * this file's five moves: listen, identity-filter, post, time, detach —
+ * covered by the monorepo's Playwright leg (`e2e/`), which the guuey-sdks
+ * mirror deliberately does not carry.
+ *
+ * ## The identity filter (security invariant)
+ *
+ * Messages are matched by `event.source === frame.contentWindow`, NEVER by
+ * `event.origin`: a view frame runs `sandbox="allow-scripts"` WITHOUT
+ * `allow-same-origin`, so its origin is opaque — every message it posts
+ * carries `"null"`, a value every other sandboxed frame on the page
+ * shares, identifying nobody. The window handle is the only identity that
+ * names the frame; a frame with no `contentWindow` matches nothing rather
+ * than everything. Responses target `'*'` for the same reason: an opaque
+ * origin is not addressable by name, and the handshake payload carries no
+ * secrets — it is the result the spec defines for any host.
+ *
+ * Seeded from ggui's console `surface-host.ts` (donated, guuey#186 audit);
+ * re-derived here against the pure machine + our own tests.
+ */
+import { type ViewHostPhase } from "./view-host-protocol.js";
+import { type McpToolCallResult, type UiActionRequest } from "./action.js";
+import type { McpUiResourcePayload } from "./block-ui.js";
+import type { McpUiHostCapabilities, McpUiHostContext } from "@modelcontextprotocol/ext-apps";
+import type { ViewHostInfo } from "./view-host-protocol.js";
+/**
+ * The slice of an `HTMLIFrameElement` this host actually touches — a
+ * structural type so Node tests (and non-DOM hosts) can hand in a fake
+ * without a single cast, same injection idiom as the package's readers and
+ * relays. A real iframe element satisfies it as-is.
+ */
+export interface ViewFrameLike {
+    readonly contentWindow: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    readonly clientWidth: number;
+    readonly clientHeight: number;
+}
+/** The inbound side: what this host needs from `window`. */
+export interface ViewHostEvents {
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+        source: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+        source: unknown;
+    }) => void): void;
+}
+export interface AttachViewHostConfig {
+    /**
+     * Capabilities to advertise in the initialize result. Default: `{}` —
+     * correct for views that ride their own live channel (ggui views do;
+     * they boot from their seeded envelope and talk to their pod directly),
+     * and the honest floor for everyone else: advertise only what the
+     * embedder implements. Exception: wiring {@link onCallTool} advertises
+     * `serverTools` automatically — a wired relay IS the implementation —
+     * and an explicit `hostCapabilities.serverTools` still wins.
+     */
+    hostCapabilities?: McpUiHostCapabilities;
+    /** Host identity for the initialize result. */
+    hostInfo?: ViewHostInfo;
+    /**
+     * Extra context merged over the derived defaults (locale from
+     * `navigator`, container dimensions from the frame when it has laid
+     * out — a 0×0 pre-layout reading is a lie the spec type shouldn't be
+     * told). Keys given here win.
+     */
+    hostContext?: McpUiHostContext;
+    /**
+     * The `tools/call` relay — a PRIVILEGE boundary, default off: with no
+     * hook, the machine refuses `tools/call` in-band and advertises no
+     * `serverTools`. Wire `createMcpUiActionRelay` (or your own) to let the
+     * mounted view reach tools over a transport the embedder owns. The
+     * request's `name`/`arguments` are VIEW-CONTROLLED wire data — the hook
+     * owns allowlisting and validation (`createMcpUiActionRelay` does both).
+     */
+    onCallTool?: (request: UiActionRequest) => Promise<McpToolCallResult>;
+    /**
+     * The mounted resource's `ui://` locator — the scope stamped on every
+     * relayed {@link UiActionRequest}. Required for the relay to fire;
+     * `<GuueyView>` fills it from the mount automatically.
+     */
+    resourceUri?: string;
+    /** Observe phase transitions (see {@link ViewHostPhase}). */
+    onPhaseChange?: (phase: ViewHostPhase) => void;
+    /**
+     * How long to wait for `ui/initialize` before declaring
+     * `"no-handshake"` (ms). `0` disables the timer. Default 8000 — a view
+     * runtime negotiates immediately after parse; this bound exists to turn
+     * "blank forever" into a labeled state, not to race slow networks.
+     */
+    negotiationTimeoutMs?: number;
+    /** Message-event source, injectable for tests. Default: `window`. */
+    events?: ViewHostEvents;
+}
+/**
+ * Attach the Host role to a mounted view frame. Returns a detach function;
+ * call it before the frame unmounts — it stops listening and posts the
+ * spec-mannered `ui/resource-teardown` farewell through the CACHED window
+ * handle (post-removal, `frame.contentWindow` is already null).
+ */
+export declare function attachViewHost(frame: ViewFrameLike, config?: AttachViewHostConfig): () => void;
+/**
+ * The document a {@link McpUiResourcePayload} mounts: `text` verbatim, or
+ * `blob` base64-decoded as UTF-8. `undefined` when the payload carries
+ * neither — nothing to put in `srcdoc`.
+ */
+export declare function viewDocumentHtml(resource: McpUiResourcePayload): string | undefined;
+//# sourceMappingURL=view-host.d.ts.map

package/dist/view-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-host.d.ts","sourceRoot":"","sources":["../src/view-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAQL,KAAK,aAAa,EAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE;QAAE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;IACR,mBAAmB,CACjB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;CACT;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AA6BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAgElG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAcnF"}

package/dist/view-host.js

@@ -0,0 +1,143 @@
+/**
+ * `attachViewHost` — the DOM glue around `view-host-protocol.ts`'s pure
+ * machine (guuey#186 Gap 1). Framework-agnostic: any embedder with an
+ * iframe can play the MCP Apps Host role with one call; `react.tsx` is one
+ * convenience composition of exactly this, and a future full transcript
+ * renderer composes the same primitive differently.
+ *
+ * This module is glue by DESIGN — every decision (what to answer, what to
+ * refuse, when the negotiation window lapses) lives in the machine, which
+ * the Node-only publish gate can test. What genuinely needs a browser is
+ * this file's five moves: listen, identity-filter, post, time, detach —
+ * covered by the monorepo's Playwright leg (`e2e/`), which the guuey-sdks
+ * mirror deliberately does not carry.
+ *
+ * ## The identity filter (security invariant)
+ *
+ * Messages are matched by `event.source === frame.contentWindow`, NEVER by
+ * `event.origin`: a view frame runs `sandbox="allow-scripts"` WITHOUT
+ * `allow-same-origin`, so its origin is opaque — every message it posts
+ * carries `"null"`, a value every other sandboxed frame on the page
+ * shares, identifying nobody. The window handle is the only identity that
+ * names the frame; a frame with no `contentWindow` matches nothing rather
+ * than everything. Responses target `'*'` for the same reason: an opaque
+ * origin is not addressable by name, and the handshake payload carries no
+ * secrets — it is the result the spec defines for any host.
+ *
+ * Seeded from ggui's console `surface-host.ts` (donated, guuey#186 audit);
+ * re-derived here against the pure machine + our own tests.
+ */
+import { initialViewHostState, teardownMessage, toolCallResponse, viewHostElapsed, viewHostReceive, } from "./view-host-protocol.js";
+import { unavailableToolCallResult, } from "./action.js";
+const DEFAULT_HOST_INFO = { name: "guuey-view-host", version: "1" };
+const DEFAULT_NEGOTIATION_TIMEOUT_MS = 8000;
+/** Derived + configured context, per the {@link AttachViewHostConfig.hostContext} contract. */
+function hostContextFor(frame, config) {
+    return {
+        locale: typeof navigator !== "undefined" ? navigator.language : "en-US",
+        ...(frame.clientWidth > 0 && frame.clientHeight > 0
+            ? { containerDimensions: { width: frame.clientWidth, height: frame.clientHeight } }
+            : {}),
+        ...config.hostContext,
+    };
+}
+function behaviorFor(frame, config) {
+    const relayWired = config.onCallTool !== undefined && config.resourceUri !== undefined;
+    return {
+        hostInfo: config.hostInfo ?? DEFAULT_HOST_INFO,
+        hostCapabilities: {
+            ...(relayWired ? { serverTools: {} } : {}),
+            ...config.hostCapabilities,
+        },
+        hostContext: hostContextFor(frame, config),
+        toolRelay: relayWired,
+    };
+}
+/**
+ * Attach the Host role to a mounted view frame. Returns a detach function;
+ * call it before the frame unmounts — it stops listening and posts the
+ * spec-mannered `ui/resource-teardown` farewell through the CACHED window
+ * handle (post-removal, `frame.contentWindow` is already null).
+ */
+export function attachViewHost(frame, config = {}) {
+    const cachedWindow = frame.contentWindow;
+    let state = initialViewHostState();
+    const setState = (next) => {
+        const phaseChanged = next.phase !== state.phase;
+        state = next;
+        if (phaseChanged)
+            config.onPhaseChange?.(next.phase);
+    };
+    const post = (message) => {
+        frame.contentWindow?.postMessage(message, "*");
+    };
+    const relay = (id, name, args) => {
+        const { onCallTool, resourceUri } = config;
+        // The machine only emits the effect when the relay is wired (behavior
+        // is derived from this same config), so these are invariants, not
+        // runtime branches a view can steer.
+        if (onCallTool === undefined || resourceUri === undefined)
+            return;
+        onCallTool({ resourceUri, name, ...(args === undefined ? {} : { arguments: args }) }).then((result) => post(toolCallResponse(id, result)), 
+        // A relay hook that rejects (createMcpUiActionRelay never does, but
+        // the hook is embedder code) still owes the view an answer — the
+        // same in-band unavailable the relay itself uses, never a hang.
+        () => post(toolCallResponse(id, unavailableToolCallResult())));
+    };
+    const onMessage = (event) => {
+        if (frame.contentWindow === null || event.source !== frame.contentWindow)
+            return;
+        const { state: next, effects } = viewHostReceive(state, behaviorFor(frame, config), event.data);
+        setState(next);
+        for (const effect of effects) {
+            if (effect.kind === "respond")
+                post(effect.message);
+            else
+                relay(effect.id, effect.name, effect.arguments);
+        }
+    };
+    // One listener, two subscription paths: the injectable seam for Node
+    // tests, and `window` — whose lib.dom listener typing wants the concrete
+    // `MessageEvent` — for the browser default.
+    const subscribe = () => {
+        const { events } = config;
+        if (events !== undefined) {
+            events.addEventListener("message", onMessage);
+            return () => events.removeEventListener("message", onMessage);
+        }
+        const domListener = (event) => onMessage(event);
+        window.addEventListener("message", domListener);
+        return () => window.removeEventListener("message", domListener);
+    };
+    const unsubscribe = subscribe();
+    const timeoutMs = config.negotiationTimeoutMs ?? DEFAULT_NEGOTIATION_TIMEOUT_MS;
+    const timer = timeoutMs > 0 ? setTimeout(() => setState(viewHostElapsed(state)), timeoutMs) : undefined;
+    return () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        unsubscribe();
+        cachedWindow?.postMessage(teardownMessage(), "*");
+    };
+}
+/**
+ * The document a {@link McpUiResourcePayload} mounts: `text` verbatim, or
+ * `blob` base64-decoded as UTF-8. `undefined` when the payload carries
+ * neither — nothing to put in `srcdoc`.
+ */
+export function viewDocumentHtml(resource) {
+    if (typeof resource.text === "string")
+        return resource.text;
+    if (typeof resource.blob === "string") {
+        try {
+            const bytes = Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0));
+            return new TextDecoder().decode(bytes);
+        }
+        catch {
+            // Malformed base64 is producer-side wire data, not an embedder bug —
+            // the honest answer is "no document" (the same labeled state a
+            // payload with neither field gets), not a render-time throw.
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",
@@ -24,14 +24,31 @@
       "types": "./dist/narrowing.d.ts",
       "import": "./dist/narrowing.js",
       "default": "./dist/narrowing.js"
+    },
+    "./react": {
+      "react-native": "./src/react.tsx",
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
     }
   },
   "dependencies": {
     "@ggui-ai/protocol": "0.9.0",
+    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@silverprotocol/core": "0.4.1"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
   },