@grackle-ai/web-components 0.110.1 → 0.110.3

package/mcp-app-sandbox/sample-widget.js

@@ -0,0 +1,74 @@
+// Sample MCP App (app-side) for the McpAppWidget Storybook story.
+//
+// Uses the REAL @modelcontextprotocol/ext-apps `App` class — bundled with its
+// dependencies inlined in app-with-deps.js (served by serve.mjs from the sandbox
+// origin) — so the ui/initialize -> initialized -> tool-input/tool-result
+// handshake is exactly spec-conformant. The previous hand-rolled handshake
+// rendered but never received data because its messages failed AppBridge's Zod
+// validation; the real App produces schema-correct messages.
+//
+// Loaded by the inner sandboxed iframe via `<script type="module">`. Relative
+// imports resolve against this module's URL (the sandbox origin), so
+// `./app-with-deps.js` is fetched from the same sidecar.
+
+import {
+  App,
+  PostMessageTransport,
+  applyHostStyleVariables,
+  applyHostFonts,
+  applyDocumentTheme,
+} from "./app-with-deps.js";
+
+const inEl = document.getElementById("in");
+const outEl = document.getElementById("out");
+const callBtn = document.getElementById("call");
+
+/** Render a CallToolResult `content` array into the result element. */
+function renderResult(content) {
+  const blocks = content ?? [];
+  outEl.textContent =
+    blocks
+      .map((block) => (block.type === "text" ? block.text : "<" + block.type + ">"))
+      .join(" ") || "(empty)";
+}
+
+const app = new App({ name: "SampleWeather", version: "1.0.0" }, {});
+
+// Register handlers BEFORE connect so the one-shot tool-input/result the host
+// sends right after the handshake are not missed.
+app.ontoolinput = (params) => {
+  inEl.textContent = JSON.stringify(params.arguments ?? {});
+};
+app.ontoolresult = (params) => {
+  renderResult(params.content);
+};
+
+/** Apply the host's theme + style variables to this document. */
+function applyHostStyles() {
+  const ctx = app.getHostContext();
+  if (ctx?.styles?.variables) {
+    applyHostStyleVariables(ctx.styles.variables);
+  }
+  if (ctx?.styles?.css?.fonts) {
+    applyHostFonts(ctx.styles.css.fonts);
+  }
+  if (ctx?.theme) {
+    applyDocumentTheme(ctx.theme);
+  }
+}
+app.onhostcontextchanged = () => applyHostStyles();
+
+// The Refresh button asks the host to run a tool on the App's behalf
+// (proxied to McpAppWidget's onCallTool prop in the story).
+callBtn.addEventListener("click", () => {
+  outEl.textContent = "(refreshing...)";
+  app
+    .callServerTool({ name: "refresh_weather", arguments: {} })
+    .then((result) => renderResult(result.content))
+    .catch((err) => {
+      outEl.textContent = "error: " + (err && err.message ? err.message : String(err));
+    });
+});
+
+await app.connect(new PostMessageTransport(window.parent, window.parent));
+applyHostStyles();

package/mcp-app-sandbox/sandbox-relay.js

