@guuey/mcp-apps-host 0.3.1 → 0.5.0

package/dist/sandbox-page.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Sandbox-PAGE document delivery — the client half of the two-origin mount
+ * (guuey#135 wave-3c, from the #186/#135 dogfood's finding 2).
+ *
+ * ## Why a second mount mode exists
+ *
+ * The default `<GuueyView>` mount is a `srcdoc` frame: zero configuration,
+ * opaque origin, correct sandbox posture — but a `srcdoc` document INHERITS
+ * the embedding page's Content-Security-Policy, so the strongest egress
+ * confinement it can have is whatever the embedder's page happens to carry.
+ * Guuey's production surfaces confine harder: the untrusted document mounts
+ * inside a HOST-SERVED sandbox page on a second origin, whose per-request
+ * CSP names exactly the egress that mount is entitled to (see the platform's
+ * `/mcp-app-sandbox` route — per-channel `connect-src`, per-app
+ * `frame-ancestors`). This module speaks that page's delivery protocol so
+ * any kit consumer can opt into the same confinement.
+ *
+ * ## The protocol (co-owned in-repo; two notifications)
+ *
+ * The page is the reference sandbox relay (adapted from the MCP ext-apps
+ * `basic-host` example, vendored at
+ * `create-agentic-app/templates-src/base/web/sandbox-proxy.ts` and served by
+ * the platform's landing route). Its wire is exactly two JSON-RPC
+ * notifications:
+ *
+ *  1. page → host: `ui/notifications/sandbox-proxy-ready` — the relay booted
+ *     and is listening;
+ *  2. host → page: `ui/notifications/sandbox-resource-ready` with
+ *     `params.html` (+ optional `params.sandbox` tokens for the INNER frame —
+ *     the page strips `allow-same-origin` from any value regardless).
+ *
+ * Every other message crosses the page transparently in both directions,
+ * which is why `attachViewHost` works unchanged on top of this delivery: the
+ * view's `ui/initialize` arrives relayed with `event.source` still the OUTER
+ * frame's window, and the host's answers relay inward.
+ *
+ * ## Identity + targeting
+ *
+ * Inbound messages are matched by `event.source === frame.contentWindow` —
+ * the package's standing identity invariant (`view-host.ts`). Outbound
+ * delivery targets `config.pageOrigin` EXPLICITLY (never `'*'`): unlike a
+ * srcdoc view, the sandbox page has a real origin, and the document being
+ * delivered is agent-generated content the caller confined on purpose — if
+ * the frame somehow navigated elsewhere, the browser drops the message
+ * instead of handing the document to the wrong receiver.
+ */
+import type { ViewFrameLike, ViewHostEvents } from "./view-host.js";
+export declare const SANDBOX_PROXY_READY_METHOD = "ui/notifications/sandbox-proxy-ready";
+export declare const SANDBOX_RESOURCE_READY_METHOD = "ui/notifications/sandbox-resource-ready";
+/** Structural check for the page's ready notification. */
+export declare function isSandboxProxyReady(data: unknown): boolean;
+export interface SandboxPageDeliveryConfig {
+    /**
+     * The sandbox page's origin — the ONLY target the document is posted to.
+     * Derive it from the page URL the frame was given (`new URL(url).origin`).
+     */
+    pageOrigin: string;
+    /** The document to deliver (the view's `viewDocumentHtml`). */
+    html: string;
+    /**
+     * Inner-frame sandbox tokens forwarded as `params.sandbox`. The page's
+     * `safeSandbox` strips `allow-same-origin` and guarantees `allow-scripts`
+     * whatever is sent — this only ever WIDENS within the page's own bounds.
+     */
+    sandbox?: string;
+    /** Message-event source, injectable for tests. Default: `window`. */
+    events?: ViewHostEvents;
+}
+/**
+ * Deliver a view document to a mounted sandbox page, re-delivering on every
+ * `sandbox-proxy-ready` (a reloaded page announces again and must be
+ * re-seeded). Returns a detach function.
+ */
+export declare function attachSandboxPageDelivery(frame: ViewFrameLike, config: SandboxPageDeliveryConfig): () => void;
+//# sourceMappingURL=sandbox-page.d.ts.map

package/dist/sandbox-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-page.d.ts","sourceRoot":"","sources":["../src/sandbox-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEpE,eAAO,MAAM,0BAA0B,yCAAyC,CAAC;AACjF,eAAO,MAAM,6BAA6B,4CAA4C,CAAC;AAEvF,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,yBAAyB,GAChC,MAAM,IAAI,CA4BZ"}

package/dist/sandbox-page.js

@@ -0,0 +1,40 @@
+export const SANDBOX_PROXY_READY_METHOD = "ui/notifications/sandbox-proxy-ready";
+export const SANDBOX_RESOURCE_READY_METHOD = "ui/notifications/sandbox-resource-ready";
+/** Structural check for the page's ready notification. */
+export function isSandboxProxyReady(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        !Array.isArray(data) &&
+        data.method === SANDBOX_PROXY_READY_METHOD);
+}
+/**
+ * Deliver a view document to a mounted sandbox page, re-delivering on every
+ * `sandbox-proxy-ready` (a reloaded page announces again and must be
+ * re-seeded). Returns a detach function.
+ */
+export function attachSandboxPageDelivery(frame, config) {
+    const deliver = () => {
+        frame.contentWindow?.postMessage({
+            jsonrpc: "2.0",
+            method: SANDBOX_RESOURCE_READY_METHOD,
+            params: {
+                html: config.html,
+                ...(config.sandbox !== undefined ? { sandbox: config.sandbox } : {}),
+            },
+        }, config.pageOrigin);
+    };
+    const onMessage = (event) => {
+        if (frame.contentWindow === null || event.source !== frame.contentWindow)
+            return;
+        if (isSandboxProxyReady(event.data))
+            deliver();
+    };
+    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);
+}

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"}