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,410 @@
import { createRef } from "react";
import { act } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import type { AppBridge } from "@modelcontextprotocol/ext-apps/app-bridge";
import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
import { renderWithMantine, screen } from "../../../test/renderWithMantine";
import {
AppRenderer,
type AppRendererHandle,
type BridgeFactory,
} from "./AppRenderer";
const tool: Tool = {
name: "cohort_app",
title: "Cohort App",
inputSchema: { type: "object" },
};
interface MockBridge {
sendToolInput: ReturnType<typeof vi.fn>;
sendToolResult: ReturnType<typeof vi.fn>;
sendToolCancelled: ReturnType<typeof vi.fn>;
teardownResource: ReturnType<typeof vi.fn>;
close: ReturnType<typeof vi.fn>;
}
function createMockBridge(): MockBridge {
return {
sendToolInput: vi.fn().mockResolvedValue(undefined),
sendToolResult: vi.fn().mockResolvedValue(undefined),
sendToolCancelled: vi.fn().mockResolvedValue(undefined),
teardownResource: vi.fn().mockResolvedValue({}),
close: vi.fn().mockResolvedValue(undefined),
};
}
function asBridge(mock: MockBridge): AppBridge {
return mock as unknown as AppBridge;
}
// Two microtask ticks are enough to settle the bridge promise chain in the
// component when the factory is synchronous: tick 1 resolves
// `Promise.resolve(bridgeFactory(iframe))`, tick 2 runs the `.then` that
// assigns `bridgeRef.current`. Tests using a multi-hop async factory must
// flush further inline (see the post-unmount disposal cases).
async function flushAsync(): Promise<void> {
await act(async () => {
await Promise.resolve();
await Promise.resolve();
});
}
describe("AppRenderer", () => {
it("renders an iframe with the sandbox path and tool title", () => {
const bridge = createMockBridge();
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
const iframe = screen.getByTitle("Cohort App") as HTMLIFrameElement;
expect(iframe.tagName).toBe("IFRAME");
expect(iframe.getAttribute("src")).toBe("/sandbox.html");
});
it("falls back to tool name when title is missing", () => {
const bridge = createMockBridge();
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={{ name: "no_title", inputSchema: { type: "object" } }}
bridgeFactory={() => asBridge(bridge)}
/>,
);
expect(screen.getByTitle("no_title")).toBeInTheDocument();
});
it("invokes the bridge factory with the iframe element", async () => {
const bridge = createMockBridge();
const factory = vi.fn<BridgeFactory>(() => asBridge(bridge));
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
/>,
);
await flushAsync();
expect(factory).toHaveBeenCalledTimes(1);
expect(factory.mock.calls[0]?.[0]).toBeInstanceOf(HTMLIFrameElement);
});
it("forwards sendToolInput through the bridge", async () => {
const bridge = createMockBridge();
const ref = createRef<AppRendererHandle>();
renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
await ref.current?.sendToolInput({ city: "NYC" });
});
expect(bridge.sendToolInput).toHaveBeenCalledWith({
arguments: { city: "NYC" },
});
});
it("forwards sendToolResult through the bridge", async () => {
const bridge = createMockBridge();
const ref = createRef<AppRendererHandle>();
const result: CallToolResult = {
content: [{ type: "text", text: "ok" }],
};
renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
await ref.current?.sendToolResult(result);
});
expect(bridge.sendToolResult).toHaveBeenCalledWith(result);
});
it("forwards sendToolCancelled through the bridge", async () => {
const bridge = createMockBridge();
const ref = createRef<AppRendererHandle>();
renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
await ref.current?.sendToolCancelled("user-aborted");
});
expect(bridge.sendToolCancelled).toHaveBeenCalledWith({
reason: "user-aborted",
});
});
it("teardown disposes the bridge once and is idempotent", async () => {
const bridge = createMockBridge();
const ref = createRef<AppRendererHandle>();
renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
await ref.current?.teardown();
await ref.current?.teardown();
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
it("does not double-dispose when unmount races an in-flight teardown", async () => {
const bridge = createMockBridge();
let resolveTeardown: ((value: Record<string, unknown>) => void) | undefined;
bridge.teardownResource.mockImplementationOnce(
() =>
new Promise<Record<string, unknown>>((resolve) => {
resolveTeardown = resolve;
}),
);
const ref = createRef<AppRendererHandle>();
const { unmount } = renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
// Kick off teardown but leave its `teardownResource` await pending.
const teardownPromise = ref.current!.teardown();
// Unmount while teardown is in flight.
unmount();
// Resolve the pending teardownResource, then let `close` settle.
await act(async () => {
resolveTeardown?.({});
await teardownPromise;
for (let i = 0; i < 4; i++) {
await Promise.resolve();
}
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
it("send methods are silent no-ops before the bridge resolves", async () => {
const bridge = createMockBridge();
let resolveBridge: ((b: AppBridge) => void) | undefined;
const factory: BridgeFactory = () =>
new Promise<AppBridge>((resolve) => {
resolveBridge = resolve;
});
const ref = createRef<AppRendererHandle>();
renderWithMantine(
<AppRenderer
ref={ref}
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
/>,
);
await act(async () => {
await ref.current?.sendToolInput({ city: "NYC" });
await ref.current?.sendToolResult({ content: [] });
await ref.current?.sendToolCancelled("aborted");
await ref.current?.teardown();
});
expect(bridge.sendToolInput).not.toHaveBeenCalled();
expect(bridge.sendToolResult).not.toHaveBeenCalled();
expect(bridge.sendToolCancelled).not.toHaveBeenCalled();
expect(bridge.teardownResource).not.toHaveBeenCalled();
// Resolve to satisfy the pending factory before unmount.
resolveBridge?.(asBridge(bridge));
await flushAsync();
});
it("unmount triggers teardownResource and close", async () => {
const bridge = createMockBridge();
const { unmount } = renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
unmount();
await Promise.resolve();
await Promise.resolve();
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
it("disposes a bridge that resolves after the component unmounts", async () => {
const bridge = createMockBridge();
let resolveBridge: ((b: AppBridge) => void) | undefined;
const factory: BridgeFactory = () =>
new Promise<AppBridge>((resolve) => {
resolveBridge = resolve;
});
const { unmount } = renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
/>,
);
unmount();
await act(async () => {
resolveBridge?.(asBridge(bridge));
// disposeBridge awaits teardownResource then close — flush enough
// microtasks to let both calls complete.
for (let i = 0; i < 8; i++) {
await Promise.resolve();
}
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
it("calls onError when the bridge factory throws", async () => {
const onError = vi.fn();
const factory: BridgeFactory = () => {
throw new Error("boom");
};
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
onError={onError}
/>,
);
await flushAsync();
expect(onError).toHaveBeenCalledTimes(1);
expect(onError.mock.calls[0]?.[0]).toBeInstanceOf(Error);
expect((onError.mock.calls[0]?.[0] as Error).message).toBe("boom");
});
it("wraps non-Error rejections from the factory", async () => {
const onError = vi.fn();
const factory: BridgeFactory = () => Promise.reject("plain string");
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
onError={onError}
/>,
);
await flushAsync();
expect(onError).toHaveBeenCalledTimes(1);
expect((onError.mock.calls[0]?.[0] as Error).message).toBe("plain string");
});
it("does not throw when no onError is provided and the factory fails", async () => {
const factory: BridgeFactory = () => Promise.reject(new Error("ignored"));
renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={factory}
/>,
);
await flushAsync();
expect(screen.getByTitle("Cohort App")).toBeInTheDocument();
});
it("rebuilds the bridge when sandboxPath changes", async () => {
const first = createMockBridge();
const second = createMockBridge();
const factory = vi
.fn<BridgeFactory>()
.mockReturnValueOnce(asBridge(first))
.mockReturnValueOnce(asBridge(second));
const { rerender } = renderWithMantine(
<AppRenderer
sandboxPath="/sandbox-a.html"
tool={tool}
bridgeFactory={factory}
/>,
);
await flushAsync();
rerender(
<AppRenderer
sandboxPath="/sandbox-b.html"
tool={tool}
bridgeFactory={factory}
/>,
);
await flushAsync();
expect(factory).toHaveBeenCalledTimes(2);
expect(first.teardownResource).toHaveBeenCalledTimes(1);
expect(first.close).toHaveBeenCalledTimes(1);
});
it("swallows teardownResource errors but still closes the transport", async () => {
const bridge = createMockBridge();
bridge.teardownResource.mockRejectedValueOnce(new Error("teardown failed"));
const { unmount } = renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
unmount();
await Promise.resolve();
await Promise.resolve();
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
it("swallows close errors during disposal", async () => {
const bridge = createMockBridge();
bridge.close.mockRejectedValueOnce(new Error("close failed"));
const { unmount } = renderWithMantine(
<AppRenderer
sandboxPath="/sandbox.html"
tool={tool}
bridgeFactory={() => asBridge(bridge)}
/>,
);
await flushAsync();
await act(async () => {
unmount();
await Promise.resolve();
await Promise.resolve();
});
expect(bridge.teardownResource).toHaveBeenCalledTimes(1);
expect(bridge.close).toHaveBeenCalledTimes(1);
});
});