feat(apps): AppRenderer with imperative ref (#1262) (#1282)

* feat(apps): add AppRenderer element with imperative ref (#1262)

Introduces a thin host-side shell for embedded MCP Apps. The renderer
owns the iframe element and the AppBridge lifecycle; the wiring layer
constructs the bridge from the active MCP Client via bridgeFactory and
drives input/result/cancellation through the imperative ref handle.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: address PR feedback on AppRenderer

- Document BridgeFactory stability requirement (unstable identity thrashes
  the iframe on every render).
- Null bridgeRef synchronously inside teardown() before awaiting disposal,
  so a concurrent unmount cleanup cannot dispose the same bridge twice.
- Comment the iframe trust model: the outer frame loads the inspector's
  trusted same-origin sandbox-proxy, which sandboxes the actual app
  content. Adding `sandbox` to this frame would block the postMessage
  bridge.
- Rename `Error` story export to `BridgeError` to avoid shadowing the
  global Error constructor; drop the `globalThis.Error` workaround.
- Comment flushAsync to explain the two-tick microtask budget.
- Add unmount-while-tearing-down test to lock in the no-double-dispose
  guarantee.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cliff Hall 2026-05-05 09:56:48 -04:00 • committed by GitHub
commit 323f42d11c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -0,0 +1,112 @@
import type { Meta, StoryObj } from "@storybook/react-vite";
import { Box } from "@mantine/core";
import type { ReactNode } from "react";
import type { AppBridge } from "@modelcontextprotocol/ext-apps/app-bridge";
import type { Tool } from "@modelcontextprotocol/sdk/types.js";
import { fn } from "storybook/test";
import { AppRenderer, type BridgeFactory } from "./AppRenderer";
const PLACEHOLDER_SANDBOX = "data:text/html,<title>Mock%20Sandbox</title>";
const cohortTool: Tool = {
name: "get-cohort-data",
title: "Cohort Data",
description: "Returns cohort retention heatmap data.",
inputSchema: { type: "object" },
};
function createMockBridge(): AppBridge {
return {
sendToolInput: async () => {},
sendToolResult: async () => {},
sendToolCancelled: async () => {},
teardownResource: async () => ({}),
close: async () => {},
} as unknown as AppBridge;
}
const okFactory: BridgeFactory = () => createMockBridge();
const pendingFactory: BridgeFactory = () =>
new Promise<AppBridge>(() => {
// Never resolves — represents the period before the bridge is ready.
});
const failingFactory: BridgeFactory = () =>
Promise.reject(new Error("Bridge connect failed: handshake timed out"));
function FrameContainer({
children,
size,
}: {
children: ReactNode;
size: "default" | "maximized";
}) {
const dims =
size === "maximized" ? { w: "100%", h: 600 } : { w: 480, h: 320 };
return (
<Box {...dims} bd="1px solid var(--mantine-color-gray-4)">
{children}
</Box>
);
}
const meta: Meta<typeof AppRenderer> = {
title: "Elements/AppRenderer",
component: AppRenderer,
args: {
sandboxPath: PLACEHOLDER_SANDBOX,
tool: cohortTool,
onError: fn(),
},
parameters: {
layout: "centered",
},
};
export default meta;
type Story = StoryObj<typeof AppRenderer>;
export const Loading: Story = {
args: {
bridgeFactory: pendingFactory,
},
render: (args) => (
<FrameContainer size="default">
<AppRenderer {...args} />
</FrameContainer>
),
};
export const Loaded: Story = {
args: {
bridgeFactory: okFactory,
},
render: (args) => (
<FrameContainer size="default">
<AppRenderer {...args} />
</FrameContainer>
),
};
export const BridgeError: Story = {
args: {
bridgeFactory: failingFactory,
},
render: (args) => (
<FrameContainer size="default">
<AppRenderer {...args} />
</FrameContainer>
),
};
export const Maximized: Story = {
args: {
bridgeFactory: okFactory,
},
render: (args) => (
<FrameContainer size="maximized">
<AppRenderer {...args} />
</FrameContainer>
),
};