@guuey/mcp-apps-host 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @guuey/mcp-apps-host
+
+The **Host** role of [MCP Apps (SEP-1865)](https://github.com/modelcontextprotocol/ext-apps)
+for guuey's chat surfaces — and for any host that mounts MCP Apps views.
+
+The spec's constant refrain is "Host MUST …". This package implements that
+role's client-side narrowing and mount contract:
+
+- **View-mount dispatch** (`toolResultViewMount`, `snapshotViewMount`): one
+  narrowing that answers "what, if anything, does this block mount?" across
+  the UI channels a transcript carries — an inline `ui://` resource payload,
+  a vendor fast-path (ggui's render shell, until its retirement per the
+  conformance map), or a bare `ui://` **locator**.
+- **Locator rehydration**: a persisted `ui://` locator remounts by a fresh,
+  authenticated `resources/read` of the uri — the spec-consistent template
+  fetch (the spec itself defers persistence/restoration; a full remount
+  additionally owes the View `ui/notifications/tool-input` + its tool
+  result) — never by replaying stored mount material. The read transport is injected
+  (`UiResourceReader`); the host owns auth and user-ownership enforcement,
+  and a deny is byte-identical to a miss.
+- **Sandbox-trust channels** (`ViewMountChannel`): which sandbox host page a
+  payload may mount in, until per-resource declared-CSP construction lands.
+
+Vendor-neutral by principle: ggui's MCP Apps run on any spec-following host
+(claude.ai, chatgpt.com, guuey) precisely because they follow the spec; this
+package is guuey's OSS host-side support for the same spec.
+
+Conformance status and roadmap: `docs/development/mcp-apps-host-conformance.md`
+in the guuey monorepo (guuey#123).

package/dist/block-ui.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 declare function isJsonObject(v: JsonValue | undefined): v is {
+    [key: string]: JsonValue;
+};
+/**
+ * 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 declare function asResourcePayload(v: JsonValue | undefined): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function scanProviderRawForUiResource(raw: JsonValue | undefined): McpUiResourcePayload | 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 declare function blockUiResource(block: JsonValue): McpUiResourcePayload | 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 declare function toolResultUiResource(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): McpUiResourcePayload | 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 declare function uiLocator(uiData: JsonValue | undefined): string | undefined;
+export declare function snapshotUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function resourceHtml(resource: McpUiResourcePayload): string | undefined;
+//# sourceMappingURL=block-ui.d.ts.map

package/dist/block-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-ui.d.ts","sourceRoot":"","sources":["../src/block-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,CAAC,IAAI;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAExF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAU5F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAK5F;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,GAAG,SAAS,GACzB,oBAAoB,GAAG,SAAS,CAMlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAyBlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,oBAAoB,GAAG,SAAS,CAUlC;AAED;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI3E;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAU5F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAU/E"}

package/dist/block-ui.js

@@ -0,0 +1,173 @@
+/** Narrow an opaque `JsonValue` to a plain (non-array) JSON object. */
+export function isJsonObject(v) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (!isJsonObject(uiData))
+        return undefined;
+    const uri = uiData.resourceUri;
+    return typeof uri === "string" && uri.startsWith("ui://") ? uri : undefined;
+}
+export function snapshotUiResource(cardSnapshot) {
+    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) {
+    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/dist/card-mount.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { type McpUiResourcePayload } from "./block-ui.js";
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+/** 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 declare function toolResultViewMount(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): ViewMount | 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 declare function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefined;
+//# sourceMappingURL=card-mount.d.ts.map

package/dist/card-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-mount.d.ts","sourceRoot":"","sources":["../src/card-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAuD,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE/G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAW/D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;CAChC,GACD;IACE,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,SAAS,GAAG,SAAS,CAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAUhF"}

package/dist/card-mount.js

@@ -0,0 +1,103 @@
+/**
+ * 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 } from "./block-ui.js";
+import { GGUI_RENDER_META_KEY, gguiRenderResource, toolResultGguiRender } from "./ggui-render.js";
+/** Does the block's `_meta` carry the ggui render key at all (valid or not)? */
+function blockCarriesGguiMetaKey(block) {
+    const meta = block._meta;
+    return (typeof meta === "object" && meta !== null && !Array.isArray(meta) && GGUI_RENDER_META_KEY in meta);
+}
+/**
+ * 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) {
+    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) {
+    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) {
+    if (typeof cardSnapshot !== "object" || cardSnapshot === null || Array.isArray(cardSnapshot)) {
+        return [];
+    }
+    const parts = cardSnapshot.parts;
+    return Array.isArray(parts) ? [...parts, cardSnapshot] : [cardSnapshot];
+}

package/dist/ggui-render.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The **ggui render** channel: narrowing + self-contained shell construction
+ * for a generative-UI card produced by the ggui MCP server (`ggui_render`).
+ *
+ * ## Where the pieces live (guuey#108 / ggui#427)
+ *
+ * The two halves of this channel have different owners, and the module is
+ * split along that line:
+ *
+ *  - **ggui's wire contract** — what makes a `_meta` slice a mountable
+ *    render bootstrap, and what the self-contained shell must contain — is
+ *    OWNED by ggui and imported from
+ *    `@ggui-ai/protocol/integrations/mcp-apps` ({@link asGguiRenderBootstrap},
+ *    {@link gguiShellHtml}, the `ai.ggui/render` key). This package used to
+ *    carry byte-compatible private copies (lifted upstream as ggui#427);
+ *    re-exporting the originals means a shell-contract change lands here by
+ *    bumping the pin, not by mirror-editing two repos.
+ *  - **host/silverprotocol shapes** — the `uiData`-keyed RECOGNITION signal,
+ *    the `AgBlock` tool-result narrowing, and the `McpUiResourcePayload`
+ *    adapter onto the host's existing mcp-ui mount path — are guuey-side
+ *    contracts and stay implemented here.
+ *
+ * ## Why recognition and mounting are separate
+ *
+ * A ggui render's `tool.done` carries two distinct signals:
+ *
+ *  1. **`uiData.resourceUri` is the RECOGNITION signal.** It is the only part
+ *     of the render's identity that survives `@silverprotocol/core`'s fold
+ *     (the reducer copies `uiData` — and, as of `@silverprotocol/core`
+ *     0.4.1 (workspace#9), `_meta` — onto the `tool-result` block).
+ *  2. **`_meta["ai.ggui/render"]` is the MOUNT MATERIAL.** Everything needed
+ *     to boot the card — which runtime bundle to load, which live-channel to
+ *     open, which props to seed — lives there and nowhere else.
+ *
+ * The shell {@link gguiShellHtml} builds is a string of HTML, so the ggui
+ * card rides the host's EXISTING mcp-ui mount path unchanged: it narrows to
+ * the same `McpUiResourcePayload` an inline resource does, so
+ * `@mcp-ui/client`'s `AppRenderer` posts it as `srcdoc` into the
+ * second-origin `mcp-app-sandbox.html` page — same double-iframe rule, same
+ * sandbox origin, same opaque inner frame. No second mount mechanism.
+ *
+ * NOT in scope here: rehydrating a ggui card from persisted history. The
+ * bootstrap's `wsToken` expires minutes after the render, so a stored
+ * bootstrap is dead on arrival — a history card resolves to the `locator`
+ * channel (`card-mount.ts`, guuey#122) and remounts by a fresh
+ * `resources/read`, never a bootstrap replay.
+ */
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+import { type GguiRenderBootstrap } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { type McpUiResourcePayload } from "./block-ui.js";
+export { asGguiRenderBootstrap, gguiShellHtml, } from "@ggui-ai/protocol/integrations/mcp-apps";
+export type { GguiRenderBootstrap, GguiShellHtmlOptions, } 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 declare const GGUI_RENDER_META_KEY: "ai.ggui/render";
+/** A ggui render recognised on a tool result: its resource uri + mount material. */
+export interface GguiRenderDescriptor {
+    /** `uiData.resourceUri` — `ui://ggui/render/<sessionId>/<contractHash>`. */
+    resourceUri: string;
+    /** `uiData.sessionId`, when present. */
+    sessionId?: string;
+    /**
+     * The `_meta["ai.ggui/render"]` slice, when it reached us. Absent for a
+     * persisted history card and for any consumer folding without `fold.ts`'s
+     * `_meta` carriage — such a descriptor is recognised but NOT mountable.
+     */
+    bootstrap?: GguiRenderBootstrap;
+}
+/**
+ * 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 declare function asGguiRender(uiData: JsonValue | undefined, meta: JsonValue | undefined): GguiRenderDescriptor | undefined;
+/**
+ * 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 declare function toolResultGguiRender(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): GguiRenderDescriptor | undefined;
+/** An untyped (persisted-snapshot) block → its ggui render descriptor, if it is one. */
+export declare function blockGguiRender(block: JsonValue): GguiRenderDescriptor | undefined;
+/**
+ * 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 declare function gguiRenderResource(render: GguiRenderDescriptor): McpUiResourcePayload | undefined;
+//# sourceMappingURL=ggui-render.d.ts.map