@guuey/mcp-apps-host 0.3.1 → 0.5.0

package/README.md

@@ -27,6 +27,24 @@ role's client-side narrowing and mount contract:
   this assembly over guuey's platform proxy.
 - **Sandbox-trust channels** (`ViewMountChannel`): which sandbox host page a
   payload may mount in, until per-resource declared-CSP construction lands.
+- **The host itself** (`attachViewHost`, and `<GuueyView>` from
+  `@guuey/mcp-apps-host/react`): a spec-following view opens with the
+  `ui/initialize` App handshake and **blocks on it** — mount material alone
+  renders a blank frame forever. `attachViewHost(iframe, config)` answers
+  that handshake for any embedder (framework-agnostic, one call); the React
+  component additionally owns iframe creation, lifecycle, and the safe
+  sandbox default (`allow-scripts` **without** `allow-same-origin` — with
+  it, agent-generated HTML would run as your origin — plus
+  `allow="clipboard-write"` so generated copy buttons work). Configurable
+  where a host genuinely varies: `hostCapabilities` (default `{}` —
+  advertise only what you implement), an optional `tools/call` relay hook
+  (privilege boundary, default off; pair with `createMcpUiActionRelay`),
+  `hostContext`, and the negotiation timeout. While a frame negotiates, the
+  state is labeled (`negotiating` / `connected` / `no-handshake`), never a
+  blank page.
+- **Resolved-only mount walk** (`resolveViewMount`): chain it off
+  `toolResultViewMount`/`snapshotViewMount` with your reader and render
+  only `ResolvedViewMount`s — the locator round-trip is folded in.
 
 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/dist/action.d.ts

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

package/dist/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAC3C;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CACnB,CAAC;CACH,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAE9C,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,iBAAiB,CAK7D;AAkCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAgB9E;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,wBAAwB,GAAG,SAAS,KACvC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAa1D"}

package/dist/action.js

