@guuey/mcp-apps-host 0.5.0 → 0.6.1

package/dist/view-host.d.ts

@@ -28,6 +28,7 @@
  * re-derived here against the pure machine + our own tests.
  */
 import { type ViewHostPhase } from "./view-host-protocol.js";
+import type { McpResourceReadResult } from "./reader.js";
 import { type McpToolCallResult, type UiActionRequest } from "./action.js";
 import type { McpUiResourcePayload } from "./block-ui.js";
 import type { McpUiHostCapabilities, McpUiHostContext } from "@modelcontextprotocol/ext-apps";
@@ -91,6 +92,28 @@ export interface AttachViewHostConfig {
      * `<GuueyView>` fills it from the mount automatically.
      */
     resourceUri?: string;
+    /**
+     * The `resources/read` relay — a PRIVILEGE boundary like
+     * {@link onCallTool}, default off: with no hook, the machine refuses
+     * `resources/read` in-band and advertises no `serverResources`. The hook
+     * is structurally the SAME transport `createMcpUiResourceReader`
+     * assembles over ({@link CreateMcpUiResourceReaderDeps.readResource}) —
+     * a host with a locator reader wires the identical function here. Trust
+     * rules ride the reader discipline (`reader.ts`): enforcement lives
+     * INSIDE the transport; a miss, a deny, and a throw all answer the view
+     * with the one `Resource not found` error (deny == miss — no oracle).
+     */
+    onReadResource?: (uri: string) => Promise<McpResourceReadResult | undefined>;
+    /**
+     * The view reported its content size (`ui/notifications/size-changed` —
+     * spec notification). Whether and how to resize the frame is the
+     * embedder's layout decision; `<GuueyView autoResize>` is one wiring of
+     * exactly this callback.
+     */
+    onSizeChanged?: (size: {
+        width?: number;
+        height?: number;
+    }) => void;
     /** Observe phase transitions (see {@link ViewHostPhase}). */
     onPhaseChange?: (phase: ViewHostPhase) => void;
     /**

package/dist/view-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-host.d.ts","sourceRoot":"","sources":["../src/view-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAQL,KAAK,aAAa,EAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE;QAAE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;IACR,mBAAmB,CACjB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;CACT;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AA6BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAgElG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAcnF"}
+{"version":3,"file":"view-host.d.ts","sourceRoot":"","sources":["../src/view-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EASL,KAAK,aAAa,EAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE;QAAE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;IACR,mBAAmB,CACjB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;CACT;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;IAC7E;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpE,6DAA6D;IAC7D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAoDD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAkFlG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAcnF"}

package/dist/view-host.js

@@ -27,7 +27,7 @@
  * Seeded from ggui's console `surface-host.ts` (donated, guuey#186 audit);
  * re-derived here against the pure machine + our own tests.
  */
-import { initialViewHostState, teardownMessage, toolCallResponse, viewHostElapsed, viewHostReceive, } from "./view-host-protocol.js";
+import { initialViewHostState, resourceReadResponse, teardownMessage, toolCallResponse, viewHostElapsed, viewHostReceive, } from "./view-host-protocol.js";
 import { unavailableToolCallResult, } from "./action.js";
 const DEFAULT_HOST_INFO = { name: "guuey-view-host", version: "1" };
 const DEFAULT_NEGOTIATION_TIMEOUT_MS = 8000;
@@ -43,14 +43,38 @@ function hostContextFor(frame, config) {
 }
 function behaviorFor(frame, config) {
     const relayWired = config.onCallTool !== undefined && config.resourceUri !== undefined;
+    const readWired = config.onReadResource !== undefined;
     return {
         hostInfo: config.hostInfo ?? DEFAULT_HOST_INFO,
         hostCapabilities: {
+            // A wired relay IS the implementation — advertise it; an explicit
+            // hostCapabilities entry still wins (the serverTools precedent).
             ...(relayWired ? { serverTools: {} } : {}),
+            ...(readWired ? { serverResources: {} } : {}),
             ...config.hostCapabilities,
         },
         hostContext: hostContextFor(frame, config),
         toolRelay: relayWired,
+        resourceRelay: readWired,
+    };
+}
+/**
+ * Re-narrow a read hook's answer at the trust boundary — hooks are embedder
+ * code (possibly plain JS), and the wire entry the view receives must be a
+ * real `contents[]` entry: `uri` required, a string payload arm required
+ * (a payload-less entry is a miss — the `createMcpUiResourceReader`
+ * discipline, applied to the WIRE entry rather than the mountable payload).
+ */
+function narrowReadEntry(entry) {
+    if (entry === undefined || typeof entry.uri !== "string")
+        return undefined;
+    if (typeof entry.text !== "string" && typeof entry.blob !== "string")
+        return undefined;
+    return {
+        uri: entry.uri,
+        ...(typeof entry.mimeType === "string" ? { mimeType: entry.mimeType } : {}),
+        ...(typeof entry.text === "string" ? { text: entry.text } : {}),
+        ...(typeof entry.blob === "string" ? { blob: entry.blob } : {}),
     };
 }
 /**
@@ -84,6 +108,15 @@ export function attachViewHost(frame, config = {}) {
         // same in-band unavailable the relay itself uses, never a hang.
         () => post(toolCallResponse(id, unavailableToolCallResult())));
     };
+    const relayRead = (id, uri) => {
+        const { onReadResource } = config;
+        if (onReadResource === undefined)
+            return; // machine-guarded invariant, as with `relay`
+        onReadResource(uri).then((entry) => post(resourceReadResponse(id, narrowReadEntry(entry))), 
+        // A throwing hook still owes the view an answer — the same not-found
+        // the reader discipline gives a deny (deny == miss), never a hang.
+        () => post(resourceReadResponse(id, undefined)));
+    };
     const onMessage = (event) => {
         if (frame.contentWindow === null || event.source !== frame.contentWindow)
             return;
@@ -92,8 +125,16 @@ export function attachViewHost(frame, config = {}) {
         for (const effect of effects) {
             if (effect.kind === "respond")
                 post(effect.message);
-            else
+            else if (effect.kind === "relay-tool-call")
                 relay(effect.id, effect.name, effect.arguments);
+            else if (effect.kind === "relay-resource-read")
+                relayRead(effect.id, effect.uri);
+            else {
+                config.onSizeChanged?.({
+                    ...(effect.width !== undefined ? { width: effect.width } : {}),
+                    ...(effect.height !== undefined ? { height: effect.height } : {}),
+                });
+            }
         }
     };
     // One listener, two subscription paths: the injectable seam for Node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@ggui-ai/protocol": "0.9.0",
     "@modelcontextprotocol/ext-apps": "1.7.5",
-    "@silverprotocol/core": "0.4.1"
+    "@silverprotocol/core": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/action.ts

@@ -47,11 +47,39 @@ export type McpToolCallResult = {
 };
 
 /**
- * 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).
+ * The runtime tools a card sandbox may RELAY over `tools/call` — the
+ * client-side twin of the server allowlist (defense in depth: the proxy
+ * enforces it again). Exactly ggui's iframe-runtime surface, all declared
+ * `_meta.ui.visibility: ['app']` (never model-callable):
+ *
+ *  - `ggui_runtime_submit_action` — the user's gesture (the SEMANTIC one);
+ *  - `ggui_runtime_refresh_ws_token` — live-channel credential refresh
+ *    (the wsToken TTL is 180 s; without the relay a view on SSE/polling
+ *    dies at that mark — guuey#220);
+ *  - `ggui_runtime_pull` — the host-relayed polling rung where the
+ *    sandbox's own transports are blocked (bridge-pull, terminal rung).
+ *
+ * Two of these are transport plumbing whose arguments are opaque runtime
+ * state — see {@link UI_SEMANTIC_ACTION_TOOLS} for the ONLY set a host may
+ * treat as "the user did something".
  */
 export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
   "ggui_runtime_submit_action",
+  "ggui_runtime_refresh_ws_token",
+  "ggui_runtime_pull",
+]);
+
+/**
+ * The strict subset of {@link UI_ACTION_TOOLS} that carries a USER gesture —
+ * the only calls a host may project into user-facing affordances (composer
+ * staging, "the user selected X" copy, telemetry as intent). Every other
+ * relayed tool is runtime plumbing whose payload must NEVER reach the user
+ * verbatim (guuey#215/#218: a staged `sessionId …` was exactly that leak).
+ * A tool that is relayable is NOT thereby semantic; a host that widens
+ * this set is asserting the wire semantics of the new name.
+ */
+export const UI_SEMANTIC_ACTION_TOOLS: ReadonlySet<string> = new Set([
+  "ggui_runtime_submit_action",
 ]);
 
 /** The in-band answer for anything the relay cannot (or will not) do. */

