@womp/mcp-ui 0.1.0

package/src/shared/bridge.ts

@@ -0,0 +1,165 @@
+import {
+  App,
+  PostMessageTransport,
+  applyDocumentTheme,
+  applyHostStyleVariables,
+} from "@modelcontextprotocol/ext-apps";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * Shared host-bridge plumbing for every Womp card.
+ *
+ * Lives in one place because the handshake is subtle and duplicating it across
+ * cards is how the two would drift. Three facts it encodes, all learned the
+ * hard way:
+ *
+ *  1. The host mounts the iframe HIDDEN (`visibility: hidden; height: 100px`)
+ *     and reveals it only after `ui/initialize` -> `ui/notifications/initialized`
+ *     plus a size report. `app.connect()` does all of that including
+ *     auto-resize. Skip it and the card renders perfectly, invisibly.
+ *
+ *  2. Handlers must be attached BEFORE `connect()` or they never fire.
+ *
+ *  3. Host theme values are NOT CSS custom properties on the document — they
+ *     arrive over the bridge and the app applies them itself. Every `var()` in
+ *     the cards therefore ships a fallback.
+ */
+
+/** Shape returned by swan-backend's GENERATION_OUTPUT_SCHEMA (api/mcp.ts). */
+export interface GenerationResult {
+  status?: "complete" | "running";
+  generationId?: number;
+  operationId?: number;
+  imageUrl?: string;
+  glbUrl?: string;
+  previewUrl?: string;
+}
+
+export const $ = (id: string) => document.getElementById(id) as HTMLElement;
+
+/** Poll cadence: quick at first, then back off. Generations run 20-60s+. */
+const POLL_START_MS = 2_000;
+const POLL_MAX_MS = 10_000;
+/** Give up eventually rather than spin forever in a hidden iframe. */
+const POLL_CEILING_MS = 6 * 60 * 1000;
+
+export interface CardHooks {
+  /** Called with every result, running or complete. */
+  onResult: (data: GenerationResult) => void;
+  /** Called when a poll gives up. */
+  onTimeout?: () => void;
+}
+
+export interface Card {
+  app: App;
+  /** Latest result rendered — what action buttons operate on. */
+  current: () => GenerationResult | undefined;
+}
+
+/**
+ * Wire a card to the host: connect, route results, and self-update while a
+ * generation is still running.
+ *
+ * The running state polls `get_generation` through the host, which is allowed
+ * because `CallToolRequest` is part of `AppRequest`. That is what lets the tool
+ * return immediately instead of blocking the conversation, and it is why the
+ * tool must declare `visibility: ["model", "app"]` — without "app" the host
+ * refuses the call and the card waits forever.
+ */
+export function createCard(name: string, hooks: CardHooks): Card {
+  let pollTimer: number | undefined;
+  let pollStarted = 0;
+  let current: GenerationResult | undefined;
+
+  const stopPolling = () => {
+    if (pollTimer !== undefined) {
+      clearTimeout(pollTimer);
+      pollTimer = undefined;
+    }
+  };
+
+  const app = new App({ name, version: "0.0.1" }, {});
+
+  const fetchGeneration = async (operationId: number) => {
+    const res = await app.request(
+      { method: "tools/call", params: { name: "get_generation", arguments: { operationId } } },
+      CallToolResultSchema,
+    );
+    if (res.isError) return undefined;
+    return res.structuredContent as GenerationResult | undefined;
+  };
+
+  const poll = (operationId: number, delay: number) => {
+    pollTimer = window.setTimeout(async () => {
+      if (Date.now() - pollStarted > POLL_CEILING_MS) {
+        hooks.onTimeout?.();
+        return;
+      }
+      try {
+        const data = await fetchGeneration(operationId);
+        if (data?.status === "complete") {
+          stopPolling();
+          current = data;
+          hooks.onResult(data);
+          return;
+        }
+      } catch {
+        // A failed poll is not a failed generation. The ceiling above is what
+        // stops this eventually.
+      }
+      poll(operationId, Math.min(delay * 1.5, POLL_MAX_MS));
+    }, delay);
+  };
+
+  const handle = (data: GenerationResult | undefined) => {
+    if (!data) return;
+    stopPolling();
+    current = data;
+    hooks.onResult(data);
+    if (data.status === "running" && data.operationId !== undefined) {
+      pollStarted = Date.now();
+      poll(data.operationId, POLL_START_MS);
+    }
+  };
+
+  // Before connect(), always.
+  app.ontoolinput = () => hooks.onResult({ status: "running" });
+  app.ontoolresult = (params) => handle(params?.structuredContent as GenerationResult);
+  app.onhostcontextchanged = (ctx) => {
+    if (ctx?.theme) applyDocumentTheme(ctx.theme);
+    if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
+    // Cards are capped narrow inline so they do not wall off the transcript;
+    // fullscreen has to undo that or Expand looks broken.
+    if (ctx?.displayMode) document.documentElement.dataset.displayMode = ctx.displayMode;
+    if (ctx?.safeAreaInsets) {
+      const { top = 0, right = 0, bottom = 0, left = 0 } = ctx.safeAreaInsets;
+      document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
+    }
+  };
+  // Otherwise a closed chat leaves timers — and a WebGL context — running in a
+  // hidden iframe.
+  app.onteardown = async () => {
+    stopPolling();
+    return {};
+  };
+
+  app.connect(new PostMessageTransport(window.parent, window.parent)).catch(() => {
+    // Nothing to show if this fails: the host never reveals an unconnected
+    // frame, so the card is invisible regardless.
+  });
+
+  return { app, current: () => current };
+}
+
+/** Ask the host to open a URL; anchors cannot navigate out of the sandbox. */
+export function openLink(app: App, url: string) {
+  return app.openLink({ url });
+}
+
+/** Toggle fullscreen, trusting the host's answer over our request. */
+export function toggleFullscreen(app: App) {
+  const isFull = document.documentElement.dataset.displayMode === "fullscreen";
+  return app.requestDisplayMode({ mode: isFull ? "inline" : "fullscreen" }).then((res) => {
+    if (res?.mode) document.documentElement.dataset.displayMode = res.mode;
+  });
+}