@@ -0,0 +1,111 @@
+/**
+ * The Host role's ACTION side (guuey#158) — the `tools/call` sibling of
+ * `reader.ts`. A mounted card's sandbox posts a runtime action to the host
+ * (SEP-1865 / ggui's relay-host contract); the host relays it over an
+ * AUTHENTICATED transport it owns, and hands the result back in-band. Two
+ * invariants mirror the reader:
+ *
+ *  - the relay NEVER throws into the sandbox bridge: allowlist miss,
+ *    transport failure, and un-narrowable answers all collapse to an
+ *    in-band `isError` result the card can display;
+ *  - runtime re-narrowing, not trust: transports are host-supplied and the
+ *    upstream answer is wire data — every content arm is re-checked before
+ *    it crosses into the sandbox.
+ */
+/**
+ * The runtime-action tools a card sandbox may relay — the client-side twin
+ * of the server allowlist (defense in depth: the proxy enforces it again).
+ */
+export const UI_ACTION_TOOLS = new Set([
+    "ggui_runtime_submit_action",
+]);
+/** The in-band answer for anything the relay cannot (or will not) do. */
+export const UI_ACTION_UNAVAILABLE_TEXT = "This action isn't available right now.";
+/**
+ * The in-band `isError` result for an action that cannot be performed —
+ * the relay's own refusals use it, and `attachViewHost` posts it when an
+ * embedder-supplied relay hook rejects (the view is always answered).
+ */
+export function unavailableToolCallResult() {
+    return {
+        content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
+        isError: true,
+    };
+}
+function isJsonObjectLike(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asContentArm(value) {
+    if (!isJsonObjectLike(value))
+        return undefined;
+    const type = value["type"];
+    if (type === "text" && typeof value["text"] === "string") {
+        return { type: "text", text: value["text"] };
+    }
+    if (type === "image" &&
+        typeof value["data"] === "string" &&
+        typeof value["mimeType"] === "string") {
+        return { type: "image", data: value["data"], mimeType: value["mimeType"] };
+    }
+    if (type === "resource" && isJsonObjectLike(value["resource"])) {
+        const res = value["resource"];
+        if (typeof res["uri"] !== "string")
+            return undefined;
+        const mimeType = typeof res["mimeType"] === "string" ? { mimeType: res["mimeType"] } : {};
+        if (typeof res["text"] === "string") {
+            return { type: "resource", resource: { uri: res["uri"], ...mimeType, text: res["text"] } };
+        }
+        if (typeof res["blob"] === "string") {
+            return { type: "resource", resource: { uri: res["uri"], ...mimeType, blob: res["blob"] } };
+        }
+    }
+    return undefined;
+}
+/**
+ * Narrow an untrusted `tools/call` answer to the arms the sandbox may see.
+ * Unknown content arms are DROPPED (never forwarded opaque); a value that
+ * is not result-shaped at all is `undefined` (the relay answers in-band).
+ */
+export function asToolCallResult(value) {
+    if (!isJsonObjectLike(value))
+        return undefined;
+    const rawContent = value["content"];
+    if (!Array.isArray(rawContent))
+        return undefined;
+    const content = [];
+    for (const entry of rawContent) {
+        const arm = asContentArm(entry);
+        if (arm)
+            content.push(arm);
+    }
+    return {
+        content,
+        ...(value["isError"] === true ? { isError: true } : {}),
+        ...(isJsonObjectLike(value["structuredContent"])
+            ? { structuredContent: value["structuredContent"] }
+            : {}),
+    };
+}
+/**
+ * Assemble the sandbox-facing action relay from a host transport. The
+ * returned function is shaped for an `onCallTool` bridge: it always
+ * resolves (never rejects), answering in-band.
+ */
+export function createMcpUiActionRelay(deps) {
+    return async (request) => {
+        if (!UI_ACTION_TOOLS.has(request.name))
+            return unavailableToolCallResult();
+        if (!request.resourceUri.startsWith("ui://"))
+            return unavailableToolCallResult();
+        let raw;
+        try {
+            raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+        }
+        catch {
+            return unavailableToolCallResult(); // transport failure == unavailable, in-band
+        }
+        if (raw === undefined)
+            return unavailableToolCallResult();
+        return asToolCallResult(raw) ?? unavailableToolCallResult();
+    };
+}

package/dist/card-mount.d.ts

@@ -97,4 +97,22 @@ export declare function toolResultViewMount(block: Extract<AgBlock, {
  * the spec-consistent template fetch, vendor-neutral.
  */
 export declare function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefined;
+/**
+ * The resolved-only convenience over the mount union (guuey#186 G6): every
+ * consumer that renders was writing the same two-call walk — narrow the
+ * union, then feed the `"locator"` arm to a reader. This collapses it:
+ *
+ *  - already-resolved mounts pass through untouched (no reader round-trip);
+ *  - a `"locator"` arm resolves via the reader — or the honest `undefined`
+ *    (placeholder) when no reader is wired: never a stale mount;
+ *  - a reader that answers with ANOTHER locator is treated as a miss. The
+ *    {@link UiResourceReader} contract says a read yields mount material or
+ *    nothing (guuey#127); a locator answer would loop, so the honest
+ *    reading is "could not resolve", not recursion.
+ *
+ * Takes `ViewMount | undefined` so it chains directly off
+ * `toolResultViewMount`/`snapshotViewMount` without a narrowing dance at
+ * the call site.
+ */
+export declare function resolveViewMount(mount: ViewMount | undefined, reader?: UiResourceReader): Promise<ResolvedViewMount | undefined>;
 //# sourceMappingURL=card-mount.d.ts.map

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

@@ -1 +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,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;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"}
+{"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,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;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;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAKxC"}

package/dist/card-mount.js

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

package/dist/index.d.ts

@@ -5,6 +5,10 @@
  */
 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 LocatorViewMount, type ResolvedViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
+export { resolveViewMount, snapshotViewMount, toolResultViewMount, type LocatorViewMount, type ResolvedViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
 export { createMcpUiResourceReader, uiResourceChannel, type CreateMcpUiResourceReaderDeps, type McpResourceReadResult, } from "./reader.js";
+export { asToolCallResult, createMcpUiActionRelay, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, type CreateMcpUiActionRelayDeps, type McpToolCallContent, type McpToolCallResult, type McpToolStructuredContent, type UiActionRequest, } from "./action.js";
+export { initializeResult, initialViewHostState, teardownMessage, toolCallResponse, TOOLS_CALL_METHOD, viewHostElapsed, viewHostReceive, type ViewHostBehavior, type ViewHostEffect, type ViewHostOutbound, type ViewHostPhase, type ViewHostInfo, type ViewHostState, type ViewHostTransition, type ViewRequestId, } from "./view-host-protocol.js";
+export { attachViewHost, viewDocumentHtml, type AttachViewHostConfig, type ViewFrameLike, type ViewHostEvents, } from "./view-host.js";
+export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, type SandboxPageDeliveryConfig, } from "./sandbox-page.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC"}
+{"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,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,EACzB,eAAe,EACf,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -5,5 +5,9 @@
  */
 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";
+export { resolveViewMount, snapshotViewMount, toolResultViewMount, } from "./card-mount.js";
 export { createMcpUiResourceReader, uiResourceChannel, } from "./reader.js";
+export { asToolCallResult, createMcpUiActionRelay, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, } from "./action.js";
+export { initializeResult, initialViewHostState, teardownMessage, toolCallResponse, TOOLS_CALL_METHOD, viewHostElapsed, viewHostReceive, } from "./view-host-protocol.js";
+export { attachViewHost, viewDocumentHtml, } from "./view-host.js";
+export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, } from "./sandbox-page.js";

package/dist/react.d.ts

@@ -0,0 +1,94 @@
+/**
+ * React entry point (`@guuey/mcp-apps-host/react`).
+ *
+ * `<GuueyView>` is the one React-coupled surface — the root subpath stays
+ * React-free (narrowing, rehydration, the relay, `attachViewHost` itself),
+ * so server-side consumers never import React at all. The component is a
+ * CONVENIENCE composition of the framework-agnostic primitive: iframe
+ * creation + the sandbox invariant + the handshake + lifecycle. A host
+ * that needs a different composition (a transcript renderer, a non-React
+ * surface) uses `attachViewHost` directly.
+ *
+ * ## Sandbox posture (invariant, not preference)
+ *
+ * `sandbox="allow-scripts"` WITHOUT `allow-same-origin`: a `srcdoc` frame
+ * inherits its embedder's origin, so granting both would run
+ * agent-generated HTML AS the embedding page — reach into its DOM and its
+ * signed-in session, an XSS by construction. Dropping `allow-same-origin`
+ * puts the document in an opaque origin instead. Extra flags ride ON TOP
+ * via {@link GuueyViewProps.dangerouslyAddSandboxFlags} — named the way it
+ * is because every flag it adds widens what agent-generated HTML can do.
+ * `allow="clipboard-write"` is delegated by default: generated views own
+ * copy buttons, and without the delegation every one of them silently
+ * no-ops inside the opaque origin.
+ *
+ * ## Who paints which state
+ *
+ * While `"negotiating"`, the component shows a small non-blocking status
+ * line — never a bare blank frame (guuey#186 audit). On `"connected"` the
+ * view owns its pixels (and its own failures) and the line disappears. On
+ * `"no-handshake"` the meaning is channel-aware: a `"ggui"` shell always
+ * negotiates, so silence is a boot failure and is labeled as one; an
+ * `"inline"` card is arbitrary tenant HTML with no handshake obligation,
+ * so the status line simply retires and the document stands as rendered.
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import { type AttachViewHostConfig } from "./view-host.js";
+import type { ViewHostPhase } from "./view-host-protocol.js";
+import type { ResolvedViewMount } from "./card-mount.js";
+export { attachViewHost, viewDocumentHtml } from "./view-host.js";
+export type { AttachViewHostConfig, ViewFrameLike, ViewHostEvents } from "./view-host.js";
+export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, type SandboxPageDeliveryConfig, } from "./sandbox-page.js";
+export type { ViewHostPhase } from "./view-host-protocol.js";
+export type { ResolvedViewMount, ViewMount, ViewMountChannel } from "./card-mount.js";
+export interface GuueyViewProps extends Pick<AttachViewHostConfig, "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "negotiationTimeoutMs"> {
+    /** The resolved card to mount (see `toolResultViewMount`/`resolveViewMount`). */
+    mount: ResolvedViewMount;
+    /**
+     * Opt into the TWO-ORIGIN mount: instead of `srcdoc`, the frame loads
+     * this host-served sandbox page (guuey's `/mcp-app-sandbox` pattern — the
+     * caller builds the full URL, channel/app query included) and the
+     * document is delivered over the page's relay protocol
+     * (`attachSandboxPageDelivery`). Why: a `srcdoc` frame INHERITS the
+     * embedder's CSP, so its egress confinement is whatever the page happens
+     * to carry; the sandbox page is served WITH the per-request CSP that
+     * confines the mount — and the untrusted document lands in the page's
+     * own inner opaque frame, never in this one. In this mode the frame's
+     * `sandbox` gains `allow-same-origin` — REQUIRED and safe: the frame
+     * holds the cross-origin RELAY PAGE (which must run as its real origin
+     * for its CSP + referrer checks to mean anything), never agent HTML.
+     * The page must be a genuinely different origin; a same-origin URL is
+     * refused with a labeled state, never mounted.
+     */
+    sandboxPageUrl?: string;
+    /**
+     * Sandbox flags appended to the safe default (`allow-scripts`). Every
+     * entry widens what agent-generated HTML may do — `allow-same-origin`
+     * in particular hands it the embedder's origin. Prefer leaving unset.
+     * In `sandboxPageUrl` mode these forward to the INNER frame via the
+     * page's relay (which strips `allow-same-origin` regardless).
+     */
+    dangerouslyAddSandboxFlags?: string[];
+    /** Permissions-Policy delegation for the frame. Default `clipboard-write`. */
+    allow?: string;
+    /** Accessible frame title. Default "Generated view". */
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Observe the negotiation phase (the same states the default UI labels). */
+    onPhaseChange?: (phase: ViewHostPhase) => void;
+    /**
+     * Replace the default status/failure line for a phase. Return `null` for
+     * "render nothing". The default: a quiet "Negotiating with view…" line
+     * while `"negotiating"`; a labeled failure for `"no-handshake"` on the
+     * `"ggui"` channel; nothing once `"connected"` (the view owns its
+     * pixels) and nothing for a silent `"inline"` card.
+     */
+    renderStatus?: (phase: ViewHostPhase) => ReactNode;
+}
+/**
+ * Mount a resolved view and play the MCP Apps Host for it. See the module
+ * docblock for the sandbox and state contracts.
+ */
+export declare function GuueyView(props: GuueyViewProps): ReactNode;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAwC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjG,OAAO,EAAoC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKtF,MAAM,WAAW,cACf,SAAQ,IAAI,CACV,oBAAoB,EACpB,kBAAkB,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,sBAAsB,CACxF;IACD,iFAAiF;IACjF,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,SAAS,CAAC;CACpD;AA+BD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAiI1D"}

package/dist/react.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * React entry point (`@guuey/mcp-apps-host/react`).
+ *
+ * `<GuueyView>` is the one React-coupled surface — the root subpath stays
+ * React-free (narrowing, rehydration, the relay, `attachViewHost` itself),
+ * so server-side consumers never import React at all. The component is a
+ * CONVENIENCE composition of the framework-agnostic primitive: iframe
+ * creation + the sandbox invariant + the handshake + lifecycle. A host
+ * that needs a different composition (a transcript renderer, a non-React
+ * surface) uses `attachViewHost` directly.
+ *
+ * ## Sandbox posture (invariant, not preference)
+ *
+ * `sandbox="allow-scripts"` WITHOUT `allow-same-origin`: a `srcdoc` frame
+ * inherits its embedder's origin, so granting both would run
+ * agent-generated HTML AS the embedding page — reach into its DOM and its
+ * signed-in session, an XSS by construction. Dropping `allow-same-origin`
+ * puts the document in an opaque origin instead. Extra flags ride ON TOP
+ * via {@link GuueyViewProps.dangerouslyAddSandboxFlags} — named the way it
+ * is because every flag it adds widens what agent-generated HTML can do.
+ * `allow="clipboard-write"` is delegated by default: generated views own
+ * copy buttons, and without the delegation every one of them silently
+ * no-ops inside the opaque origin.
+ *
+ * ## Who paints which state
+ *
+ * While `"negotiating"`, the component shows a small non-blocking status
+ * line — never a bare blank frame (guuey#186 audit). On `"connected"` the
+ * view owns its pixels (and its own failures) and the line disappears. On
+ * `"no-handshake"` the meaning is channel-aware: a `"ggui"` shell always
+ * negotiates, so silence is a boot failure and is labeled as one; an
+ * `"inline"` card is arbitrary tenant HTML with no handshake obligation,
+ * so the status line simply retires and the document stands as rendered.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { attachViewHost, viewDocumentHtml } from "./view-host.js";
+import { attachSandboxPageDelivery } from "./sandbox-page.js";
+export { attachViewHost, viewDocumentHtml } from "./view-host.js";
+export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, } from "./sandbox-page.js";
+/** Accessible name for a mounted view when the caller has nothing better. */
+const DEFAULT_TITLE = "Generated view";
+const statusLineStyle = {
+    position: "absolute",
+    insetInlineStart: 8,
+    insetBlockEnd: 8,
+    margin: 0,
+    padding: "2px 8px",
+    fontSize: 12,
+    lineHeight: "18px",
+    opacity: 0.65,
+    pointerEvents: "none",
+};
+function defaultStatus(phase, channel) {
+    if (phase === "negotiating") {
+        return _jsx("p", { style: statusLineStyle, children: "Negotiating with view\u2026" });
+    }
+    if (phase === "no-handshake" && channel === "ggui") {
+        // A ggui shell negotiates unconditionally before painting, so silence
+        // here is a boot failure with no other author — label it (role=alert
+        // so it is announced, not just drawn).
+        return (_jsx("p", { role: "alert", style: { ...statusLineStyle, opacity: 1, pointerEvents: "auto" }, children: "This view did not start \u2014 it never negotiated with the host." }));
+    }
+    return null;
+}
+/**
+ * Mount a resolved view and play the MCP Apps Host for it. See the module
+ * docblock for the sandbox and state contracts.
+ */
+export function GuueyView(props) {
+    const { mount, sandboxPageUrl, dangerouslyAddSandboxFlags, allow, title, className, style, onPhaseChange, renderStatus, ...hostConfig } = props;
+    const frameRef = useRef(null);
+    const [phase, setPhase] = useState("negotiating");
+    const html = viewDocumentHtml(mount.resource);
+    // Vet the sandbox page once per URL. Same-origin is REFUSED (the widget's
+    // ResourceMount precedent, generalized): the whole point of the page is
+    // being a different origin — same-origin would hand the relay page (and
+    // through `allow-same-origin`, everything it can reach) the embedder's
+    // own origin.
+    const sandboxPage = useMemo(() => {
+        if (sandboxPageUrl === undefined)
+            return undefined;
+        let url;
+        try {
+            url = new URL(sandboxPageUrl);
+        }
+        catch {
+            return "refused";
+        }
+        if (typeof window !== "undefined" && url.origin === window.location.origin)
+            return "refused";
+        return url;
+    }, [sandboxPageUrl]);
+    const page = sandboxPage instanceof URL ? sandboxPage : undefined;
+    // The attachment is keyed to the mounted DOCUMENT, not to every render's
+    // fresh callback identities — host config rides a ref so the effect's
+    // dependency list is honestly just the document identity.
+    const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags });
+    latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags };
+    useEffect(() => {
+        // Keyed to the same identity the frame is (the resource uri): a new
+        // document boots fresh, and the previous negotiation's phase must not
+        // paper over it.
+        setPhase("negotiating");
+        const frame = frameRef.current;
+        if (frame === null || html === undefined)
+            return;
+        if (sandboxPageUrl !== undefined && page === undefined)
+            return; // refused config — nothing mounts
+        const resourceUri = mount.resource.uri;
+        const detachHost = attachViewHost(frame, {
+            ...latest.current.hostConfig,
+            resourceUri,
+            onPhaseChange: (next) => {
+                setPhase(next);
+                latest.current.onPhaseChange?.(next);
+            },
+        });
+        if (page === undefined)
+            return detachHost;
+        // Two-origin mode: the page announces readiness, the document is
+        // delivered over its relay (re-delivered on a reload's re-announce),
+        // and the view-host handshake crosses the same relay transparently.
+        const flags = latest.current.dangerouslyAddSandboxFlags;
+        const detachDelivery = attachSandboxPageDelivery(frame, {
+            pageOrigin: page.origin,
+            html,
+            ...(flags !== undefined && flags.length > 0
+                ? { sandbox: ["allow-scripts", ...flags].join(" ") }
+                : {}),
+        });
+        return () => {
+            detachDelivery();
+            detachHost();
+        };
+    }, [mount.resource.uri, html, sandboxPageUrl, page]);
+    if (html === undefined) {
+        // A resolved mount with no document is producer-side breakage; an
+        // empty frame would be a lie. Label it, in the same voice as the
+        // no-handshake state.
+        return (_jsx("div", { className: className, style: { position: "relative", ...style }, children: _jsx("p", { role: "alert", style: { ...statusLineStyle, opacity: 1, pointerEvents: "auto" }, children: "This view could not be displayed \u2014 its resource carries no document." }) }));
+    }
+    if (sandboxPageUrl !== undefined && page === undefined) {
+        // A malformed or SAME-ORIGIN sandbox page is a configuration state, not
+        // a property of the card — refused, labeled, never mounted.
+        return (_jsx("div", { className: className, style: { position: "relative", ...style }, children: _jsx("p", { role: "alert", style: { ...statusLineStyle, opacity: 1, pointerEvents: "auto" }, children: "Interactive view unavailable \u2014 the sandbox page is not usable from this origin." }) }));
+    }
+    return (_jsxs("div", { className: className, style: { position: "relative", ...style }, children: [_jsx("iframe", { ref: frameRef, ...(page !== undefined ? { src: page.href } : { srcDoc: html }), title: title ?? DEFAULT_TITLE, 
+                // srcdoc mode: the INVARIANT — agent HTML in an opaque origin, extra
+                // flags only widen knowingly. Page mode: the frame holds the
+                // cross-origin RELAY PAGE, which must run as its real origin
+                // (`allow-same-origin`) for its CSP/referrer machinery to exist at
+                // all; the agent HTML lands in the page's own inner opaque frame,
+                // and the caller's extra flags travel to THAT frame via the relay.
+                sandbox: page !== undefined
+                    ? "allow-scripts allow-same-origin allow-forms"
+                    : ["allow-scripts", ...(dangerouslyAddSandboxFlags ?? [])].join(" "), allow: allow ?? "clipboard-write", style: { display: "block", width: "100%", height: "100%", border: 0 } }, `${page?.href ?? "srcdoc"}::${mount.resource.uri}`), renderStatus !== undefined ? renderStatus(phase) : defaultStatus(phase, mount.channel)] }));
+}