@@ -0,0 +1,114 @@
+// Externalized relay for the MCP Apps outer sandbox proxy (loaded by sandbox.html).
+//
+// Kept as a separate module — served from the sandbox origin and loaded as
+// `script-src 'self'` — so the proxy CSP does NOT need `script-src 'unsafe-inline'`.
+// Implements the double-iframe relay between the host and the inner untrusted
+// widget per the MCP Apps spec (SEP-1865). Adapted from
+// modelcontextprotocol/ext-apps examples/basic-host/src/sandbox.ts (commit 9a37ad7).
+
+const RESOURCE_READY = "ui/notifications/sandbox-resource-ready";
+const PROXY_READY = "ui/notifications/sandbox-proxy-ready";
+const DEFAULT_SANDBOX = "allow-scripts allow-same-origin allow-forms";
+
+// Must run inside an iframe on a different origin than the host.
+if (window.self === window.top) {
+  throw new Error("sandbox.html must be loaded inside an iframe.");
+}
+if (!document.referrer) {
+  throw new Error("No referrer; cannot validate the embedding host origin.");
+}
+const EXPECTED_HOST_ORIGIN = new URL(document.referrer).origin;
+const OWN_ORIGIN = new URL(window.location.href).origin;
+
+// Security self-test: confirm we cannot reach the top window. Reading a property
+// on a cross-origin window.top throws a SecurityError without any visible side
+// effect (unlike alert()). If it does NOT throw, isolation is broken and we must
+// refuse to run.
+try {
+  const probe = window.top.location.href;
+  void probe;
+  throw "FAIL";
+} catch (e) {
+  if (e === "FAIL") {
+    throw new Error("Sandbox is not isolated (host and sandbox share an origin?).");
+  }
+}
+
+// Minimal copy of ext-apps buildAllowAttribute: maps requested permissions to an
+// iframe Permissions-Policy `allow` attribute.
+function buildAllowAttribute(permissions) {
+  if (!permissions || typeof permissions !== "object") {
+    return "";
+  }
+  const map = {
+    camera: "camera",
+    microphone: "microphone",
+    geolocation: "geolocation",
+    clipboardWrite: "clipboard-write",
+    clipboardRead: "clipboard-read",
+    displayCapture: "display-capture",
+  };
+  const out = [];
+  for (const key of Object.keys(permissions)) {
+    if (map[key]) {
+      out.push(`${map[key]} 'self'`);
+    }
+  }
+  return out.join("; ");
+}
+
+// Target origin for host -> inner messages. When the inner iframe keeps
+// `allow-same-origin`, its document shares OWN_ORIGIN, so we post to that exact
+// origin — if the widget navigates the frame elsewhere, delivery stops, which
+// prevents it from continuing to receive host-sent tool data. Opaque frames (no
+// `allow-same-origin`) have an unnameable null origin, so "*" is the only option.
+function innerTargetOrigin(sandboxValue) {
+  return /\ballow-same-origin\b/.test(sandboxValue) ? OWN_ORIGIN : "*";
+}
+
+const inner = document.createElement("iframe");
+inner.setAttribute("sandbox", DEFAULT_SANDBOX);
+let innerOrigin = innerTargetOrigin(DEFAULT_SANDBOX);
+document.body.appendChild(inner);
+
+window.addEventListener("message", (event) => {
+  if (event.source === window.parent) {
+    if (event.origin !== EXPECTED_HOST_ORIGIN) {
+      console.error("[sandbox] dropping parent message from", event.origin);
+      return;
+    }
+    if (event.data && event.data.method === RESOURCE_READY) {
+      const { html, sandbox, permissions } = event.data.params ?? {};
+      if (typeof sandbox === "string") {
+        inner.setAttribute("sandbox", sandbox);
+        innerOrigin = innerTargetOrigin(sandbox);
+      }
+      const allow = buildAllowAttribute(permissions);
+      if (allow) {
+        inner.setAttribute("allow", allow);
+      }
+      if (typeof html === "string") {
+        const doc = inner.contentDocument || inner.contentWindow?.document;
+        if (doc) {
+          doc.open();
+          doc.write(html);
+          doc.close();
+        } else {
+          inner.srcdoc = html;
+        }
+      }
+      return;
+    }
+    // Relay everything else host -> inner widget, scoped to the inner origin.
+    inner.contentWindow?.postMessage(event.data, innerOrigin);
+  } else if (event.source === inner.contentWindow) {
+    if (event.origin !== OWN_ORIGIN && event.origin !== "null") {
+      console.error("[sandbox] dropping inner message from", event.origin);
+      return;
+    }
+    // Relay inner widget -> host.
+    window.parent.postMessage(event.data, EXPECTED_HOST_ORIGIN);
+  }
+});
+
+window.parent.postMessage({ jsonrpc: "2.0", method: PROXY_READY, params: {} }, EXPECTED_HOST_ORIGIN);

