web: Wave 2 — spec-conformant MCP Apps host (rollup of #1565–#1572)

clients/web/README.md

@@ -54,6 +54,23 @@ Components live under `src/components/` in four layers, smallest to largest:
 
 Every screen and element has a `*.stories.tsx` (see [Storybook](#storybook)). Styling follows the Mantine-first rules in [`AGENTS.md`](../../AGENTS.md) — theme variants and component props over CSS, `--inspector-*` tokens over raw colors.
 
+## MCP Apps screen automation contract
+
+The Apps screen exposes a small, stable set of `data-testid` / `data-*` attributes so an automated driver (deep-link auto-open, CI review harness) can `waitForSelector` on a deterministic signal instead of sleeping. Treat these as a public contract — drivers depend on them staying stable:
+
+| Attribute | Where | Meaning |
+| --- | --- | --- |
+| `data-testid="apps-form"` | Apps content card | The container that carries the status/error attributes below. |
+| `data-app-status` | on `apps-form` | Renderer lifecycle: `idle` (nothing running) → `loading` (bridge building / `ui/initialize` in flight) → `ready` (view fired `notifications/initialized`) → `error` (bridge factory threw/rejected). Poll for `ready`. |
+| `data-app-error` | on `apps-form` | The failure reason string when `data-app-status="error"` (e.g. no connected client); absent otherwise. |
+| `data-testid="apps-error"` | error panel | Rendered below the frame when the app fails to load (factory throw/reject); shows the reason so the failure isn't a silent blank frame. |
+| `data-testid="open-app"` | Open App button | Launches the selected app. |
+| `data-testid="apps-stage"` | Stage-partial button | Snapshots the current form values for progressive-render testing. |
+| `data-testid="apps-messages"` | messages panel | `ui/message` submissions from the running view. |
+| `data-testid="apps-logs"` | app-logs panel | `notifications/message` log entries (default-expanded). |
+
+The renderer lifecycle itself is `AppRendererStatus` (`loading` | `ready` | `error`) reported via `AppRenderer`'s `onAppStatusChange`; the screen maps it to `data-app-status`. Resource-read failures (malformed/404 UI resource) are surfaced as a toast via the bridge factory's `onResourceError`; because the app never reaches `ready` in that case, a driver times out on `data-app-status` and reads the toast.
+
 ## Theme (`src/theme/`)
 
 Each customized Mantine component has a `Theme<Name>.ts` file (`Button.ts`, `Text.ts`, …, ~21 total) exporting a `Theme<Name>` constant; the barrel `index.ts` re-exports them and `theme.ts` assembles the `MantineProvider` theme. Theme files hold app-wide defaults and **variants** (flat CSS-in-JS); only pseudo-selectors, nested child selectors, keyframes, and native-HTML styling belong in `App.css`. Element components import from `@mantine/core` (never from `theme/`) — the theme layer is applied transparently by the provider.

clients/web/server/sandbox-controller.ts

@@ -47,6 +47,18 @@ export function createSandboxController(
   let server: Server | null = null;
   let sandboxUrl: string | null = null;
 
+  // Defense-in-depth for the proxy page itself. Only `frame-ancestors` is set
+  // here — fetch directives (`default-src`, `connect-src`, etc.) are
+  // deliberately omitted because a `srcdoc` iframe clones its embedder's CSP
+  // policy container: any fetch directive on this header would be inherited by
+  // the inner app document and, since multiple CSPs intersect, would override
+  // the per-app `connect-src`/`img-src` allowlists the host bakes into the
+  // wrapped HTML (see src/lib/sandbox-csp.ts). The opaque-origin sandbox on
+  // the inner frame is the structural boundary; `frame-ancestors` ensures the
+  // proxy can only be embedded by the local inspector itself.
+  const SANDBOX_PROXY_CSP =
+    "frame-ancestors http://127.0.0.1:* http://localhost:*";
+
   let sandboxHtml: string;
   try {
     const sandboxHtmlPath = join(__dirname, "../static/sandbox_proxy.html");
@@ -91,6 +103,7 @@ export function createSandboxController(
             "Content-Type": "text/html; charset=utf-8",
             "Cache-Control": "no-store, no-cache, must-revalidate",
             Pragma: "no-cache",
+            "Content-Security-Policy": SANDBOX_PROXY_CSP,
           });
           res.end(sandboxHtml);
         });

clients/web/src/App.tsx

@@ -708,6 +708,19 @@ function App() {
           const invocation = await inspectorClient.readResource(uri);
           return invocation.result;
         },
+        // The bridge's sandboxready handler reads + posts the UI resource
+        // inside a detached async block; without this hook a 404 / malformed
+        // resource is console.error-only and the user stares at a blank
+        // frame. Surface it as a toast. The renderer separately drives
+        // `data-app-status` so an automated driver can time out on
+        // never-reaching-"ready" and read the toast.
+        onResourceError: (err) => {
+          notifications.show({
+            title: "App resource failed to load",
+            message: err.message,
+            color: "red",
+          });
+        },
       }),
     [inspectorClient],
   );

clients/web/src/components/elements/AppRenderer/AppRenderer.stories.tsx

@@ -20,6 +20,9 @@ function createMockBridge(): AppBridge {
     sendToolInput: async () => {},
     sendToolResult: async () => {},
     sendToolCancelled: async () => {},
+    sendHostContextChange: async () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
     teardownResource: async () => ({}),
     close: async () => {},
   } as unknown as AppBridge;