@guuey/agent-client 0.2.2 → 0.3.0

package/dist/block-ui.d.ts

@@ -1,117 +0,0 @@
-/**
- * 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, AgMessage, JsonValue } from "@silverprotocol/core";
-import type { HistoryCard } from "./types";
-/** A narrowed MCP embedded UI resource (the `_meta.ui.resource` shape). */
-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.
- */
-export declare function cardUiResource(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;
-/**
- * The tool name for a `tool-result` block, read off its paired `tool-call`
- * block in the same message (the reducer keeps both in one message's content).
- * Falls back to `"tool"` when the pair is missing.
- */
-export declare function toolNameFor(message: AgMessage, toolCallId: string): string;
-/**
- * Persisted cards, ascending by transcript `seq` (stable; input untouched).
- * These are PRIOR-turn cards — they always precede the live fold, so a
- * block-preserving renderer surfaces them first (e.g. under an "Earlier in
- * this conversation" divider).
- */
-export declare function sortHistoryCards(cards: readonly HistoryCard[]): HistoryCard[];
-//# sourceMappingURL=block-ui.d.ts.map

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

@@ -1 +0,0 @@
-{"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,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,2EAA2E;AAC3E,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,wBAAgB,cAAc,CAAC,YAAY,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAUxF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAE7E"}

package/dist/block-ui.js

@@ -1,183 +0,0 @@
-/** 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.
- */
-export function cardUiResource(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;
-}
-/**
- * The tool name for a `tool-result` block, read off its paired `tool-call`
- * block in the same message (the reducer keeps both in one message's content).
- * Falls back to `"tool"` when the pair is missing.
- */
-export function toolNameFor(message, toolCallId) {
-    for (const b of message.content) {
-        if (b.type === "tool-call" && b.toolCallId === toolCallId)
-            return b.name;
-    }
-    return "tool";
-}
-/**
- * Persisted cards, ascending by transcript `seq` (stable; input untouched).
- * These are PRIOR-turn cards — they always precede the live fold, so a
- * block-preserving renderer surfaces them first (e.g. under an "Earlier in
- * this conversation" divider).
- */
-export function sortHistoryCards(cards) {
-    return [...cards].sort((a, b) => a.seq - b.seq);
-}

package/dist/card-mount.d.ts

@@ -1,69 +0,0 @@
-/**
- * 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";
-import type { AgBlock, JsonValue } from "@silverprotocol/core";
-/** Which generative-UI channel produced a mount. See this module's header. */
-export type CardMountChannel = "inline" | "ggui";
-/** A mountable card: the resource to hand the host, and where it came from. */
-export interface CardMount {
-    /** The payload an mcp-ui host mounts, identical in shape for both channels. */
-    resource: McpUiResourcePayload;
-    /**
-     * `"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.
-     */
-    channel: CardMountChannel;
-}
-/**
- * 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 toolResultCardMount(block: Extract<AgBlock, {
-    type: "tool-result";
-}>): CardMount | undefined;
-/**
- * A persisted `HistoryCard`'s `cardSnapshot` → the card to mount, across both
- * channels.
- *
- * The ggui arm is reached only for a snapshot that stored the render's
- * `_meta`; a bootstrap old enough to have been persisted has an expired
- * `wsToken` anyway, so in practice a ggui history card resolves to `undefined`
- * and the host renders its placeholder — honest, and NOT a broken mount.
- */
-export declare function cardCardMount(cardSnapshot: JsonValue): CardMount | undefined;
-//# sourceMappingURL=card-mount.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"card-mount.d.ts","sourceRoot":"","sources":["../src/card-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAwC,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,SAAS,GAAG,SAAS,CAMvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAS5E"}

package/dist/card-mount.js

@@ -1,83 +0,0 @@
-/**
- * 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 { cardUiResource, toolResultUiResource } from "./block-ui";
-import { blockGguiRender, gguiRenderResource, toolResultGguiRender } from "./ggui-render";
-/**
- * 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 toolResultCardMount(block) {
-    const inline = toolResultUiResource(block);
-    if (inline)
-        return { resource: inline, channel: "inline" };
-    const ggui = toolResultGguiRender(block);
-    const resource = ggui ? gguiRenderResource(ggui) : undefined;
-    return resource ? { resource, channel: "ggui" } : undefined;
-}
-/**
- * A persisted `HistoryCard`'s `cardSnapshot` → the card to mount, across both
- * channels.
- *
- * The ggui arm is reached only for a snapshot that stored the render's
- * `_meta`; a bootstrap old enough to have been persisted has an expired
- * `wsToken` anyway, so in practice a ggui history card resolves to `undefined`
- * and the host renders its placeholder — honest, and NOT a broken mount.
- */
-export function cardCardMount(cardSnapshot) {
-    const inline = cardUiResource(cardSnapshot);
-    if (inline)
-        return { resource: inline, channel: "inline" };
-    for (const block of snapshotBlocks(cardSnapshot)) {
-        const ggui = blockGguiRender(block);
-        const resource = ggui ? gguiRenderResource(ggui) : undefined;
-        if (resource)
-            return { resource, channel: "ggui" };
-    }
-    return undefined;
-}
-/**
- * The blocks to scan inside a card snapshot: the stored `AgArtifact`'s `parts`
- * when present, then the snapshot root itself — exactly `cardUiResource`'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

@@ -1,161 +0,0 @@
-/**
- * The **ggui render** channel: narrowing + self-contained shell construction
- * for a generative-UI card produced by the ggui MCP server (`ggui_render`).
- *
- * ## Why this is a second channel and not the existing one
- *
- * `block-ui.ts`'s original narrowing accepts exactly one shape — an mcp-ui
- * embedded resource that carries its HTML INLINE (`{uri, text|blob}`). A ggui
- * render carries no HTML at all. Its `tool.done` looks like this on the wire
- * (shaped identically to the production capture the widget's fixtures
- * replay, but with the SAME synthetic ids those redacted fixtures use —
- * `apps/widget/src/fixtures/issue2627-render-capture.sse.txt` seq 48):
- *
- * ```jsonc
- * {"type":"tool.done", "toolCallId":"toolu_0000…0005",
- *  "uiData":{"sessionId":"render_0000…0001",
- *            "resourceUri":"ui://ggui/render/render_0000…0001/c10a2055…", … },
- *  "_meta":{"ai.ggui/render":{"sessionId":"render_0000…0001","appId":"APP00000",
- *              "runtimeUrl":"https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js",
- *              "wsUrl":"wss://…/ws","wsToken":"eyJ…","expiresAt":"…",
- *              "propsJson":"{…}"},
- *           "ui":{"resourceUri":"ui://ggui/render/…"}}}
- * ```
- *
- * Two facts follow, and they shape everything below:
- *
- *  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.
- *
- * ## How the card mounts (the ggui-documented self-contained shell)
- *
- * ggui's iframe runtime accepts its bootstrap from three delivery channels;
- * the highest-priority one is the **self-contained shell**: HTML that inlines
- * the slice envelope at `globalThis.__GGUI_META__` synchronously BEFORE the
- * runtime bundle's `<script type="module">` evaluates, after which the runtime
- * autostarts, creates its own mount container and renders — no postMessage
- * round-trip, no host-side ggui code. That contract is stated verbatim by the
- * runtime's own reader (`@ggui-ai/iframe-runtime`'s `parseMetaFromGlobal`:
- * *"The global carries the SAME slice envelope shape as the wire `_meta`
- * (`{ "ai.ggui/render": {...} }`) … per-render shells populate this
- * synchronously BEFORE the runtime bundle's `<script type="module">`
- * evaluates"*), and by its boot resolver (`runtime.js`'s autostart:
- * `readSelfContainedMeta()` first, postMessage channels after).
- *
- * {@link gguiShellHtml} builds exactly that shell. Because the shell IS a
- * string of HTML, the ggui card then 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.
- *
- * The slice is inlined **verbatim**: `runtimeUrl` is honored as given (ggui's
- * host checklist item 8 — "no fallback URL, no substitution"), and every other
- * field is passed through untouched for the runtime's own projector to
- * validate. This module reads exactly one field (`runtimeUrl`) and only to
- * prove the slice is mountable at all.
- *
- * NOT in scope here: rehydrating a ggui card from persisted history. The
- * bootstrap's `wsToken` expires minutes after the render (`expiresAt` in the
- * capture above), so a stored bootstrap is dead on arrival — a history card
- * without a live bootstrap correctly resolves to `undefined` and renders the
- * host's placeholder rather than a broken mount.
- */
-import type { AgBlock, JsonValue } from "@silverprotocol/core";
-import { type McpUiResourcePayload } from "./block-ui";
-/** The `_meta` key the ggui render bootstrap rides on (MCP-Apps slice convention). */
-export declare const GGUI_RENDER_META_KEY = "ai.ggui/render";
-/**
- * A ggui render bootstrap: the runtime bundle URL this module reads, plus the
- * WHOLE `ai.ggui/render` slice, verbatim, for the shell to inline.
- */
-export interface GguiRenderBootstrap {
-    /** `runtimeUrl` — the ESM bundle the shell loads. Honored as given. */
-    runtimeUrl: string;
-    /**
-     * The verbatim slice. Open-ended by construction: it is ggui's wire
-     * contract, not one this package owns, and the runtime's own projector is
-     * the authority on every field. Re-declaring it here would duplicate a
-     * contract we do not own and rot at ggui's next field addition.
-     */
-    slice: {
-        [key: string]: JsonValue;
-    };
-}
-/** 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 `_meta` container → the ggui render bootstrap, or `undefined`.
- *
- * Two hard requirements, both the runtime's own `validateMeta` enforces
- * (`MALFORMED_BOOTSTRAP`): a non-empty `runtimeUrl`, AND at least one mode
- * discriminator (see {@link hasModeDiscriminator}). A slice with `runtimeUrl`
- * alone has a bundle to load but nothing for it to mount — the runtime would
- * boot into a blank shell rather than a card, so this guard treats that shape
- * as unmountable too and returns `undefined`.
- */
-export declare function asGguiRenderBootstrap(meta: JsonValue | undefined): GguiRenderBootstrap | undefined;
-/**
- * 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. */
-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;
-/**
- * The ggui **self-contained shell** for a render bootstrap — see this module's
- * header for the contract it implements.
- *
- * Ordering is guaranteed twice over: the classic `<script>` runs during parse,
- * and the runtime's `<script type="module">` is deferred by definition, so the
- * global is always populated before the bundle evaluates.
- */
-export declare function gguiShellHtml(bootstrap: GguiRenderBootstrap): string;
-/**
- * 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.
- *
- * **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 — it has `sessionId`, `resourceUri`, `action`,
- * `contractHash`, `blueprintId`, `variantKey`, `cache`, `nextStep`, and that is
- * all. 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

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

@@ -1 +0,0 @@
-{"version":3,"file":"ggui-render.d.ts","sourceRoot":"","sources":["../src/ggui-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAErE,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAKrD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CACrC;AAED,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;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAQlG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,oBAAoB,GAAG,SAAS,CAUlC;AAED,+EAA+E;AAC/E,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;AA0BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAkBpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,GAAG,SAAS,CAOlC"}