package/mcp-app-sandbox/sandbox.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="color-scheme" content="light dark" />
+    <!--
+      MCP Apps outer sandbox proxy.
+
+      Double-iframe pattern per the MCP Apps spec (SEP-1865). This page is the
+      OUTER proxy and MUST be served from a different origin than the host (see
+      serve.mjs / GRACKLE_SANDBOX_PORT). It creates an INNER iframe for the
+      untrusted widget HTML and relays postMessage between host and widget.
+
+      CSP for the proxy + the inner widget is applied by serve.mjs via the HTTP
+      Content-Security-Policy header (built from the ?csp= query param) — it is
+      tamper-proof, unlike a <meta> tag. The relay is loaded as an EXTERNAL module
+      (sandbox-relay.js) from the sandbox origin so the CSP can keep
+      `script-src 'self'` (no 'unsafe-inline').
+
+      Adapted from modelcontextprotocol/ext-apps examples/basic-host/src/sandbox.ts
+      (commit 9a37ad7).
+    -->
+    <title>Grackle MCP App Sandbox</title>
+    <style>
+      html, body { margin: 0; height: 100vh; width: 100vw; background: transparent; }
+      body { display: flex; flex-direction: column; }
+      * { box-sizing: border-box; }
+      iframe {
+        background: transparent; border: 0 none transparent; padding: 0;
+        overflow: hidden; flex-grow: 1; color-scheme: inherit;
+      }
+    </style>
+  </head>
+  <body>
+    <script type="module" src="./sandbox-relay.js"></script>
+  </body>
+</html>

package/mcp-app-sandbox/serve.mjs

