@guuey/mcp-apps-host 0.4.0 → 0.6.0

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

@@ -0,0 +1,211 @@
+/**
+ * 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";
+import type { McpResourceReadResult } from "./reader.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";
+/**
+ * The standard MCP method a view uses to read host-proxied resources —
+ * `ReadResourceRequest` in the spec's App→Host request union
+ * (`@modelcontextprotocol/ext-apps` `AppRequest`). A local constant, same
+ * as {@link TOOLS_CALL_METHOD}: the string is MCP-core vocabulary the
+ * ext-apps root does not re-export, and this package deliberately carries
+ * no `@modelcontextprotocol/sdk` dependency.
+ */
+export declare const RESOURCES_READ_METHOD = "resources/read";
+/** 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;
+} | {
+    /**
+     * A `resources/read` the config accepted for relaying (spec surface:
+     * `ReadResourceRequest` rides the App→Host union, and the matching
+     * advertisement is `hostCapabilities.serverResources`). The glue runs
+     * the read hook and posts {@link resourceReadResponse}. Only emitted
+     * when {@link ViewHostBehavior.resourceRelay} is true — unwired, the
+     * machine refuses in-band like every other unsupported request.
+     */
+    kind: "relay-resource-read";
+    id: ViewRequestId;
+    uri: string;
+} | {
+    /**
+     * The view reported its content size (`ui/notifications/size-changed`
+     * — spec notification, App → Host). At least one of the two fields is
+     * a finite number; a notification carrying neither is consumed
+     * silently instead. The glue forwards this to the embedder
+     * ({@link AttachViewHostConfig.onSizeChanged} in `view-host.ts`) —
+     * whether/how to resize the frame is the embedder's layout decision,
+     * never the machine's.
+     */
+    kind: "size-changed";
+    width?: number;
+    height?: number;
+};
+/**
+ * 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;
+    /** Whether a `resources/read` relay hook is wired (see `view-host.ts`). */
+    resourceRelay: 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;
+/**
+ * Build the in-band response for a relayed `resources/read`. An entry
+ * becomes the spec's `ReadResourceResult` (`contents: [entry]`); `undefined`
+ * — a miss, a deny, or a relay failure alike — becomes the one
+ * `Resource not found` error (deny == miss, {@link RESOURCE_NOT_FOUND}).
+ */
+export declare function resourceReadResponse(id: ViewRequestId, entry: McpResourceReadResult | undefined): 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":"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"}

package/dist/view-host-protocol.js

@@ -0,0 +1,230 @@
+/**
+ * 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, SIZE_CHANGED_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";
+/**
+ * The standard MCP method a view uses to read host-proxied resources —
+ * `ReadResourceRequest` in the spec's App→Host request union
+ * (`@modelcontextprotocol/ext-apps` `AppRequest`). A local constant, same
+ * as {@link TOOLS_CALL_METHOD}: the string is MCP-core vocabulary the
+ * ext-apps root does not re-export, and this package deliberately carries
+ * no `@modelcontextprotocol/sdk` dependency.
+ */
+export const RESOURCES_READ_METHOD = "resources/read";
+/**
+ * MCP's `Resource not found` JSON-RPC code — the one answer for a miss, a
+ * transport deny, AND a relay failure (deny == miss: the reader discipline,
+ * `reader.ts` — the view gets no oracle for which locators resolve).
+ */
+const RESOURCE_NOT_FOUND = -32002;
+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 };
+}
+/**
+ * Build the in-band response for a relayed `resources/read`. An entry
+ * becomes the spec's `ReadResourceResult` (`contents: [entry]`); `undefined`
+ * — a miss, a deny, or a relay failure alike — becomes the one
+ * `Resource not found` error (deny == miss, {@link RESOURCE_NOT_FOUND}).
+ */
+export function resourceReadResponse(id, entry) {
+    if (entry === undefined) {
+        return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: RESOURCE_NOT_FOUND, message: "resource unavailable" },
+        };
+    }
+    return { jsonrpc: "2.0", id, result: { contents: [entry] } };
+}
+/**
+ * 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, surface the one
+        // the embedder may act on; consume the rest.
+        if (req.method === "ui/notifications/initialized" && !state.initializedSeen) {
+            return { state: { ...state, initializedSeen: true }, effects: [] };
+        }
+        if (req.method === SIZE_CHANGED_METHOD) {
+            const width = req.params?.["width"];
+            const height = req.params?.["height"];
+            const validWidth = typeof width === "number" && Number.isFinite(width);
+            const validHeight = typeof height === "number" && Number.isFinite(height);
+            if (validWidth || validHeight) {
+                return {
+                    state,
+                    effects: [
+                        {
+                            kind: "size-changed",
+                            ...(validWidth ? { width } : {}),
+                            ...(validHeight ? { height } : {}),
+                        },
+                    ],
+                };
+            }
+        }
+        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.
+    }
+    if (req.method === RESOURCES_READ_METHOD && behavior.resourceRelay) {
+        const uri = req.params?.["uri"];
+        if (typeof uri === "string") {
+            return { state, effects: [{ kind: "relay-resource-read", id: req.id, uri }] };
+        }
+        // fall through: a uri-less read is not a read we can relay.
+    }
+    const answered = [
+        INITIALIZE_METHOD,
+        ...(behavior.toolRelay ? [TOOLS_CALL_METHOD] : []),
+        ...(behavior.resourceRelay ? [RESOURCES_READ_METHOD] : []),
+    ];
+    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 ${answered.join(", ")} 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,142 @@
+/**
+ * `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 { McpResourceReadResult } from "./reader.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;
+    /**
+     * The `resources/read` relay — a PRIVILEGE boundary like
+     * {@link onCallTool}, default off: with no hook, the machine refuses
+     * `resources/read` in-band and advertises no `serverResources`. The hook
+     * is structurally the SAME transport `createMcpUiResourceReader`
+     * assembles over ({@link CreateMcpUiResourceReaderDeps.readResource}) —
+     * a host with a locator reader wires the identical function here. Trust
+     * rules ride the reader discipline (`reader.ts`): enforcement lives
+     * INSIDE the transport; a miss, a deny, and a throw all answer the view
+     * with the one `Resource not found` error (deny == miss — no oracle).
+     */
+    onReadResource?: (uri: string) => Promise<McpResourceReadResult | undefined>;
+    /**
+     * The view reported its content size (`ui/notifications/size-changed` —
+     * spec notification). Whether and how to resize the frame is the
+     * embedder's layout decision; `<GuueyView autoResize>` is one wiring of
+     * exactly this callback.
+     */
+    onSizeChanged?: (size: {
+        width?: number;
+        height?: number;
+    }) => void;
+    /** 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,EASL,KAAK,aAAa,EAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,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;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;IAC7E;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpE,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;AAoDD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAkFlG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAcnF"}