package/src/block-ui.ts

@@ -175,6 +175,27 @@ export function uiLocator(uiData: JsonValue | undefined): string | undefined {
   return typeof uri === "string" && uri.startsWith("ui://") ? uri : undefined;
 }
 
+/**
+ * The `ui://` locator a `tool-result` block carries, from EITHER channel it
+ * can arrive on — the single seam every locator reader goes through.
+ *
+ * AgJSON §2.1 routes a tool result's `structuredContent` by its `_meta.ui`
+ * sibling: WITH the sibling it is surface data and the normalizer stamps
+ * `uiData`; WITHOUT it, it is model-channel data and lands in
+ * `structuredContent`. A producer that withholds `_meta` (ggui's non-prod
+ * posture; any plain-locator MCP server) therefore delivers a locator that
+ * is byte-identical in shape but lives one field over — reading `uiData`
+ * alone renders NOTHING for it (dark, not "expired"), and the persistence
+ * projector minted no placeholder row (the read plane 404s). `uiData` wins
+ * when both carry one (guuey#209 route-A finding).
+ */
+export function toolResultLocator(block: {
+  uiData?: JsonValue;
+  structuredContent?: JsonValue;
+}): string | undefined {
+  return uiLocator(block.uiData) ?? uiLocator(block.structuredContent);
+}
+
 export function snapshotUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined {
   if (!isJsonObject(cardSnapshot)) return undefined;
   const parts = cardSnapshot.parts;

package/src/card-mount.ts

@@ -33,7 +33,7 @@
  * keeps that one narrowing in one place — the alternative was for every host
  * to re-run `toolResultGguiRender` beside this call and ask again.
  */
-import { snapshotUiResource, toolResultUiResource, uiLocator, type McpUiResourcePayload } from "./block-ui.js";
+import { snapshotUiResource, toolResultLocator, toolResultUiResource, type McpUiResourcePayload } from "./block-ui.js";
 import { GGUI_RENDER_META_KEY, gguiRenderResource, toolResultGguiRender } from "./ggui-render.js";
 import type { AgBlock, JsonValue } from "@silverprotocol/core";
 
@@ -56,7 +56,9 @@ export type ViewMountChannel = "inline" | "ggui" | "locator";
  * `"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
+ * identity (guuey#122) — read from `uiData` OR, for a producer that
+ * withheld `_meta` (AgJSON §2.1 then routes it to `structuredContent`),
+ * from `structuredContent` (guuey#209): 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`
@@ -79,7 +81,7 @@ export interface ResolvedViewMount {
 /** The durable-identity arm: no mount material, only the uri to re-fetch. */
 export interface LocatorViewMount {
   channel: "locator";
-  /** The persisted `uiData.resourceUri` (`ui://` scheme) to re-fetch. */
+  /** The durable `ui://` locator to re-fetch (`uiData.resourceUri`, else `structuredContent.resourceUri`). */
   resourceUri: string;
 }
 
@@ -108,8 +110,10 @@ export function toolResultViewMount(
   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
+  // dropped `_meta`, or a producer that never sent it — the locator then
+  // rides `structuredContent`, see `toolResultLocator`): 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)) {
@@ -117,7 +121,7 @@ export function toolResultViewMount(
       `mcp-apps-host: tool result ${block.toolCallId} carries a malformed ggui render bootstrap — degrading to the locator channel`,
     );
   }
-  const locator = uiLocator(block.uiData);
+  const locator = toolResultLocator(block);
   return locator !== undefined ? { channel: "locator", resourceUri: locator } : undefined;
 }
 
@@ -137,7 +141,7 @@ export function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefine
   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);
