@guuey/mcp-apps-host 0.3.0

package/dist/ggui-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ggui-render.d.ts","sourceRoot":"","sources":["../src/ggui-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,kBAAkC,CAAC;AAKpE,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,oBAAoB,GAAG,SAAS,CAUlC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,oBAAoB,GAAG,SAAS,CAElC;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAIlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,GAAG,SAAS,CAOlC"}

package/dist/ggui-render.js

@@ -0,0 +1,85 @@
+import { asGguiRenderBootstrap, gguiShellHtml, MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { isJsonObject } from "./block-ui.js";
+export { asGguiRenderBootstrap, gguiShellHtml, } from "@ggui-ai/protocol/integrations/mcp-apps";
+/**
+ * The `_meta` key the ggui render bootstrap rides on. Alias of the
+ * protocol package's own constant — one spelling, owned upstream.
+ */
+export const GGUI_RENDER_META_KEY = MCP_APP_AI_GGUI_RENDER_META_KEY;
+/** The `ui://` scheme prefix every ggui render resource uri carries. */
+const UI_SCHEME = "ui://";
+/**
+ * A tool result's `uiData` (+ its `_meta`, when carried) → a ggui render
+ * descriptor, or `undefined` for anything that is not one.
+ *
+ * The `ui://` scheme gate is deliberate: `uiData` is a general-purpose channel
+ * (every `structuredContent` of a `_meta.ui`-stamped tool lands there), so a
+ * bare `resourceUri` string is not on its own a claim of generative UI.
+ */
+export function asGguiRender(uiData, meta) {
+    if (!isJsonObject(uiData))
+        return undefined;
+    const resourceUri = uiData.resourceUri;
+    if (typeof resourceUri !== "string" || !resourceUri.startsWith(UI_SCHEME))
+        return undefined;
+    const bootstrap = asGguiRenderBootstrap(meta);
+    return {
+        resourceUri,
+        ...(typeof uiData.sessionId === "string" ? { sessionId: uiData.sessionId } : {}),
+        ...(bootstrap ? { bootstrap } : {}),
+    };
+}
+/**
+ * A live `tool-result` AgBlock → its ggui render descriptor, if it is one.
+ *
+ * NOTE: `@ggui-ai/protocol/integrations/mcp-apps` exports a helper of the
+ * same name that narrows a spec-canonical MCP `CallToolResult` instead. This
+ * one is the silverprotocol-side twin — the input is the FOLDED block, whose
+ * `uiData`/`_meta` carriage is `@silverprotocol/core`'s contract, not ggui's.
+ */
+export function toolResultGguiRender(block) {
+    return asGguiRender(block.uiData, block._meta);
+}
+/** An untyped (persisted-snapshot) block → its ggui render descriptor, if it is one. */
+export function blockGguiRender(block) {
+    if (!isJsonObject(block))
+        return undefined;
+    if (block.type !== "tool-result")
+        return undefined;
+    return asGguiRender(block.uiData, block._meta);
+}
+/**
+ * A ggui render descriptor → the mountable resource the host's existing
+ * mcp-ui path already knows how to mount, or `undefined` when the descriptor
+ * carries no bootstrap (history cards, and any fold that dropped `_meta`).
+ *
+ * The `uri` is the render's REAL `resourceUri` — the shell is the payload, not
+ * a renaming of the resource.
+ *
+ * The shell is built `background: 'transparent'`: every guuey host that
+ * mounts through this adapter (widget, portal web, Studio) draws its own
+ * card chrome around the iframe, so the host page composits behind the card.
+ * The upstream default (`'surface'`) is for standalone served documents —
+ * see `GguiShellHtmlOptions` in `@ggui-ai/protocol/integrations/mcp-apps`.
+ *
+ * **On `_meta` being required to MOUNT (but never to RECOGNISE).** Recognition
+ * — "this tool result is a ggui card" — is keyed on `uiData.resourceUri` alone
+ * and never waits for anything (see {@link asGguiRender}); nothing in this
+ * package is blocked on an upstream change. Mounting is different, and the
+ * requirement is ggui's, not ours: its runtime rejects a slice without
+ * `runtimeUrl` AND without at least one mode discriminator (`wsUrl`+`wsToken`,
+ * `codeUrl`, or `kind`) as `MALFORMED_BOOTSTRAP` and renders nothing. `uiData`
+ * carries none of those fields, so a bootstrap-less descriptor could only ever
+ * produce a blank frame; returning `undefined` and letting the host show its
+ * own placeholder is the honest answer, not a deferral. `@silverprotocol/core`'s
+ * `Reducer` is what puts `_meta` on the block for a live turn, in-repo, today.
+ */
+export function gguiRenderResource(render) {
+    if (!render.bootstrap)
+        return undefined;
+    return {
+        uri: render.resourceUri,
+        mimeType: "text/html",
+        text: gguiShellHtml(render.bootstrap, { background: "transparent" }),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @guuey/mcp-apps-host — the MCP Apps (SEP-1865) Host role: view-mount
+ * narrowing, ui:// locator rehydration, sandbox-trust channels. See README +
+ * the conformance map (guuey#123).
+ */
+export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, type McpUiResourcePayload, } from "./block-ui.js";
+export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, type GguiRenderBootstrap, type GguiRenderDescriptor, type GguiShellHtmlOptions, } from "./ggui-render.js";
+export { snapshotViewMount, toolResultViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @guuey/mcp-apps-host — the MCP Apps (SEP-1865) Host role: view-mount
+ * narrowing, ui:// locator rehydration, sandbox-trust channels. See README +
+ * the conformance map (guuey#123).
+ */
+export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, } from "./block-ui.js";
+export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, } from "./ggui-render.js";
+export { snapshotViewMount, toolResultViewMount, } from "./card-mount.js";

package/dist/narrowing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Protocol-free subpath (`@guuey/mcp-apps-host/narrowing`): ONLY the
+ * recognition/narrowing helpers, so lean consumers (e.g. `@guuey/threads`'
+ * persistence projection) never pull `@ggui-ai/protocol` into their runtime
+ * graph through the barrel (which re-exports the ggui render arm until its
+ * retirement — conformance-map step 4).
+ */
+export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, type McpUiResourcePayload, } from "./block-ui.js";
+//# sourceMappingURL=narrowing.d.ts.map

package/dist/narrowing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrowing.d.ts","sourceRoot":"","sources":["../src/narrowing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/narrowing.js

@@ -0,0 +1,8 @@
+/**
+ * Protocol-free subpath (`@guuey/mcp-apps-host/narrowing`): ONLY the
+ * recognition/narrowing helpers, so lean consumers (e.g. `@guuey/threads`'
+ * persistence projection) never pull `@ggui-ai/protocol` into their runtime
+ * graph through the barrel (which re-exports the ggui render arm until its
+ * retirement — conformance-map step 4).
+ */
+export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, } from "./block-ui.js";

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@guuey/mcp-apps-host",
+  "version": "0.3.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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./narrowing": {
+      "react-native": "./src/narrowing.ts",
+      "types": "./dist/narrowing.d.ts",
+      "import": "./dist/narrowing.js",
+      "default": "./dist/narrowing.js"
+    }
+  },
+  "dependencies": {
+    "@ggui-ai/protocol": "0.6.3",
+    "@silverprotocol/core": "0.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "mcp",
+    "mcp-apps",
+    "sep-1865",
+    "host",
+    "generative-ui",
+    "view"
+  ],
+  "repository": {
+    "type": "git",
+    "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"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/block-ui.ts

@@ -0,0 +1,205 @@
+/**
+ * Pure block-walk / resource-narrowing helpers for a block-preserving agent
+ * transcript — no React, no DOM, so the narrowing logic stays unit-testable in
+ * isolation (this package's vitest runs a `node` environment) and can be shared
+ * by every host renderer (Studio's `AgentBlocks`, Portal-web's agent chat).
+ *
+ * The pod's AgJSON wire carries generative-UI payloads on `tool.done` events,
+ * which the reducer folds onto `tool-result` blocks. Two channels reach us:
+ *
+ *  1. **`uiData`** — the MCP-Apps *surface* channel. The pod's Claude facet
+ *     routes a tool result's `structuredContent` here when the server stamped
+ *     `_meta.ui`. Any resource here is intended as UI.
+ *  2. **`provider-raw` content blocks** — an MCP embedded `resource` content
+ *     part does NOT survive as a first-class `resource` AgBlock in the Claude
+ *     facet; it degrades to `{ type:'provider-raw', vendor, raw:<part> }`. So a
+ *     `ui://` resource can be hiding inside `provider-raw.raw` and must be
+ *     scanned for defensively.
+ *
+ * The resource-narrowing (opaque `JsonValue` → typed payload) mirrors the
+ * proven `create-agentic-app` web template — structural validation, never a cast.
+ */
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+
+/**
+ * A narrowed MCP UI resource payload — the `resources/read` `contents[]`
+ * entry shape of SEP-1865 (uri + mimeType + text|blob), which is also the
+ * pre-SEP mcp-ui embedded `resource` content-part shape. (No `_meta.ui.resource`
+ * path exists in the spec; recognition rides `uiData`/content parts.)
+ */
+export interface McpUiResourcePayload {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+}
+
+/** Narrow an opaque `JsonValue` to a plain (non-array) JSON object. */
+export function isJsonObject(v: JsonValue | undefined): v is { [key: string]: JsonValue } {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A JSON object → an MCP UI resource, if it has a `uri` plus renderable
+ * payload (`text` or base64 `blob`). Returns `undefined` for anything else.
+ */
+export function asResourcePayload(v: JsonValue | undefined): McpUiResourcePayload | undefined {
+  if (!isJsonObject(v)) return undefined;
+  if (typeof v.uri !== "string") return undefined;
+  if (typeof v.text !== "string" && typeof v.blob !== "string") return undefined;
+  return {
+    uri: v.uri,
+    ...(typeof v.mimeType === "string" ? { mimeType: v.mimeType } : {}),
+    ...(typeof v.text === "string" ? { text: v.text } : {}),
+    ...(typeof v.blob === "string" ? { blob: v.blob } : {}),
+  };
+}
+
+/**
+ * Does a `tool-result` block's `uiData` carry an MCP embedded UI resource?
+ * Accepts the resource inlined directly, or wrapped as `{ resource: {...} }`
+ * (the shape an MCP `resource` content part carries). No `ui://` scheme gate
+ * here on purpose: `uiData` is the explicit *surface* channel (the server
+ * stamped `_meta.ui`), so any resource on it is meant to render.
+ */
+export function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined {
+  if (!isJsonObject(uiData)) return undefined;
+  const direct = asResourcePayload(uiData);
+  if (direct) return direct;
+  return asResourcePayload(uiData.resource);
+}
+
+/**
+ * Scan a `provider-raw` block's `raw` (the vendor tool_result content part)
+ * for a *generative-UI* resource. Unlike {@link asUiResource}, this path IS
+ * gated on the `ui://` scheme: `provider-raw` degradation is a lossy catch-all,
+ * so a plain file/text resource riding it is NOT a UI to mount — only the
+ * mcp-ui `ui://` convention is.
+ */
+export function scanProviderRawForUiResource(
+  raw: JsonValue | undefined,
+): McpUiResourcePayload | undefined {
+  if (!isJsonObject(raw)) return undefined;
+  const candidate =
+    raw.resource !== undefined ? asResourcePayload(raw.resource) : asResourcePayload(raw);
+  if (!candidate) return undefined;
+  return candidate.uri.startsWith("ui://") ? candidate : undefined;
+}
+
+/**
+ * Extract a mountable UI resource from an opaque AgBlock-shaped `JsonValue`
+ * (used for persisted card snapshot parts, which arrive untyped). Dispatches
+ * by `block.type`:
+ *   - `tool-result` → its `uiData` surface channel, then a `ui://` resource
+ *     degraded into a `provider-raw` content part — the SAME two channels
+ *     the live path ({@link toolResultUiResource}) mounts. The write side
+ *     (`nocode-runtime`'s `uiCardArtifactsFromMessages`, guuey#86) persists
+ *     card rows for both, so the snapshot arm must mount both or
+ *     provider-raw-only cards rehydrate as placeholders.
+ *   - `provider-raw` → a `ui://` resource hiding in `raw`
+ *   - `resource`     → a first-class embedded resource (gated on `ui://`)
+ * Everything else → `undefined`.
+ */
+export function blockUiResource(block: JsonValue): McpUiResourcePayload | undefined {
+  if (!isJsonObject(block)) return undefined;
+  switch (block.type) {
+    case "tool-result": {
+      const fromUiData = asUiResource(block.uiData);
+      if (fromUiData) return fromUiData;
+      if (Array.isArray(block.content)) {
+        for (const part of block.content) {
+          if (isJsonObject(part) && part.type === "provider-raw") {
+            const found = scanProviderRawForUiResource(part.raw);
+            if (found) return found;
+          }
+        }
+      }
+      return undefined;
+    }
+    case "provider-raw":
+      return scanProviderRawForUiResource(block.raw);
+    case "resource": {
+      const r = asResourcePayload(block.resource);
+      return r && r.uri.startsWith("ui://") ? r : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * A live `tool-result` AgBlock → its mountable UI resource, checking BOTH
+ * channels the Claude facet uses:
+ *   1. the `uiData` surface channel (server stamped `_meta.ui`), and
+ *   2. an embedded `ui://` resource that degraded into a `provider-raw`
+ *      content part inside the tool result (MCP `resource` parts do NOT survive
+ *      as first-class `resource` AgBlocks here).
+ * First-class `resource` content parts are intentionally not scanned in this
+ * typed live path (the Claude facet never emits them); the untyped card path
+ * ({@link blockUiResource}) covers them for other facets' persisted snapshots.
+ */
+export function toolResultUiResource(
+  block: Extract<AgBlock, { type: "tool-result" }>,
+): McpUiResourcePayload | undefined {
+  const fromUiData = asUiResource(block.uiData);
+  if (fromUiData) return fromUiData;
+  for (const part of block.content) {
+    if (part.type === "provider-raw") {
+      const found = scanProviderRawForUiResource(part.raw);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A persisted `HistoryCard`'s `cardSnapshot` → a mountable UI resource. The
+ * snapshot is the verbatim `AgArtifact` the pod stored (`{ parts: AgBlock[] }`),
+ * so walk its `parts` for the first block that yields a resource; fall back to
+ * treating the snapshot root itself as a block.
+ *
+ * NOTE (`no-ggui-tools`): a ggui-rendered card carries NO inline HTML resource —
+ * its UI rides `_meta.ggui.bootstrap` and mounts via `@ggui-ai/react`'s
+ * `McpAppIframe`. That branch is OUT OF SCOPE for v1 (deferred-pending-capture).
+ * So a real ggui card resolves to `undefined` here and renders as the host's
+ * coherent placeholder, not a broken mount.
+ */
+/**
+ * A `tool-result` block's `uiData.resourceUri` when it is a `ui://` locator
+ * (MCP-Apps durable identity), else `undefined`. Vendor-neutral: ggui renders
+ * are one producer of this shape.
+ */
+export function uiLocator(uiData: JsonValue | undefined): string | undefined {
+  if (!isJsonObject(uiData)) return undefined;
+  const uri = uiData.resourceUri;
+  return typeof uri === "string" && uri.startsWith("ui://") ? uri : undefined;
+}
+
+export function snapshotUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined {
+  if (!isJsonObject(cardSnapshot)) return undefined;
+  const parts = cardSnapshot.parts;
+  if (Array.isArray(parts)) {
+    for (const part of parts) {
+      const found = blockUiResource(part);
+      if (found) return found;
+    }
+  }
+  return blockUiResource(cardSnapshot);
+}
+
+/**
+ * The resource's HTML: inline `text` wins; else base64-decode `blob`. `atob`
+ * alone yields a Latin-1 string (mojibake on multibyte UTF-8), so decode via
+ * bytes + `TextDecoder`. Invalid base64 → `undefined` (no renderable payload).
+ */
+export function resourceHtml(resource: McpUiResourcePayload): string | undefined {
+  if (resource.text !== undefined) return resource.text;
+  if (resource.blob !== undefined) {
+    try {
+      return new TextDecoder().decode(Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0)));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}

package/src/card-mount.ts

@@ -0,0 +1,149 @@
+/**
+ * The card-mount dispatcher: ONE narrowing that answers "what, if anything,
+ * does this block mount?" across BOTH generative-UI channels a guuey pod
+ * emits.
+ *
+ *   1. **inline mcp-ui resource** — `{uri, text|blob}` on `uiData`, or a
+ *      `ui://` resource degraded into a `provider-raw` content part. Handled
+ *      verbatim by `block-ui.ts`; this module does not touch that path, it
+ *      only tries it FIRST.
+ *   2. **ggui render** — `uiData.resourceUri` + the `_meta["ai.ggui/render"]`
+ *      bootstrap, mounted through ggui's self-contained shell. See
+ *      `ggui-render.ts`.
+ *
+ * Both channels land on the SAME `McpUiResourcePayload`, which is the whole
+ * point: a host that already mounts inline resources through
+ * `@mcp-ui/client`'s `AppRenderer` in a second-origin sandbox gains ggui cards
+ * without a second mount mechanism, a second iframe contract, or a second
+ * security posture to review.
+ *
+ * Precedence is inline-first and deliberate: an inline resource is the
+ * server's explicit, self-sufficient HTML. A ggui render only ever wins when
+ * there is no inline resource to prefer, so this dispatcher can never change
+ * what an existing inline card renders.
+ *
+ * ## Why the CHANNEL is returned alongside the resource
+ *
+ * The payload alone cannot say where it came from — a ggui shell is a string
+ * of HTML like any other. But a host has one decision that genuinely depends
+ * on the origin of that HTML: WHICH sandbox host page to mount it in. A ggui
+ * shell must load ggui's runtime bundle and open its WSS, so it needs a page
+ * whose CSP names the ggui origins; an inline card is arbitrary tenant HTML
+ * and must keep the self-only page it has always had. Handing back the channel
+ * keeps that one narrowing in one place — the alternative was for every host
+ * to re-run `toolResultGguiRender` beside this call and ask again.
+ */
+import { snapshotUiResource, toolResultUiResource, uiLocator, type McpUiResourcePayload } from "./block-ui.js";
+import { GGUI_RENDER_META_KEY, gguiRenderResource, toolResultGguiRender } from "./ggui-render.js";
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+
+
+/** Does the block's `_meta` carry the ggui render key at all (valid or not)? */
+function blockCarriesGguiMetaKey(block: Extract<AgBlock, { type: "tool-result" }>): boolean {
+  const meta = block._meta;
+  return (
+    typeof meta === "object" && meta !== null && !Array.isArray(meta) && GGUI_RENDER_META_KEY in meta
+  );
+}
+
+/** Which generative-UI channel produced a mount. See this module's header. */
+export type ViewMountChannel = "inline" | "ggui" | "locator";
+
+/**
+ * A mountable card, or the locator to fetch one with.
+ *
+ * `"inline"` — the server's own HTML, untrusted tenant content.
+ * `"ggui"` — a shell that boots the ggui runtime from a platform-pinned
+ * origin, and therefore needs a host page whose CSP allows that origin.
+ * `"locator"` — no mount material in hand, only the durable `ui://`
+ * identity (guuey#122): the host resolves it with a fresh, authenticated
+ * `resources/read` of the uri ({@link UiResourceReader}) — the spec-consistent
+ * template fetch, vendor-neutral. (The spec defers persistence/restoration
+ * itself; a full remount additionally owes the View `ui/notifications/tool-input`
+ * + its tool result — see the conformance map.) Until a reader is wired, the honest render
+ * is the host's own placeholder, never a stale mount.
+ */
+export type ViewMount =
+  | {
+      channel: "inline" | "ggui";
+      /** The payload an mcp-ui host mounts, identical in shape for both channels. */
+      resource: McpUiResourcePayload;
+    }
+  | {
+      channel: "locator";
+      /** The persisted `uiData.resourceUri` (`ui://` scheme) to re-fetch. */
+      resourceUri: string;
+    };
+
+/**
+ * Resolves a `"locator"` mount by a fresh `resources/read` of the uri over
+ * an AUTHENTICATED channel the HOST owns — guuey must enforce its own
+ * user-ownership before fetching on a user's behalf, and a deny is
+ * byte-identical to a miss (`undefined` → placeholder, never an error
+ * surface). The reader returns a full {@link ViewMount} because only the
+ * transport knows which sandbox trust the fetched HTML needs (a ggui shell
+ * wants the ggui-CSP page; arbitrary tenant HTML wants the self-only page).
+ */
+export type UiResourceReader = (resourceUri: string) => Promise<ViewMount | undefined>;
+
+/**
+ * A live `tool-result` block → the card to mount, across both channels.
+ * `undefined` when the block carries no generative UI at all (or carries a
+ * ggui render whose bootstrap did not reach us — see `ggui-render.ts`).
+ */
+export function toolResultViewMount(
+  block: Extract<AgBlock, { type: "tool-result" }>,
+): ViewMount | undefined {
+  const inline = toolResultUiResource(block);
+  if (inline) return { resource: inline, channel: "inline" };
+  const ggui = toolResultGguiRender(block);
+  const resource = ggui ? gguiRenderResource(ggui) : undefined;
+  if (resource) return { resource, channel: "ggui" };
+  // A live locator whose mount material didn't reach us (a fold that
+  // dropped `_meta`): re-fetch works on live turns too — the resource is
+  // freshly minted (guuey#122). One diagnostic when `_meta` DID carry the
+  // vendor key but failed validation — a producer bug would otherwise be
+  // indistinguishable from a meta-less fold (blank UI, zero errors).
+  if (ggui && !ggui.bootstrap && blockCarriesGguiMetaKey(block)) {
+    console.warn(
+      `mcp-apps-host: tool result ${block.toolCallId} carries a malformed ggui render bootstrap — degrading to the locator channel`,
+    );
+  }
+  const locator = uiLocator(block.uiData);
+  return locator !== undefined ? { channel: "locator", resourceUri: locator } : undefined;
+}
+
+/**
+ * A persisted `HistoryCard`'s `cardSnapshot` → the card to mount.
+ *
+ * There is deliberately NO bootstrap arm here (guuey#122): persistence
+ * strips tool-result `_meta` (see `@guuey/threads`' fold-rows), and a
+ * foreign snapshot that still carries one holds an expired `wsToken` — a
+ * dead mount. A persisted `ui://` locator resolves to the `"locator"`
+ * channel instead: rehydration is a fresh `resources/read` of the uri,
+ * the spec-consistent template fetch, vendor-neutral.
+ */
+export function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefined {
+  const inline = snapshotUiResource(cardSnapshot);
+  if (inline) return { resource: inline, channel: "inline" };
+  for (const block of snapshotBlocks(cardSnapshot)) {
+    if (typeof block !== "object" || block === null || Array.isArray(block)) continue;
+    if (block.type !== "tool-result") continue;
+    const locator = uiLocator(block.uiData);
+    if (locator !== undefined) return { channel: "locator", resourceUri: locator };
+  }
+  return undefined;
+}
+
+/**
+ * The blocks to scan inside a card snapshot: the stored `AgArtifact`'s `parts`
+ * when present, then the snapshot root itself — exactly `snapshotUiResource`'s own
+ * walk order, so both channels see the same candidates in the same order.
+ */
+function snapshotBlocks(cardSnapshot: JsonValue): JsonValue[] {
+  if (typeof cardSnapshot !== "object" || cardSnapshot === null || Array.isArray(cardSnapshot)) {
+    return [];
+  }
+  const parts = cardSnapshot.parts;
+  return Array.isArray(parts) ? [...parts, cardSnapshot] : [cardSnapshot];
+}