@guuey/mcp-apps-host 0.4.0 → 0.6.0

package/dist/view-host.js

@@ -0,0 +1,184 @@
+/**
+ * `attachViewHost` — the DOM glue around `view-host-protocol.ts`'s pure
+ * machine (guuey#186 Gap 1). Framework-agnostic: any embedder with an
+ * iframe can play the MCP Apps Host role with one call; `react.tsx` is one
+ * convenience composition of exactly this, and a future full transcript
+ * renderer composes the same primitive differently.
+ *
+ * This module is glue by DESIGN — every decision (what to answer, what to
+ * refuse, when the negotiation window lapses) lives in the machine, which
+ * the Node-only publish gate can test. What genuinely needs a browser is
+ * this file's five moves: listen, identity-filter, post, time, detach —
+ * covered by the monorepo's Playwright leg (`e2e/`), which the guuey-sdks
+ * mirror deliberately does not carry.
+ *
+ * ## The identity filter (security invariant)
+ *
+ * Messages are matched by `event.source === frame.contentWindow`, NEVER by
+ * `event.origin`: a view frame runs `sandbox="allow-scripts"` WITHOUT
+ * `allow-same-origin`, so its origin is opaque — every message it posts
+ * carries `"null"`, a value every other sandboxed frame on the page
+ * shares, identifying nobody. The window handle is the only identity that
+ * names the frame; a frame with no `contentWindow` matches nothing rather
+ * than everything. Responses target `'*'` for the same reason: an opaque
+ * origin is not addressable by name, and the handshake payload carries no
+ * secrets — it is the result the spec defines for any host.
+ *
+ * Seeded from ggui's console `surface-host.ts` (donated, guuey#186 audit);
+ * re-derived here against the pure machine + our own tests.
+ */
+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;
+/** Derived + configured context, per the {@link AttachViewHostConfig.hostContext} contract. */
+function hostContextFor(frame, config) {
+    return {
+        locale: typeof navigator !== "undefined" ? navigator.language : "en-US",
+        ...(frame.clientWidth > 0 && frame.clientHeight > 0
+            ? { containerDimensions: { width: frame.clientWidth, height: frame.clientHeight } }
+            : {}),
+        ...config.hostContext,
+    };
+}
+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 } : {}),
+    };
+}
+/**
+ * Attach the Host role to a mounted view frame. Returns a detach function;
+ * call it before the frame unmounts — it stops listening and posts the
+ * spec-mannered `ui/resource-teardown` farewell through the CACHED window
+ * handle (post-removal, `frame.contentWindow` is already null).
+ */
+export function attachViewHost(frame, config = {}) {
+    const cachedWindow = frame.contentWindow;
+    let state = initialViewHostState();
+    const setState = (next) => {
+        const phaseChanged = next.phase !== state.phase;
+        state = next;
+        if (phaseChanged)
+            config.onPhaseChange?.(next.phase);
+    };
+    const post = (message) => {
+        frame.contentWindow?.postMessage(message, "*");
+    };
+    const relay = (id, name, args) => {
+        const { onCallTool, resourceUri } = config;
+        // The machine only emits the effect when the relay is wired (behavior
+        // is derived from this same config), so these are invariants, not
+        // runtime branches a view can steer.
+        if (onCallTool === undefined || resourceUri === undefined)
+            return;
+        onCallTool({ resourceUri, name, ...(args === undefined ? {} : { arguments: args }) }).then((result) => post(toolCallResponse(id, result)), 
+        // A relay hook that rejects (createMcpUiActionRelay never does, but
+        // the hook is embedder code) still owes the view an answer — the
+        // 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;
+        const { state: next, effects } = viewHostReceive(state, behaviorFor(frame, config), event.data);
+        setState(next);
+        for (const effect of effects) {
+            if (effect.kind === "respond")
+                post(effect.message);
+            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
+    // tests, and `window` — whose lib.dom listener typing wants the concrete
+    // `MessageEvent` — for the browser default.
+    const subscribe = () => {
+        const { events } = config;
+        if (events !== undefined) {
+            events.addEventListener("message", onMessage);
+            return () => events.removeEventListener("message", onMessage);
+        }
+        const domListener = (event) => onMessage(event);
+        window.addEventListener("message", domListener);
+        return () => window.removeEventListener("message", domListener);
+    };
+    const unsubscribe = subscribe();
+    const timeoutMs = config.negotiationTimeoutMs ?? DEFAULT_NEGOTIATION_TIMEOUT_MS;
+    const timer = timeoutMs > 0 ? setTimeout(() => setState(viewHostElapsed(state)), timeoutMs) : undefined;
+    return () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        unsubscribe();
+        cachedWindow?.postMessage(teardownMessage(), "*");
+    };
+}
+/**
+ * The document a {@link McpUiResourcePayload} mounts: `text` verbatim, or
+ * `blob` base64-decoded as UTF-8. `undefined` when the payload carries
+ * neither — nothing to put in `srcdoc`.
+ */
+export function viewDocumentHtml(resource) {
+    if (typeof resource.text === "string")
+        return resource.text;
+    if (typeof resource.blob === "string") {
+        try {
+            const bytes = Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0));
+            return new TextDecoder().decode(bytes);
+        }
+        catch {
+            // Malformed base64 is producer-side wire data, not an embedder bug —
+            // the honest answer is "no document" (the same labeled state a
+            // payload with neither field gets), not a render-time throw.
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",
@@ -24,14 +24,31 @@
       "types": "./dist/narrowing.d.ts",
       "import": "./dist/narrowing.js",
       "default": "./dist/narrowing.js"
+    },
+    "./react": {
+      "react-native": "./src/react.tsx",
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
     }
   },
   "dependencies": {
     "@ggui-ai/protocol": "0.9.0",
-    "@silverprotocol/core": "0.4.1"
+    "@modelcontextprotocol/ext-apps": "1.7.5",
+    "@silverprotocol/core": "0.5.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
   },

package/src/action.ts

@@ -58,7 +58,12 @@ export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
 export const UI_ACTION_UNAVAILABLE_TEXT =
   "This action isn't available right now.";
 
-function unavailable(): McpToolCallResult {
+/**
+ * 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(): McpToolCallResult {
   return {
     content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
     isError: true,
@@ -152,15 +157,15 @@ export function createMcpUiActionRelay(
   deps: CreateMcpUiActionRelayDeps,
 ): (request: UiActionRequest) => Promise<McpToolCallResult> {
   return async (request) => {
-    if (!UI_ACTION_TOOLS.has(request.name)) return unavailable();
-    if (!request.resourceUri.startsWith("ui://")) return unavailable();
+    if (!UI_ACTION_TOOLS.has(request.name)) return unavailableToolCallResult();
+    if (!request.resourceUri.startsWith("ui://")) return unavailableToolCallResult();
     let raw: unknown;
     try {
       raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
     } catch {
-      return unavailable(); // transport failure == unavailable, in-band
+      return unavailableToolCallResult(); // transport failure == unavailable, in-band
     }
-    if (raw === undefined) return unavailable();
-    return asToolCallResult(raw) ?? unavailable();
+    if (raw === undefined) return unavailableToolCallResult();
+    return asToolCallResult(raw) ?? unavailableToolCallResult();
   };
 }

package/src/card-mount.ts

@@ -143,6 +143,33 @@ export function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefine
   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: ViewMount | undefined,
+  reader?: UiResourceReader,
+): Promise<ResolvedViewMount | undefined> {
+  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/src/index.ts

@@ -28,6 +28,7 @@ export {
   type GguiShellHtmlOptions,
 } from "./ggui-render.js";
 export {
+  resolveViewMount,
   snapshotViewMount,
   toolResultViewMount,
   type LocatorViewMount,
@@ -45,6 +46,7 @@ export {
 export {
   asToolCallResult,
   createMcpUiActionRelay,
+  unavailableToolCallResult,
   UI_ACTION_TOOLS,
   UI_ACTION_UNAVAILABLE_TEXT,
   type CreateMcpUiActionRelayDeps,
@@ -53,3 +55,36 @@ export {
   type McpToolStructuredContent,
   type UiActionRequest,
 } from "./action.js";
+export {
+  initializeResult,
+  initialViewHostState,
+  resourceReadResponse,
+  RESOURCES_READ_METHOD,
+  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";

package/src/react.tsx

@@ -0,0 +1,314 @@
+/**
+ * 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, type CSSProperties, type ReactNode } from "react";
+import { attachViewHost, viewDocumentHtml, type AttachViewHostConfig } from "./view-host.js";
+import { attachSandboxPageDelivery } from "./sandbox-page.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";
+
+/** Accessible name for a mounted view when the caller has nothing better. */
+const DEFAULT_TITLE = "Generated view";
+
+export interface GuueyViewProps
+  extends Pick<
+    AttachViewHostConfig,
+    | "hostCapabilities"
+    | "hostInfo"
+    | "hostContext"
+    | "onCallTool"
+    | "onReadResource"
+    | "onSizeChanged"
+    | "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.
+   *
+   * `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 | 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`
+   * 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;
+}
+
+const statusLineStyle: CSSProperties = {
+  position: "absolute",
+  insetInlineStart: 8,
+  insetBlockEnd: 8,
+  margin: 0,
+  padding: "2px 8px",
+  fontSize: 12,
+  lineHeight: "18px",
+  opacity: 0.65,
+  pointerEvents: "none",
+};
+
+function defaultStatus(phase: ViewHostPhase, channel: ResolvedViewMount["channel"]): ReactNode {
+  if (phase === "negotiating") {
+    return <p style={statusLineStyle}>Negotiating with view…</p>;
+  }
+  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 (
+      <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
+        This view did not start — it never negotiated with the host.
+      </p>
+    );
+  }
+  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: GuueyViewProps): ReactNode {
+  const {
+    mount,
+    sandboxPageUrl,
+    autoResize,
+    dangerouslyAddSandboxFlags,
+    allow,
+    title,
+    className,
+    style,
+    onPhaseChange,
+    renderStatus,
+    ...hostConfig
+  } = 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. `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);
+    } 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, 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 — 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
+    const resourceUri = mount.resource.uri;
+    const detachHost = attachViewHost(frame, {
+      ...latest.current.hostConfig,
+      resourceUri,
+      onPhaseChange: (next) => {
+        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
+    // 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 (
+      <div className={className} style={{ position: "relative", ...style }}>
+        <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
+          This view could not be displayed — its resource carries no document.
+        </p>
+      </div>
+    );
+  }
+
+  if (sandboxPageUrl !== undefined && page === undefined) {
+    // 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" }}>
+          {sandboxPageUrl === null
+            ? "Interactive view unavailable — no sandbox page is configured."
+            : "Interactive view unavailable — the sandbox page is not usable from this origin."}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={{ position: "relative", ...style }}>
+      <iframe
+        ref={frameRef}
+        // Remount on a new resource (or mount mode) rather than reusing the
+        // frame: a view runtime boots once from the document it was handed,
+        // so swapping `srcDoc` in place would leave the old boot running
+        // against new markup.
+        key={`${page?.href ?? "srcdoc"}::${mount.resource.uri}`}
+        {...(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"}
+        // 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>
+  );
+}