@@ -0,0 +1,145 @@
+// Sidecar static server for the MCP Apps sandbox proxy.
+//
+// Serves sandbox.html from a DIFFERENT ORIGIN than the host (Storybook), with a
+// per-request Content-Security-Policy set via HTTP header (built from the ?csp=
+// query param) — tamper-proof, unlike a <meta> tag. The CSP governs the inner
+// widget written into sandbox.html's inner iframe.
+//
+// Used in T1 (#1236) for Storybook; the production equivalent is the
+// GRACKLE_SANDBOX_PORT server in #1238. CSP-building logic mirrors
+// modelcontextprotocol/ext-apps examples/basic-host/serve.ts (commit 9a37ad7).
+
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+const PORT = parseInt(process.env.MCP_SANDBOX_PORT ?? "6007", 10);
+const HOST = process.env.MCP_SANDBOX_HOST ?? "127.0.0.1";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SANDBOX_FILE = join(HERE, "sandbox.html");
+// The thin app-side widget module loaded by the inner iframe.
+const SAMPLE_WIDGET_FILE = join(HERE, "sample-widget.js");
+// The REAL @modelcontextprotocol/ext-apps App, pre-bundled with deps inlined,
+// resolved from node_modules so it stays in sync with the installed version.
+let APP_WITH_DEPS_FILE;
+try {
+  APP_WITH_DEPS_FILE = require.resolve("@modelcontextprotocol/ext-apps/app-with-deps");
+} catch {
+  APP_WITH_DEPS_FILE = undefined;
+}
+
+// The externalized proxy relay (loaded by sandbox.html as `script-src 'self'`).
+const SANDBOX_RELAY_FILE = join(HERE, "sandbox-relay.js");
+
+// Static JS files served (as ES modules). The relay runs in the proxy page; the
+// widget modules run in the inner sandboxed iframe (both as same-origin 'self').
+const JS_ROUTES = {
+  "/sandbox-relay.js": () => SANDBOX_RELAY_FILE,
+  "/sample-widget.js": () => SAMPLE_WIDGET_FILE,
+  "/app-with-deps.js": () => APP_WITH_DEPS_FILE,
+};
+
+/** Reject CSP domain entries with characters that could break out of a directive. */
+function sanitizeCspDomains(domains) {
+  if (!Array.isArray(domains)) return [];
+  return domains.filter((d) => typeof d === "string" && !/[;\r\n'" ]/.test(d));
+}
+
+/** Build the Content-Security-Policy header value from an optional McpUiResourceCsp. */
+function buildCspHeader(csp) {
+  const resourceDomains = sanitizeCspDomains(csp?.resourceDomains).join(" ");
+  const connectDomains = sanitizeCspDomains(csp?.connectDomains).join(" ");
+  const frameDomains = sanitizeCspDomains(csp?.frameDomains).join(" ");
+  const baseUriDomains = sanitizeCspDomains(csp?.baseUriDomains).join(" ");
+  return [
+    "default-src 'self'",
+    // Scripts: only same-origin (the relay + widget modules are served from this
+    // origin) plus blob: for widgets that spawn workers. No 'unsafe-inline' (the
+    // relay is an external module), no 'unsafe-eval' (the ext-apps App runs zod in
+    // jitless mode), no data: scripts.
+    `script-src 'self' blob: ${resourceDomains}`.trim(),
+    // Styles still allow 'unsafe-inline' — widgets routinely use <style> blocks
+    // and inline style attributes, which is far lower-risk than inline scripts.
+    `style-src 'self' 'unsafe-inline' blob: data: ${resourceDomains}`.trim(),
+    `img-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `font-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `media-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `connect-src 'self' ${connectDomains}`.trim(),
+    `worker-src 'self' blob: ${resourceDomains}`.trim(),
+    frameDomains ? `frame-src ${frameDomains}` : "frame-src 'none'",
+    "object-src 'none'",
+    baseUriDomains ? `base-uri ${baseUriDomains}` : "base-uri 'none'",
+  ].join("; ");
+}
+
+const server = createServer((req, res) => {
+  const requestUrl = new URL(req.url ?? "/", `http://${req.headers.host ?? HOST}`);
+  const path = requestUrl.pathname;
+
+  // Serve the app-side JS modules (the bundled App + the sample widget) that the
+  // inner widget loads. `script-src 'self'` permits these because the inner
+  // iframe shares the sandbox origin (allow-same-origin).
+  const jsResolver = JS_ROUTES[path];
+  if (jsResolver) {
+    const file = jsResolver();
+    let js;
+    try {
+      js = file ? readFileSync(file, "utf-8") : undefined;
+    } catch {
+      js = undefined;
+    }
+    if (!js) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end(`Not found: ${path}`);
+      return;
+    }
+    res.writeHead(200, {
+      "Content-Type": "text/javascript; charset=utf-8",
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "Access-Control-Allow-Origin": "*",
+    });
+    res.end(js);
+    return;
+  }
+
+  if (path !== "/" && path !== "/sandbox.html") {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Only sandbox.html and the widget JS modules are served on this port.");
+    return;
+  }
+
+  let csp;
+  const cspParam = requestUrl.searchParams.get("csp");
+  if (cspParam) {
+    try {
+      csp = JSON.parse(cspParam);
+    } catch {
+      // Ignore an unparseable csp param and fall back to the locked-down default.
+    }
+  }
+
+  let html;
+  try {
+    html = readFileSync(SANDBOX_FILE, "utf-8");
+  } catch {
+    res.writeHead(500, { "Content-Type": "text/plain" });
+    res.end("sandbox.html not found");
+    return;
+  }
+
+  res.writeHead(200, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Content-Security-Policy": buildCspHeader(csp),
+    "Cache-Control": "no-cache, no-store, must-revalidate",
+    "Access-Control-Allow-Origin": "*",
+  });
+  res.end(html);
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`[mcp-sandbox] serving sandbox.html at http://${HOST}:${PORT}/sandbox.html`);
+});

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@grackle-ai/web-components",
-  "version": "0.110.1",
+  "version": "0.110.3",
   "description": "Presentational React component library for the Grackle web UI",
   "license": "MIT",
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/nick-pape/grackle.git",
@@ -25,6 +29,8 @@
   "main": "src/index.ts",
   "dependencies": {
     "@bufbuild/protobuf": "^2.5.0",
+    "@modelcontextprotocol/ext-apps": "1.7.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@dagrejs/dagre": "^2.0.4",
     "@xyflow/react": "^12.10.0",
     "motion": "^11.18.0",
@@ -40,7 +46,7 @@
     "remark-gfm": "^4.0.0",
     "lucide-react": "~0.474.0",
     "react-router": "^7.0.0",
-    "@grackle-ai/common": "0.110.1"
+    "@grackle-ai/common": "0.110.3"
   },
   "devDependencies": {
     "@rushstack/heft": "1.2.7",
@@ -77,6 +83,8 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test-storybook": "test-storybook",
+    "mcp-sandbox": "node mcp-app-sandbox/serve.mjs",
+    "storybook:mcp": "concurrently -k -n sandbox,storybook \"node mcp-app-sandbox/serve.mjs\" \"storybook dev -p 6006\"",
     "_phase:build": "heft run --only build -- --clean",
     "_phase:test": "heft run --only test"
   }

