Add generated UI browser fallback

Author: RhysSullivan

apps/cli/src/main.ts

@@ -778,6 +778,11 @@ const runStdioMcpSession = (input: { readonly elicitationMode: "browser" | "mode
         runMcpStdioServer({
           executor: web.executor,
           codeExecutor: makeQuickJsExecutor(),
+          renderUiFallbackUrl: (code) => {
+            const url = new URL("/plugins/dynamic-ui/render", web.baseUrl);
+            url.hash = `code=${encodeURIComponent(code)}`;
+            return url.toString();
+          },
           elicitationMode:
             input.elicitationMode === "browser"
               ? {

apps/cloud/src/mcp-session.ts

@@ -371,6 +371,12 @@ export class McpSessionDO extends DurableObject {
         plugins,
         parentSpan: () => self.currentRequestSpan ?? undefined,
         debug: env.EXECUTOR_MCP_DEBUG === "true",
+        renderUiFallbackUrl: (code) => {
+          const origin = env.VITE_PUBLIC_SITE_URL ?? "https://executor.sh";
+          const url = new URL("/plugins/dynamic-ui/render", origin);
+          url.hash = `code=${encodeURIComponent(code)}`;
+          return url.toString();
+        },
         browserApprovalStore: {
           takeResponse: (executionId) => self.takeApprovalResponse(executionId),
           waitForResponse: (executionId) => self.waitForApprovalResponse(executionId),

apps/cloud/src/routeTree.gen.ts

@@ -23,6 +23,7 @@ import { Route as SourcesNamespaceRouteImport } from './routes/sources.$namespac
 import { Route as ResumeExecutionIdRouteImport } from './routes/resume.$executionId'
 import { Route as BillingPlansRouteImport } from './routes/billing_.plans'
 import { Route as SourcesAddPluginKeyRouteImport } from './routes/sources.add.$pluginKey'
+import { Route as PluginsPluginIdSplatRouteImport } from './routes/plugins.$pluginId.$'
 
 const ToolsRoute = ToolsRouteImport.update({
   id: '/tools',
@@ -94,6 +95,11 @@ const SourcesAddPluginKeyRoute = SourcesAddPluginKeyRouteImport.update({
   path: '/sources/add/$pluginKey',
   getParentRoute: () => rootRouteImport,
 } as any)
+const PluginsPluginIdSplatRoute = PluginsPluginIdSplatRouteImport.update({
+  id: '/plugins/$pluginId/$',
+  path: '/plugins/$pluginId/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
@@ -109,6 +115,7 @@ export interface FileRoutesByFullPath {
   '/billing/plans': typeof BillingPlansRoute
   '/resume/$executionId': typeof ResumeExecutionIdRoute
   '/sources/$namespace': typeof SourcesNamespaceRoute
+  '/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
   '/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
 }
 export interface FileRoutesByTo {
@@ -125,6 +132,7 @@ export interface FileRoutesByTo {
   '/billing/plans': typeof BillingPlansRoute
   '/resume/$executionId': typeof ResumeExecutionIdRoute
   '/sources/$namespace': typeof SourcesNamespaceRoute
+  '/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
   '/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
 }
 export interface FileRoutesById {
@@ -142,6 +150,7 @@ export interface FileRoutesById {
   '/billing_/plans': typeof BillingPlansRoute
   '/resume/$executionId': typeof ResumeExecutionIdRoute
   '/sources/$namespace': typeof SourcesNamespaceRoute
+  '/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
   '/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
 }
 export interface FileRouteTypes {
@@ -160,6 +169,7 @@ export interface FileRouteTypes {
     | '/billing/plans'
     | '/resume/$executionId'
     | '/sources/$namespace'
+    | '/plugins/$pluginId/$'
     | '/sources/add/$pluginKey'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -176,6 +186,7 @@ export interface FileRouteTypes {
     | '/billing/plans'
     | '/resume/$executionId'
     | '/sources/$namespace'
+    | '/plugins/$pluginId/$'
     | '/sources/add/$pluginKey'
   id:
     | '__root__'
@@ -192,6 +203,7 @@ export interface FileRouteTypes {
     | '/billing_/plans'
     | '/resume/$executionId'
     | '/sources/$namespace'
+    | '/plugins/$pluginId/$'
     | '/sources/add/$pluginKey'
   fileRoutesById: FileRoutesById
 }
@@ -209,6 +221,7 @@ export interface RootRouteChildren {
   BillingPlansRoute: typeof BillingPlansRoute
   ResumeExecutionIdRoute: typeof ResumeExecutionIdRoute
   SourcesNamespaceRoute: typeof SourcesNamespaceRoute
+  PluginsPluginIdSplatRoute: typeof PluginsPluginIdSplatRoute
   SourcesAddPluginKeyRoute: typeof SourcesAddPluginKeyRoute
 }
 
@@ -291,6 +304,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof SourcesNamespaceRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/plugins/$pluginId/$': {
+      id: '/plugins/$pluginId/$'
+      path: '/plugins/$pluginId/$'
+      fullPath: '/plugins/$pluginId/$'
+      preLoaderRoute: typeof PluginsPluginIdSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/resume/$executionId': {
       id: '/resume/$executionId'
       path: '/resume/$executionId'
@@ -329,6 +349,7 @@ const rootRouteChildren: RootRouteChildren = {
   BillingPlansRoute: BillingPlansRoute,
   ResumeExecutionIdRoute: ResumeExecutionIdRoute,
   SourcesNamespaceRoute: SourcesNamespaceRoute,
+  PluginsPluginIdSplatRoute: PluginsPluginIdSplatRoute,
   SourcesAddPluginKeyRoute: SourcesAddPluginKeyRoute,
 }
 export const routeTree = rootRouteImport

apps/cloud/src/routes/plugins.$pluginId.$.tsx

@@ -0,0 +1,27 @@
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import { useClientPlugins } from "@executor-js/sdk/client";
+
+export const Route = createFileRoute("/plugins/$pluginId/$")({
+  component: PluginRouteComponent,
+});
+
+function normalizePath(input: string): string {
+  if (!input || input === "/") return "/";
+  return input.startsWith("/") ? input : `/${input}`;
+}
+
+function PluginRouteComponent() {
+  const { pluginId, _splat: rest } = Route.useParams();
+  const plugins = useClientPlugins();
+  const plugin = plugins.find((p) => p.id === pluginId);
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: TanStack Router represents not-found from components by throwing notFound()
+  if (!plugin) throw notFound();
+
+  const target = normalizePath(rest ?? "/");
+  const page = plugin.pages?.find((p) => normalizePath(p.path) === target);
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: TanStack Router represents not-found from components by throwing notFound()
+  if (!page) throw notFound();
+
+  const Component = page.component;
+  return <Component />;
+}

apps/local/src/server/mcp.ts

@@ -59,6 +59,12 @@ const approvalUrlForRequest = (
   return url.toString();
 };
 
+const renderUiFallbackUrlForRequest = (request: Request, code: string): string => {
+  const url = new URL("/plugins/dynamic-ui/render", new URL(request.url).origin);
+  url.hash = `code=${encodeURIComponent(code)}`;
+  return url.toString();
+};
+
 const ignoreClose = (close: (() => Promise<void>) | undefined): Promise<void> =>
   close
     ? Effect.runPromise(
@@ -162,6 +168,8 @@ export const createMcpRequestHandler = (config: ExecutorMcpServerConfig): McpReq
         created = await Effect.runPromise(
           createExecutorMcpServer({
             ...config,
+            renderUiFallbackUrl:
+              config.renderUiFallbackUrl ?? ((code) => renderUiFallbackUrlForRequest(request, code)),
             browserApprovalStore: {
               takeResponse: (executionId) =>
                 Effect.sync(() => {

bun.lock

@@ -32,6 +32,8 @@ import type { ExecutorCliConfig } from "@executor-js/sdk";
 
 const VIRTUAL_ID = "virtual:executor/plugins-client";
 const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+const INNER_RENDERER_ID = "virtual:executor-inner-renderer";
+const RESOLVED_INNER_RENDERER_ID = `\0${INNER_RENDERER_ID}`;
 
 const DEFAULT_CONFIG_CANDIDATES = [
   "executor.config.ts",
@@ -65,6 +67,35 @@ const tryResolveClient = (packageName: string, fromDir: string): string | null =
   }
 };
 
+const tryResolveDynamicUiInnerRenderer = (fromDir: string): string | null => {
+  const require = createRequire(resolvePath(fromDir, "_anchor.js"));
+  try {
+    const clientEntry = require.resolve("@executor-js/plugin-dynamic-ui/client");
+    return resolvePath(dirname(clientEntry), "shell/inner-renderer.tsx");
+  } catch {
+    return null;
+  }
+};
+
+type EsbuildApi = {
+  readonly build: (options: {
+    readonly entryPoints: readonly string[];
+    readonly absWorkingDir: string;
+    readonly bundle: boolean;
+    readonly write: boolean;
+    readonly format: "iife";
+    readonly platform: "browser";
+    readonly target: "es2022";
+    readonly jsx: "automatic";
+    readonly define: Record<string, string>;
+  }) => Promise<{ readonly outputFiles: readonly { readonly text: string }[] }>;
+};
+
+const loadEsbuild = (anchor: string): EsbuildApi => {
+  const require = createRequire(anchor);
+  return require("esbuild") as EsbuildApi;
+};
+
 interface ExecutorVitePluginOptions {
   /**
    * Path to the executor config file. Resolved relative to the Vite
@@ -218,10 +249,39 @@ export default function executorVitePlugin(options: ExecutorVitePluginOptions =
       projectRoot = config.root;
     },
     resolveId(id) {
+      if (id === INNER_RENDERER_ID) return RESOLVED_INNER_RENDERER_ID;
       if (id === VIRTUAL_ID) return RESOLVED_ID;
       return undefined;
     },
     async load(id) {
+      if (id === RESOLVED_INNER_RENDERER_ID) {
+        const configPath = resolveConfigPath();
+        const fromDir = configPath ? dirname(configPath) : projectRoot;
+        const entryPoint = tryResolveDynamicUiInnerRenderer(fromDir);
+        if (!entryPoint) {
+          throw new Error(
+            "virtual:executor-inner-renderer was requested but @executor-js/plugin-dynamic-ui could not be resolved.",
+          );
+        }
+
+        const result = await loadEsbuild(entryPoint).build({
+          entryPoints: [entryPoint],
+          absWorkingDir: dirname(entryPoint),
+          bundle: true,
+          write: false,
+          format: "iife",
+          platform: "browser",
+          target: "es2022",
+          jsx: "automatic",
+          define: {
+            "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV ?? "development"),
+          },
+        });
+
+        const js = result.outputFiles[0];
+        if (!js) throw new Error("Failed to bundle Executor inner renderer.");
+        return `export default ${JSON.stringify(js.text)};`;
+      }
       if (id !== RESOLVED_ID) return undefined;
       return loadVirtualSource();
     },

packages/core/vite-plugin/src/index.ts

@@ -25,6 +25,7 @@ export type McpPluginRegisterContext<E extends Cause.YieldableError = Cause.Yiel
   readonly debugLog: McpDebugLog;
   readonly runToolEffect: McpRunToolEffect;
   readonly executeCodeFromApp: (code: string) => Effect.Effect<McpToolResult, E>;
+  readonly renderUiFallbackUrl?: (code: string) => string;
   readonly resumeExecution: (
     executionId: string,
     action: "accept" | "decline" | "cancel",

packages/hosts/mcp/src/plugin.ts

@@ -45,7 +45,7 @@ const withClient = async <E extends Cause.YieldableError>(
   fn: (client: Client) => Promise<void>,
   config?: Pick<
     ExecutorMcpServerConfig<E>,
-    "debug" | "elicitationMode" | "browserApprovalStore" | "plugins"
+    "debug" | "elicitationMode" | "browserApprovalStore" | "plugins" | "renderUiFallbackUrl"
   >,
 ) => {
   const mcpServer = await Effect.runPromise(createExecutorMcpServer({ engine, ...config }));
@@ -169,18 +169,31 @@ describe("MCP host server — native elicitation mode", () => {
     });
   });
 
-  it("does not expose dynamic UI app tools to clients without MCP Apps support", async () => {
+  it("exposes render-ui fallback but not app-only tools to clients without MCP Apps support", async () => {
     await withClient(
       makeStubEngine({}),
       NO_CAPS,
       async (client) => {
         const { tools } = await client.listTools();
         const names = tools.map((tool) => tool.name);
-        expect(names).not.toContain("render-ui");
+        expect(names).toContain("render-ui");
         expect(names).not.toContain("execute-action");
         expect(names).not.toContain("execute-action-resume");
+
+        const result = await client.callTool({
+          name: "render-ui",
+          arguments: { code: 'function App() { return <Card className="p-4" />; }' },
+        });
+        expect(textOf(result)).toContain("https://executor.test/render?code=42");
+        expect(result.structuredContent).toEqual({
+          status: "fallback_url",
+          url: "https://executor.test/render?code=42",
+        });
+      },
+      {
+        plugins: [DYNAMIC_UI_PLUGIN],
+        renderUiFallbackUrl: () => "https://executor.test/render?code=42",
       },
-      { plugins: [DYNAMIC_UI_PLUGIN] },
     );
   });
 

packages/hosts/mcp/src/server.test.ts

@@ -90,6 +90,11 @@ type SharedMcpServerConfig = {
         readonly mode: "native";
       };
   readonly browserApprovalStore?: BrowserApprovalStore;
+  /**
+   * Browser URL used by generative UI MCP contributions when the connected
+   * client cannot mount MCP Apps resources directly.
+   */
+  readonly renderUiFallbackUrl?: (code: string) => string;
   /**
    * Executor plugins whose host-protocol MCP contributions should be mounted.
    * Core SDK treats the field as opaque; this host interprets `plugin.mcp`.
@@ -672,6 +677,7 @@ export const createExecutorMcpServer = <E extends Cause.YieldableError>(
             debugLog,
             runToolEffect,
             executeCodeFromApp,
+            renderUiFallbackUrl: config.renderUiFallbackUrl,
             resumeExecution,
             parseJsonContent,
           })