+    const locator = toolResultLocator(block);
     if (locator !== undefined) return { channel: "locator", resourceUri: locator };
   }
   return undefined;

package/src/index.ts

@@ -11,6 +11,7 @@ export {
   resourceHtml,
   scanProviderRawForUiResource,
   snapshotUiResource,
+  toolResultLocator,
   toolResultUiResource,
   uiLocator,
   type McpUiResourcePayload,
@@ -49,6 +50,7 @@ export {
   unavailableToolCallResult,
   UI_ACTION_TOOLS,
   UI_ACTION_UNAVAILABLE_TEXT,
+  UI_SEMANTIC_ACTION_TOOLS,
   type CreateMcpUiActionRelayDeps,
   type McpToolCallContent,
   type McpToolCallResult,
@@ -58,6 +60,8 @@ export {
 export {
   initializeResult,
   initialViewHostState,
+  resourceReadResponse,
+  RESOURCES_READ_METHOD,
   teardownMessage,
   toolCallResponse,
   TOOLS_CALL_METHOD,

package/src/narrowing.ts

@@ -13,6 +13,7 @@ export {
   resourceHtml,
   scanProviderRawForUiResource,
   snapshotUiResource,
+  toolResultLocator,
   toolResultUiResource,
   uiLocator,
   type McpUiResourcePayload,

package/src/react.tsx

@@ -56,7 +56,13 @@ const DEFAULT_TITLE = "Generated view";
 export interface GuueyViewProps
   extends Pick<
     AttachViewHostConfig,
-    "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "negotiationTimeoutMs"
+    | "hostCapabilities"
+    | "hostInfo"
+    | "hostContext"
+    | "onCallTool"
+    | "onReadResource"
+    | "onSizeChanged"
+    | "negotiationTimeoutMs"
   > {
   /** The resolved card to mount (see `toolResultViewMount`/`resolveViewMount`). */
   mount: ResolvedViewMount;
@@ -75,8 +81,23 @@ export interface GuueyViewProps
    * 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.
+   *
+   * `null` (as opposed to absent) means the two-origin mount is REQUIRED
+   * by the embedder's posture but no page is configured — the mount is
+   * refused with the same labeled state, and srcdoc is NEVER fallen back
+   * to (falling back would silently trade the caller's egress confinement
+   * for the page's CSP; the widget/Studio convergence posture).
    */
-  sandboxPageUrl?: string;
+  sandboxPageUrl?: string | null;
+  /**
+   * Apply the view's own size reports (`ui/notifications/size-changed` —
+   * spec surface) to the frame: a reported HEIGHT becomes the frame's
+   * height; width stays the container's (a transcript column owns its
+   * width). Default OFF — the primitive changes nothing for existing
+   * hosts; a caller's {@link AttachViewHostConfig.onSizeChanged} observer
+   * fires either way.
+   */
+  autoResize?: boolean;
   /**
    * Sandbox flags appended to the safe default (`allow-scripts`). Every
    * entry widens what agent-generated HTML may do — `allow-same-origin`
@@ -140,6 +161,7 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   const {
     mount,
     sandboxPageUrl,
+    autoResize,
     dangerouslyAddSandboxFlags,
     allow,
     title,
@@ -151,15 +173,19 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   } = props;
   const frameRef = useRef<HTMLIFrameElement>(null);
   const [phase, setPhase] = useState<ViewHostPhase>("negotiating");
+  // The view's own size report, applied only under `autoResize`.
+  const [reportedHeight, setReportedHeight] = useState<number | undefined>(undefined);
   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.
+  // own origin. `null` — page mode required but unconfigured — refuses the
+  // same way: srcdoc is never a silent fallback for a confinement posture.
   const sandboxPage: URL | "refused" | undefined = useMemo(() => {
     if (sandboxPageUrl === undefined) return undefined;
+    if (sandboxPageUrl === null) return "refused";
     let url: URL;
     try {
       url = new URL(sandboxPageUrl);
@@ -174,14 +200,15 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   // 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 };
+  const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize });
+  latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize };
 
   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.
+    // paper over it — nor must the previous document's reported size.
     setPhase("negotiating");
+    setReportedHeight(undefined);
     const frame = frameRef.current;
     if (frame === null || html === undefined) return;
     if (sandboxPageUrl !== undefined && page === undefined) return; // refused config — nothing mounts
@@ -193,6 +220,12 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
         setPhase(next);
         latest.current.onPhaseChange?.(next);
       },
+      onSizeChanged: (size) => {
+        if (latest.current.autoResize === true && size.height !== undefined) {
+          setReportedHeight(size.height);
+        }
+        latest.current.hostConfig.onSizeChanged?.(size);
+      },
     });
     if (page === undefined) return detachHost;
     // Two-origin mode: the page announces readiness, the document is
@@ -226,12 +259,17 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   }
 
   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.
+    // A missing (null), malformed, or SAME-ORIGIN sandbox page is a
+    // configuration state, not a property of the card — refused, labeled,
+    // never mounted, and never silently downgraded to srcdoc. The copy
+    // names the configuration cause (an operator can act on it) without
+    // ever printing the offending URL.
     return (
       <div className={className} style={{ position: "relative", ...style }}>
         <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
-          Interactive view unavailable — the sandbox page is not usable from this origin.
+          {sandboxPageUrl === null
+            ? "Interactive view unavailable — no sandbox page is configured."
+            : "Interactive view unavailable — the sandbox page is not usable from this origin."}
         </p>
       </div>
     );
@@ -260,7 +298,15 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
             : ["allow-scripts", ...(dangerouslyAddSandboxFlags ?? [])].join(" ")
         }
         allow={allow ?? "clipboard-write"}
-        style={{ display: "block", width: "100%", height: "100%", border: 0 }}
+        // Under `autoResize`, the view's own height report wins over the
+        // fill-the-container default (width stays the container's — a
+        // transcript column owns its width).
+        style={{
+          display: "block",
+          width: "100%",
+          height: autoResize === true && reportedHeight !== undefined ? reportedHeight : "100%",
+          border: 0,
+        }}
       />
       {renderStatus !== undefined ? renderStatus(phase) : defaultStatus(phase, mount.channel)}
     </div>

package/src/view-host-protocol.ts

@@ -34,11 +34,13 @@ import {
   INITIALIZE_METHOD,
   LATEST_PROTOCOL_VERSION,
   RESOURCE_TEARDOWN_METHOD,
+  SIZE_CHANGED_METHOD,
   type McpUiHostCapabilities,
   type McpUiHostContext,
   type McpUiInitializeResult,
 } from "@modelcontextprotocol/ext-apps";
 import type { McpToolStructuredContent } from "./action.js";
+import type { McpResourceReadResult } from "./reader.js";
 
 /**
  * The host identity in the initialize result — structurally the spec's
@@ -56,6 +58,23 @@ const METHOD_NOT_SUPPORTED = -32601;
 /** The standard MCP method a view uses to reach host-proxied tools. */
 export const TOOLS_CALL_METHOD = "tools/call";
 
+/**
+ * The standard MCP method a view uses to read host-proxied resources —
+ * `ReadResourceRequest` in the spec's App→Host request union
+ * (`@modelcontextprotocol/ext-apps` `AppRequest`). A local constant, same
+ * as {@link TOOLS_CALL_METHOD}: the string is MCP-core vocabulary the
+ * ext-apps root does not re-export, and this package deliberately carries
+ * no `@modelcontextprotocol/sdk` dependency.
+ */
+export const RESOURCES_READ_METHOD = "resources/read";
+
+/**
+ * MCP's `Resource not found` JSON-RPC code — the one answer for a miss, a
+ * transport deny, AND a relay failure (deny == miss: the reader discipline,
+ * `reader.ts` — the view gets no oracle for which locators resolve).
+ */
+const RESOURCE_NOT_FOUND = -32002;
+
 /** A JSON-RPC id as the wire allows it. */
 export type ViewRequestId = number | string;
 
@@ -117,6 +136,33 @@ export type ViewHostEffect =
       id: ViewRequestId;
       name: string;
       arguments?: McpToolStructuredContent;
+    }
+  | {
+      /**
+       * A `resources/read` the config accepted for relaying (spec surface:
+       * `ReadResourceRequest` rides the App→Host union, and the matching
+       * advertisement is `hostCapabilities.serverResources`). The glue runs
+       * the read hook and posts {@link resourceReadResponse}. Only emitted
+       * when {@link ViewHostBehavior.resourceRelay} is true — unwired, the
+       * machine refuses in-band like every other unsupported request.
+       */
+      kind: "relay-resource-read";
+      id: ViewRequestId;
+      uri: string;
+    }
+  | {
+      /**
+       * The view reported its content size (`ui/notifications/size-changed`
+       * — spec notification, App → Host). At least one of the two fields is
+       * a finite number; a notification carrying neither is consumed
+       * silently instead. The glue forwards this to the embedder
+       * ({@link AttachViewHostConfig.onSizeChanged} in `view-host.ts`) —
+       * whether/how to resize the frame is the embedder's layout decision,
+       * never the machine's.
+       */
+      kind: "size-changed";
+      width?: number;
+      height?: number;
     };
 
 /**
@@ -138,6 +184,8 @@ export interface ViewHostBehavior {
   hostContext: McpUiHostContext;
   /** Whether a `tools/call` relay hook is wired (see `view-host.ts`). */
   toolRelay: boolean;
+  /** Whether a `resources/read` relay hook is wired (see `view-host.ts`). */
+  resourceRelay: boolean;
 }
 
 /** The result of feeding one inbound frame (or the timeout) to the machine. */
@@ -205,6 +253,26 @@ export function toolCallResponse(
   return { jsonrpc: "2.0", id, result };
 }
 
+/**
+ * Build the in-band response for a relayed `resources/read`. An entry
+ * becomes the spec's `ReadResourceResult` (`contents: [entry]`); `undefined`
+ * — a miss, a deny, or a relay failure alike — becomes the one
+ * `Resource not found` error (deny == miss, {@link RESOURCE_NOT_FOUND}).
+ */
+export function resourceReadResponse(
+  id: ViewRequestId,
+  entry: McpResourceReadResult | undefined,
+): ViewHostOutbound {
+  if (entry === undefined) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code: RESOURCE_NOT_FOUND, message: "resource unavailable" },
+    };
+  }
+  return { jsonrpc: "2.0", id, result: { contents: [entry] } };
+}
+
 /**
  * The spec-mannered farewell a detaching host posts (`ui/resource-teardown`).
  * Sent WITHOUT an id — a host that is tearing the frame down cannot await a
@@ -237,10 +305,29 @@ export function viewHostReceive(
   if (req === undefined) return { state, effects: [] };
 
   if (req.id === undefined) {
-    // A notification. Track the one the handshake defines; consume the rest.
+    // A notification. Track the one the handshake defines, surface the one
+    // the embedder may act on; consume the rest.
     if (req.method === "ui/notifications/initialized" && !state.initializedSeen) {
       return { state: { ...state, initializedSeen: true }, effects: [] };
     }
+    if (req.method === SIZE_CHANGED_METHOD) {
+      const width = req.params?.["width"];
+      const height = req.params?.["height"];
+      const validWidth = typeof width === "number" && Number.isFinite(width);
+      const validHeight = typeof height === "number" && Number.isFinite(height);
+      if (validWidth || validHeight) {
+        return {
+          state,
+          effects: [
+            {
+              kind: "size-changed",
+              ...(validWidth ? { width } : {}),
+              ...(validHeight ? { height } : {}),
+            },
+          ],
+        };
+      }
+    }
     return { state, effects: [] };
   }
 
@@ -271,6 +358,19 @@ export function viewHostReceive(
     // fall through: a nameless tools/call is not a call we can relay.
   }
 
+  if (req.method === RESOURCES_READ_METHOD && behavior.resourceRelay) {
+    const uri = req.params?.["uri"];
+    if (typeof uri === "string") {
+      return { state, effects: [{ kind: "relay-resource-read", id: req.id, uri }] };
+    }
+    // fall through: a uri-less read is not a read we can relay.
+  }
+
+  const answered = [
+    INITIALIZE_METHOD,
+    ...(behavior.toolRelay ? [TOOLS_CALL_METHOD] : []),
+    ...(behavior.resourceRelay ? [RESOURCES_READ_METHOD] : []),
+  ];
   return {
     state,
     effects: [
@@ -281,7 +381,7 @@ export function viewHostReceive(
           id: req.id,
           error: {
             code: METHOD_NOT_SUPPORTED,
-            message: `method_not_supported: ${req.method} — this host answers ${INITIALIZE_METHOD}${behavior.toolRelay ? ` and ${TOOLS_CALL_METHOD}` : ""} only`,
+            message: `method_not_supported: ${req.method} — this host answers ${answered.join(", ")} only`,
           },
         },
       },