package/rush-logs/web-components._phase_build.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: 3629cc83b3804ac8bcea27905e83162210fb5dd6
+Cache key: de557b666a8980e74bc5c775dc53097f779f8d53
 Clearing cached folders: dist, storybook-static, .rush/temp/operation/_phase_build
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_build.log

@@ -7,12 +7,12 @@ Invoking: heft run --only build -- --clean
 [build:lint] Using ESLint version 9.39.4
 vite v6.4.2 building for production...
 transforming...
-✓ 2574 modules transformed.
+✓ 2715 modules transformed.
 rendering chunks...
 computing gzip size...
 dist/index.css    156.09 kB │ gzip:  20.37 kB
-dist/index.js   1,377.68 kB │ gzip: 352.31 kB
-✓ built in 5.19s
+dist/index.js   1,589.58 kB │ gzip: 401.03 kB
+✓ built in 5.83s
 [build:vite-build] Vite build completed.
- ---- build finished (73.056s) ---- 
--------------------- Finished (73.061s) --------------------
+ ---- build finished (39.698s) ---- 
+-------------------- Finished (39.701s) --------------------

package/rush-logs/web-components._phase_test.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: f2b8b611fc00c7b912256986db4cc966d6560387
+Cache key: 6bc9700f6b9938b330a84bd0f8c7ef5a7e3dbfb6
 Clearing cached folders: .rush/temp/operation/_phase_test
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_test.log

@@ -5,26 +5,28 @@ The provided list of phases does not contain all phase dependencies. You may nee
 
  RUN  v3.2.4 /home/runner/work/grackle/grackle/packages/web-components
 
- ✓ src/utils/sessionEvents.test.ts (14 tests) 55ms
  ✓ src/utils/eventContent.test.ts (38 tests) 103ms
