@guuey/mcp-apps-host 0.3.1 → 0.5.0

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.3.1",
+  "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.6.3",
+    "@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"
   },
@@ -52,10 +69,10 @@
     "url": "git+https://github.com/withguuey/guuey-sdks.git",
     "directory": "packages/mcp-apps-host"
   },
-  "homepage": "https://guuey.com",
   "bugs": {
-    "url": "https://github.com/loqu-co/guuey/issues"
+    "url": "https://github.com/withguuey/guuey-sdks/issues"
   },
+  "homepage": "https://guuey.com",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",

package/src/action.ts

@@ -0,0 +1,171 @@
+/**
+ * The Host role's ACTION side (guuey#158) — the `tools/call` sibling of
+ * `reader.ts`. A mounted card's sandbox posts a runtime action to the host
+ * (SEP-1865 / ggui's relay-host contract); the host relays it over an
+ * AUTHENTICATED transport it owns, and hands the result back in-band. Two
+ * invariants mirror the reader:
+ *
+ *  - the relay NEVER throws into the sandbox bridge: allowlist miss,
+ *    transport failure, and un-narrowable answers all collapse to an
+ *    in-band `isError` result the card can display;
+ *  - runtime re-narrowing, not trust: transports are host-supplied and the
+ *    upstream answer is wire data — every content arm is re-checked before
+ *    it crosses into the sandbox.
+ */
+
+/** The wire arms a relay hands back to the sandbox — re-narrowed, never trusted. */
+export type McpToolCallContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | {
+      type: "resource";
+      resource: { uri: string; mimeType?: string } & (
+        | { text: string }
+        | { blob: string }
+      );
+    };
+
+/**
+ * `structuredContent` is protocol-open by design (the MCP spec types it as
+ * an arbitrary JSON object) — the index signature is the honest wire type,
+ * not an erasure of a known shape.
+ */
+export type McpToolStructuredContent = {
+  [key: string]: unknown;
+};
+
+/**
+ * The SEP-1865 CallToolResult surface a host hands back to the sandbox.
+ * A `type` alias, deliberately: the MCP SDK's own result types carry Zod
+ * passthrough index signatures, and only type aliases (never interfaces)
+ * get the implicit index signature that makes this assignable to them.
+ */
+export type McpToolCallResult = {
+  content: McpToolCallContent[];
+  isError?: boolean;
+  structuredContent?: McpToolStructuredContent;
+};
+
+/**
+ * The runtime-action tools a card sandbox may relay — the client-side twin
+ * of the server allowlist (defense in depth: the proxy enforces it again).
+ */
+export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
+  "ggui_runtime_submit_action",
+]);
+
+/** The in-band answer for anything the relay cannot (or will not) do. */
+export const UI_ACTION_UNAVAILABLE_TEXT =
+  "This action isn't available right now.";
+
+/**
+ * The in-band `isError` result for an action that cannot be performed —
+ * the relay's own refusals use it, and `attachViewHost` posts it when an
+ * embedder-supplied relay hook rejects (the view is always answered).
+ */
+export function unavailableToolCallResult(): McpToolCallResult {
+  return {
+    content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
+    isError: true,
+  };
+}
+
+function isJsonObjectLike(value: unknown): value is McpToolStructuredContent {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asContentArm(value: unknown): McpToolCallContent | undefined {
+  if (!isJsonObjectLike(value)) return undefined;
+  const type = value["type"];
+  if (type === "text" && typeof value["text"] === "string") {
+    return { type: "text", text: value["text"] };
+  }
+  if (
+    type === "image" &&
+    typeof value["data"] === "string" &&
+    typeof value["mimeType"] === "string"
+  ) {
+    return { type: "image", data: value["data"], mimeType: value["mimeType"] };
+  }
+  if (type === "resource" && isJsonObjectLike(value["resource"])) {
+    const res = value["resource"];
+    if (typeof res["uri"] !== "string") return undefined;
+    const mimeType =
+      typeof res["mimeType"] === "string" ? { mimeType: res["mimeType"] } : {};
+    if (typeof res["text"] === "string") {
+      return { type: "resource", resource: { uri: res["uri"], ...mimeType, text: res["text"] } };
+    }
+    if (typeof res["blob"] === "string") {
+      return { type: "resource", resource: { uri: res["uri"], ...mimeType, blob: res["blob"] } };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Narrow an untrusted `tools/call` answer to the arms the sandbox may see.
+ * Unknown content arms are DROPPED (never forwarded opaque); a value that
+ * is not result-shaped at all is `undefined` (the relay answers in-band).
+ */
+export function asToolCallResult(value: unknown): McpToolCallResult | undefined {
+  if (!isJsonObjectLike(value)) return undefined;
+  const rawContent = value["content"];
+  if (!Array.isArray(rawContent)) return undefined;
+  const content: McpToolCallContent[] = [];
+  for (const entry of rawContent) {
+    const arm = asContentArm(entry);
+    if (arm) content.push(arm);
+  }
+  return {
+    content,
+    ...(value["isError"] === true ? { isError: true } : {}),
+    ...(isJsonObjectLike(value["structuredContent"])
+      ? { structuredContent: value["structuredContent"] }
+      : {}),
+  };
+}
+
+/** The host-supplied transport {@link createMcpUiActionRelay} assembles over. */
+export interface CreateMcpUiActionRelayDeps {
+  /**
+   * One `tools/call` bound to the mounted card's locator `uri` over the
+   * host's authenticated channel. Returns the raw result (narrowed here),
+   * or `undefined` when the upstream denied/lost the session. Throwing is
+   * treated as unavailable.
+   */
+  callTool: (
+    uri: string,
+    name: string,
+    args: McpToolStructuredContent | undefined,
+  ) => Promise<unknown>;
+}
+
+/** The request shape a mounted card's `onCallTool` bridge produces. */
+export interface UiActionRequest {
+  /** The mounted card's persisted `ui://` locator — the action's scope. */
+  resourceUri: string;
+  name: string;
+  arguments?: McpToolStructuredContent;
+}
+
+/**
+ * Assemble the sandbox-facing action relay from a host transport. The
+ * returned function is shaped for an `onCallTool` bridge: it always
+ * resolves (never rejects), answering in-band.
+ */
+export function createMcpUiActionRelay(
+  deps: CreateMcpUiActionRelayDeps,
+): (request: UiActionRequest) => Promise<McpToolCallResult> {
+  return async (request) => {
+    if (!UI_ACTION_TOOLS.has(request.name)) return unavailableToolCallResult();
+    if (!request.resourceUri.startsWith("ui://")) return unavailableToolCallResult();
+    let raw: unknown;
+    try {
+      raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+    } catch {
+      return unavailableToolCallResult(); // transport failure == unavailable, in-band
+    }
+    if (raw === undefined) return unavailableToolCallResult();
+    return asToolCallResult(raw) ?? unavailableToolCallResult();
+  };
+}

package/src/card-mount.ts

@@ -143,6 +143,33 @@ export function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefine
   return undefined;
 }
 
+/**
+ * The resolved-only convenience over the mount union (guuey#186 G6): every
+ * consumer that renders was writing the same two-call walk — narrow the
+ * union, then feed the `"locator"` arm to a reader. This collapses it:
+ *
+ *  - already-resolved mounts pass through untouched (no reader round-trip);
+ *  - a `"locator"` arm resolves via the reader — or the honest `undefined`
+ *    (placeholder) when no reader is wired: never a stale mount;
+ *  - a reader that answers with ANOTHER locator is treated as a miss. The
+ *    {@link UiResourceReader} contract says a read yields mount material or
+ *    nothing (guuey#127); a locator answer would loop, so the honest
+ *    reading is "could not resolve", not recursion.
+ *
+ * Takes `ViewMount | undefined` so it chains directly off
+ * `toolResultViewMount`/`snapshotViewMount` without a narrowing dance at
+ * the call site.
+ */
+export async function resolveViewMount(
+  mount: ViewMount | undefined,
+  reader?: UiResourceReader,
+): Promise<ResolvedViewMount | undefined> {
+  if (mount === undefined || mount.channel !== "locator") return mount;
+  if (reader === undefined) return undefined;
+  const read = await reader(mount.resourceUri);
+  return read === undefined || read.channel === "locator" ? undefined : read;
+}
+
 /**
  * The blocks to scan inside a card snapshot: the stored `AgArtifact`'s `parts`
  * when present, then the snapshot root itself — exactly `snapshotUiResource`'s own

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   type GguiShellHtmlOptions,
 } from "./ggui-render.js";
 export {
+  resolveViewMount,
   snapshotViewMount,
   toolResultViewMount,
   type LocatorViewMount,
@@ -42,3 +43,46 @@ export {
   type CreateMcpUiResourceReaderDeps,
   type McpResourceReadResult,
 } from "./reader.js";
+export {
+  asToolCallResult,
+  createMcpUiActionRelay,
+  unavailableToolCallResult,
+  UI_ACTION_TOOLS,
+  UI_ACTION_UNAVAILABLE_TEXT,
+  type CreateMcpUiActionRelayDeps,
+  type McpToolCallContent,
+  type McpToolCallResult,
+  type McpToolStructuredContent,
+  type UiActionRequest,
+} from "./action.js";
+export {
+  initializeResult,
+  initialViewHostState,
+  teardownMessage,
+  toolCallResponse,
+  TOOLS_CALL_METHOD,
+  viewHostElapsed,
+  viewHostReceive,
+  type ViewHostBehavior,
+  type ViewHostEffect,
+  type ViewHostOutbound,
+  type ViewHostPhase,
+  type ViewHostInfo,
+  type ViewHostState,
+  type ViewHostTransition,
+  type ViewRequestId,
+} from "./view-host-protocol.js";
+export {
+  attachViewHost,
+  viewDocumentHtml,
+  type AttachViewHostConfig,
+  type ViewFrameLike,
+  type ViewHostEvents,
+} from "./view-host.js";
+export {
+  attachSandboxPageDelivery,
+  isSandboxProxyReady,
+  SANDBOX_PROXY_READY_METHOD,
+  SANDBOX_RESOURCE_READY_METHOD,
+  type SandboxPageDeliveryConfig,
+} from "./sandbox-page.js";