- ✓ src/utils/dashboard.test.ts (4 tests) 25ms
- ✓ src/utils/route-config.test.ts (23 tests) 72ms
- ✓ src/utils/breadcrumbs.test.ts (18 tests) 24ms
- ✓ src/utils/scrollUtils.test.ts (11 tests) 24ms
- ✓ src/components/tools/classifyTool.test.ts (6 tests) 37ms
- ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 17ms
- ✓ src/components/display/extractText.test.tsx (8 tests) 12ms
- ✓ src/components/editable/useEditableField.test.tsx (17 tests) 181ms
- ✓ src/hooks/useEventSelection.test.ts (13 tests) 182ms
- ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 125ms
-
- Test Files  12 passed (12)
-      Tests  166 passed (166)
-   Start at  20:39:06
-   Duration  13.92s (transform 2.79s, setup 0ms, collect 15.06s, tests 856ms, environment 6.97s, prepare 5.20s)
+ ✓ src/utils/sessionEvents.test.ts (14 tests) 54ms
+ ✓ src/utils/dashboard.test.ts (4 tests) 28ms
+ ✓ src/utils/route-config.test.ts (23 tests) 45ms
+ ✓ src/utils/scrollUtils.test.ts (11 tests) 19ms
+ ✓ src/utils/breadcrumbs.test.ts (18 tests) 108ms
+ ✓ src/components/tools/classifyTool.test.ts (6 tests) 17ms
+ ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 21ms
+ ✓ src/components/display/extractText.test.tsx (8 tests) 6ms
+ ✓ src/components/editable/useEditableField.test.tsx (17 tests) 154ms
+ ✓ src/hooks/useEventSelection.test.ts (13 tests) 114ms
+ ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 73ms
+ ✓ src/components/display/McpAppWidget.test.tsx (3 tests) 251ms
+ ✓ src/utils/grackleHostStyleVariables.test.ts (2 tests) 229ms
+
+ Test Files  14 passed (14)
+      Tests  171 passed (171)
+   Start at  14:51:21
+   Duration  13.26s (transform 2.17s, setup 0ms, collect 16.02s, tests 1.22s, environment 8.39s, prepare 5.24s)
 
 [test:vitest] Vitest completed.
-[test:storybook-test] Starting Storybook static server on port 43017...
+[test:storybook-test] Starting Storybook static server on port 45689...
 [test:storybook-test] Storybook server ready. Running interaction tests...
 jest-haste-map: duplicate manual mock found: adapter-manager
   The following files share their name; please delete one of them:
@@ -101,21 +103,21 @@ jest-haste-map: duplicate manual mock found: token-push
     * <rootDir>/packages/server/dist/__mocks__/token-push.js
     * <rootDir>/packages/server/src/__mocks__/token-push.ts
 
-jest-haste-map: duplicate manual mock found: utils/exec
-  The following files share their name; please delete one of them:
-    * <rootDir>/packages/server/dist/__mocks__/utils/exec.js
-    * <rootDir>/packages/server/src/__mocks__/utils/exec.ts
-
 jest-haste-map: duplicate manual mock found: utils/format-gh-error
   The following files share their name; please delete one of them:
     * <rootDir>/packages/server/dist/__mocks__/utils/format-gh-error.js
     * <rootDir>/packages/server/src/__mocks__/utils/format-gh-error.ts
 
+jest-haste-map: duplicate manual mock found: utils/exec
+  The following files share their name; please delete one of them:
+    * <rootDir>/packages/server/dist/__mocks__/utils/exec.js
+    * <rootDir>/packages/server/src/__mocks__/utils/exec.ts
+
 jest-haste-map: duplicate manual mock found: utils/network
   The following files share their name; please delete one of them:
     * <rootDir>/packages/server/dist/__mocks__/utils/network.js
     * <rootDir>/packages/server/src/__mocks__/utils/network.ts
 
 [test:storybook-test] Storybook interaction tests completed.
- ---- test finished (112.648s) ---- 
--------------------- Finished (112.652s) --------------------
+ ---- test finished (68.057s) ---- 
+-------------------- Finished (68.063s) --------------------

package/src/components/display/McpAppWidget.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { McpAppWidget } from "./McpAppWidget.js";
+
+// The sandbox proxy MUST be served from a different origin than Storybook.
+// Run `npm run storybook:mcp` (Storybook + the sidecar CSP server) so this is up.
+const SANDBOX_ORIGIN: string = "http://localhost:6007";
+const SANDBOX_URL: string = SANDBOX_ORIGIN + "/sandbox.html";
+
+// A sample widget that loads the REAL @modelcontextprotocol/ext-apps `App` (the
+// dependency-inlined bundle served by serve.mjs) so the MCP Apps handshake is
+// fully spec-conformant. The widget logic lives in sample-widget.js; this is just
+// the DOM skeleton plus the module script tag. ASCII-only (the Storybook acorn
+// indexer breaks on non-ASCII in .stories.tsx).
+const SAMPLE_WIDGET_HTML: string = [
+  "<!doctype html><html><head><meta charset=\"utf-8\"><style>",
+  "body{margin:0;font-family:var(--font-sans,sans-serif);color:var(--color-text-primary,#111);",
+  "background:var(--color-background-secondary,#f5f5f5);padding:16px}",
+  ".card{background:var(--color-background-primary,#fff);border:1px solid var(--color-border-primary,#ddd);",
+  "border-radius:var(--border-radius-md,6px);padding:16px}",
+  "code{font-family:var(--font-mono,monospace)} button{margin-top:12px}",
+  "</style></head><body><div class=\"card\">",
+  "<h2 id=\"title\">Weather</h2>",
+  "<div>Input: <code id=\"in\">(none)</code></div>",
+  "<div>Result: <code id=\"out\">(pending)</code></div>",
+  "<button id=\"call\">Refresh</button></div>",
+  "<script type=\"module\" src=\"" + SANDBOX_ORIGIN + "/sample-widget.js\"></script>",
+  "</body></html>",
+].join("");
+
+const meta: Meta<typeof McpAppWidget> = {
+  title: "Grackle/Display/McpAppWidget",
+  component: McpAppWidget,
+  parameters: { layout: "padded" },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    widgetHtml: SAMPLE_WIDGET_HTML,
+    sandboxProxyUrl: SANDBOX_URL,
+    toolInput: { location: "Seattle" },
+    toolResult: { content: [{ type: "text", text: "72F and clear" }] },
+    onCallTool: fn(async () => ({ content: [{ type: "text", text: "refreshed: 70F" }] })),
+    onOpenLink: fn(),
+    onSendMessage: fn(),
+    onSizeChange: fn(),
+  },
+  // Sidecar-independent smoke check: the host iframe mounts. The full handshake
+  // (proxy ready -> initialize -> tool-input/result -> size-changed) is exercised
+  // visually via `npm run storybook:mcp` and the PR screenshot, since it requires
+  // the cross-origin sidecar which is not part of the headless test phase.
+  play: async ({ canvas }) => {
+    const iframe = await canvas.findByTestId("mcp-app-widget");
+    await expect(iframe).toBeInTheDocument();
+    await expect(iframe.tagName.toLowerCase()).toBe("iframe");
+  },
+};

package/src/components/display/McpAppWidget.test.tsx

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup, screen } from "@testing-library/react";
+import { McpAppWidget } from "./McpAppWidget.js";
+
+describe("McpAppWidget", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("mounts an iframe host for the widget", () => {
+    render(
+      <McpAppWidget
+        widgetHtml="<!doctype html><html><body>hi</body></html>"
+        sandboxProxyUrl="http://localhost:6007/sandbox.html"
+      />,
+    );
+    const iframe = screen.getByTestId("mcp-app-widget");
+    expect(iframe.tagName.toLowerCase()).toBe("iframe");
+  });
+
+  it("points the iframe at the sandbox proxy origin", () => {
+    render(
+      <McpAppWidget
+        widgetHtml="<!doctype html><html><body>hi</body></html>"
+        sandboxProxyUrl="http://localhost:6007/sandbox.html"
+      />,
+    );
+    const iframe = screen.getByTestId("mcp-app-widget") as HTMLIFrameElement;
+    expect(iframe.getAttribute("src") ?? "").toContain("localhost:6007");
+  });
+
+  it("fails fast when the sandbox proxy shares the host origin", () => {
+    // A same-origin proxy breaks the double-iframe isolation guarantee, so the
+    // component throws rather than silently rendering an insecure widget.
+    const sameOrigin = `${window.location.origin}/sandbox.html`;
+    expect(() =>
+      render(
+        <McpAppWidget
+          widgetHtml="<!doctype html><html><body>hi</body></html>"
+          sandboxProxyUrl={sameOrigin}
+        />,
+      ),
+    ).toThrow(/different origin/i);
+  });
+});