@aprovan/mcp-app-server 0.1.0-dev.4d82df8

package/e2e/global-setup.ts

@@ -0,0 +1,114 @@
+/**
+ * Playwright global setup for visual regression tests.
+ *
+ * Responsibilities:
+ * 1. Save the live-dashboard reference widget's RAW source files to an isolated
+ *    widget store (no server-side compilation).
+ * 2. Start an in-process Express widget server on WIDGET_PORT (default 3002) that
+ *    serves the shared browser runtime (dist/runtime) plus each widget's raw
+ *    files at /widget/:name/:hash/files.
+ * 3. Write a test-fixtures.json file so tests can discover widget runtime URLs.
+ *
+ * Compilation now happens in the browser via @aprovan/patchwork-compiler — the
+ * same path the chat app uses — so the React UMD injection hack is gone. The
+ * widget's React is preloaded from the CDN by the image at mount time.
+ *
+ * NOTE: dist/runtime must be built first (`pnpm build:runtime`); the e2e:visual
+ * script does this before invoking Playwright.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import cors from "cors";
+import express from "express";
+import {
+  REFERENCE_WIDGET_FILES,
+  REFERENCE_WIDGET_MANIFEST,
+} from "../src/reference-widgets/live-dashboard.js";
+import { WidgetStore } from "../src/widget-store/store.js";
+
+const WIDGET_PORT = Number(process.env["WIDGET_PORT"] ?? 3002);
+const ARTIFACTS_DIR = join(process.cwd(), ".artifacts");
+const STORE_DIR = join(ARTIFACTS_DIR, "widget-store-e2e");
+const FIXTURES_PATH = join(ARTIFACTS_DIR, "test-fixtures.json");
+const SCREENSHOTS_DIR = join(ARTIFACTS_DIR, "screenshots");
+
+const RUNTIME_DIR = fileURLToPath(new URL("../dist/runtime", import.meta.url));
+
+export interface WidgetFixture {
+  name: string;
+  hash: string;
+  url: string;
+}
+
+export interface TestFixtures {
+  widgets: Record<string, WidgetFixture>;
+  serverPort: number;
+}
+
+let _server: Server | null = null;
+
+export default async function globalSetup(): Promise<void> {
+  await mkdir(ARTIFACTS_DIR, { recursive: true });
+  await mkdir(SCREENSHOTS_DIR, { recursive: true });
+  await mkdir(STORE_DIR, { recursive: true });
+
+  if (!existsSync(RUNTIME_DIR)) {
+    throw new Error(
+      `Runtime bundle not found at ${RUNTIME_DIR}. Run \`pnpm build:runtime\` before e2e tests.`,
+    );
+  }
+
+  // Use an isolated store for E2E tests to avoid polluting the default store
+  const store = new WidgetStore({ storageDir: STORE_DIR });
+
+  // Save the live-dashboard reference widget as RAW source files
+  const hash = "e2e-live-dashboard";
+  await store.saveWidget(hash, REFERENCE_WIDGET_FILES, REFERENCE_WIDGET_MANIFEST, "main.tsx");
+
+  const baseUrl = `http://localhost:${WIDGET_PORT}`;
+  const fixtures: TestFixtures = {
+    widgets: {
+      "live-dashboard": {
+        name: REFERENCE_WIDGET_MANIFEST.name,
+        hash,
+        url: `${baseUrl}/runtime/?widget=${REFERENCE_WIDGET_MANIFEST.name}/${hash}`,
+      },
+    },
+    serverPort: WIDGET_PORT,
+  };
+
+  await writeFile(FIXTURES_PATH, JSON.stringify(fixtures, null, 2), "utf-8");
+
+  // Start the Express widget server: shared runtime + raw widget files
+  const app = express();
+  app.use(cors());
+  app.use("/runtime", express.static(RUNTIME_DIR));
+
+  app.get("/widget/:name/:hash/files", async (req, res) => {
+    const { name, hash: h } = req.params;
+    const widget = await store.getWidget(name, h);
+    if (!widget) {
+      res.status(404).json({ error: "Widget not found" });
+      return;
+    }
+    res.json({ files: widget.files, entry: widget.entry, manifest: widget.manifest });
+  });
+
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok" });
+  });
+
+  await new Promise<void>((resolve) => {
+    _server = createServer(app).listen(WIDGET_PORT, "127.0.0.1", () => {
+      resolve();
+    });
+  });
+
+  // Expose the server reference for global teardown via the module cache.
+  // Playwright runs globalSetup and globalTeardown in the same Node.js process.
+  (globalThis as Record<string, unknown>).__e2eWidgetServer = _server;
+}

package/e2e/global-teardown.ts

@@ -0,0 +1,15 @@
+/**
+ * Playwright global teardown — shuts down the in-process widget server started
+ * by global-setup.ts.
+ */
+
+import type { Server } from "node:http";
+
+export default async function globalTeardown(): Promise<void> {
+  const server = (globalThis as Record<string, unknown>).__e2eWidgetServer as
+    | Server
+    | undefined;
+  if (server) {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}

package/e2e/visual-regression.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Visual regression tests for Patchwork reference widgets.
+ *
+ * Each test:
+ * 1. Reads the widget runtime URL from test-fixtures.json (written by global-setup)
+ * 2. Navigates to the shared runtime host (/runtime/?widget=name/hash)
+ *    - The runtime fetches the widget's raw source and compiles + mounts it in
+ *      the browser via @aprovan/patchwork-compiler (esbuild-wasm + esm.sh)
+ * 3. Waits for the widget to mount (#root > *) and CDN resources to settle
+ * 4. Captures a full-page screenshot saved to .artifacts/screenshots/<widget-name>.png
+ * 5. Runs toHaveScreenshot() for visual regression baseline comparison
+ */
+
+import { readFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { test, expect } from "@playwright/test";
+import type { TestFixtures } from "./global-setup.js";
+
+const ARTIFACTS_DIR = join(process.cwd(), ".artifacts");
+const FIXTURES_PATH = join(ARTIFACTS_DIR, "test-fixtures.json");
+const SCREENSHOTS_DIR = join(ARTIFACTS_DIR, "screenshots");
+
+async function loadFixtures(): Promise<TestFixtures> {
+  const raw = await readFile(FIXTURES_PATH, "utf-8");
+  return JSON.parse(raw) as TestFixtures;
+}
+
+test.describe("Widget visual regression", () => {
+  test("live-dashboard renders with Tailwind styles applied", async ({ page }) => {
+    const fixtures = await loadFixtures();
+    const widget = fixtures.widgets["live-dashboard"];
+    if (!widget) throw new Error("live-dashboard fixture not found — check global-setup");
+
+    // Inject a minimal window.patchwork stub before any page scripts run.
+    // The live-dashboard widget calls window.patchwork.subscribe() in a
+    // useEffect. In the test environment there is no MCP host, so the
+    // patchwork shim cannot connect and window.patchwork is never initialised.
+    // Without the stub React unmounts the tree on the thrown TypeError and
+    // #root stays empty.
+    await page.addInitScript(() => {
+      (window as unknown as Record<string, unknown>)["patchwork"] = {
+        subscribe: (_stream: string, _cb: unknown) => () => {},
+        fireEvent: () => {},
+        updateContext: () => {},
+      };
+    });
+
+    // Collect console errors for debugging on failure
+    const consoleErrors: string[] = [];
+    page.on("console", (msg) => {
+      if (msg.type() === "error") consoleErrors.push(msg.text());
+    });
+    page.on("pageerror", (err) => consoleErrors.push(err.message));
+
+    // Navigate to the shared runtime host, which compiles the widget in-browser
+    await page.goto(widget.url, { waitUntil: "domcontentloaded" });
+
+    // Wait for the widget to mount into #root (cold esbuild-wasm + CDN can be slow)
+    await page.waitForSelector("#root > *", {
+      timeout: 90_000,
+      state: "attached",
+    });
+
+    // Wait for CDN network activity (Tailwind, any remaining esm.sh calls) to settle
+    await page.waitForLoadState("networkidle", { timeout: 60_000 });
+
+    if (consoleErrors.length > 0) {
+      console.warn("Browser console errors during test:", consoleErrors);
+    }
+
+    // Verify the widget rendered its expected initial empty-state content
+    await expect(page.locator("text=Waiting for live data")).toBeVisible();
+    await expect(page.locator("text=Live Data Dashboard")).toBeVisible();
+
+    // Capture a named screenshot to .artifacts/screenshots/ for artifact upload
+    await mkdir(SCREENSHOTS_DIR, { recursive: true });
+    const screenshotPath = join(SCREENSHOTS_DIR, "live-dashboard.png");
+    await page.screenshot({ path: screenshotPath, fullPage: true });
+
+    // Visual regression baseline — created on first run, diffed on subsequent runs
+    await expect(page).toHaveScreenshot("live-dashboard.png", {
+      fullPage: true,
+      maxDiffPixelRatio: 0.02,
+    });
+  });
+});

package/e2e/widget-smoke.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Widget visual smoke test.
+ *
+ * Saves a minimal widget's RAW source to an isolated store, serves the shared
+ * browser runtime + raw files over HTTP, then drives a headless Chromium browser
+ * to verify the runtime compiles and mounts the widget in-browser.
+ *
+ * This exercises the same path as production: no server-side compilation — the
+ * runtime fetches raw files and compiles them with @aprovan/patchwork-compiler.
+ *
+ * NOTE: dist/runtime must be built first (`pnpm build:runtime`).
+ */
+
+import { test, expect } from "@playwright/test";
+import { createServer, type Server } from "node:http";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import cors from "cors";
+import express from "express";
+import { WidgetStore } from "../src/widget-store/store.js";
+import type { Manifest, VirtualFile } from "@aprovan/patchwork-compiler";
+
+const RUNTIME_DIR = fileURLToPath(new URL("../dist/runtime", import.meta.url));
+
+const SIMPLE_WIDGET_FILES: VirtualFile[] = [
+  {
+    path: "main.tsx",
+    content: `
+export default function Widget() {
+  return (
+    <div
+      id="widget-content"
+      style={{ padding: "1.5rem", background: "#dbeafe", borderRadius: "8px" }}
+    >
+      <h1 style={{ margin: 0, fontSize: "1.25rem" }}>Hello from Patchwork</h1>
+      <p style={{ margin: "0.5rem 0 0" }}>Widget rendered successfully.</p>
+    </div>
+  );
+}
+`,
+  },
+];
+
+const TEST_MANIFEST: Manifest = {
+  name: "smoke-test",
+  version: "0.1.0",
+  platform: "browser",
+  image: "@aprovan/patchwork-image-shadcn",
+};
+
+test.describe("widget smoke", () => {
+  let httpServer: Server;
+  let widgetUrl: string;
+
+  test.beforeAll(async () => {
+    await mkdir(".artifacts/screenshots", { recursive: true });
+
+    if (!existsSync(RUNTIME_DIR)) {
+      throw new Error(`Runtime bundle missing at ${RUNTIME_DIR}. Run \`pnpm build:runtime\`.`);
+    }
+
+    const storeDir = await mkdtemp(join(tmpdir(), "pw-smoke-"));
+    const store = new WidgetStore({ storageDir: storeDir });
+    const hash = "smoke";
+    await store.saveWidget(hash, SIMPLE_WIDGET_FILES, TEST_MANIFEST, "main.tsx");
+
+    const app = express();
+    app.use(cors());
+    app.use("/runtime", express.static(RUNTIME_DIR));
+    app.get("/widget/:name/:hash/files", async (req, res) => {
+      const widget = await store.getWidget(req.params.name, req.params.hash);
+      if (!widget) {
+        res.status(404).json({ error: "not found" });
+        return;
+      }
+      res.json({ files: widget.files, entry: widget.entry, manifest: widget.manifest });
+    });
+
+    httpServer = createServer(app);
+    await new Promise<void>((resolve) => httpServer.listen(0, "127.0.0.1", resolve));
+
+    const addr = httpServer.address() as { address: string; port: number };
+    widgetUrl = `http://127.0.0.1:${addr.port}/runtime/?widget=${TEST_MANIFEST.name}/${hash}`;
+  }, 120_000);
+
+  test.afterAll(async () => {
+    await new Promise<void>((resolve, reject) =>
+      httpServer.close((err) => (err ? reject(err) : resolve()))
+    );
+  });
+
+  test("widget compiles and renders in browser", async ({ page }) => {
+    await page.goto(widgetUrl);
+
+    // The runtime mounts the compiled widget into #root
+    await expect(page.locator("#root > *")).toBeVisible({ timeout: 90_000 });
+
+    // Our widget's inner element should also be visible
+    await expect(page.locator("#widget-content")).toBeVisible();
+
+    await page.screenshot({
+      path: ".artifacts/screenshots/widget-smoke.png",
+      fullPage: true,
+    });
+  });
+});

package/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>timer</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+      }
+      iframe {
+        width: 100%;
+        height: 100%;
+        border: none;
+      }
+    </style>
+  </head>
+  <body>
+    <iframe
+      src="https://cloudy-hair-camcorders-open.trycloudflare.com/widget/timer/c177be55eb568a0b"
+      title="timer"
+      sandbox="allow-scripts allow-same-origin"
+    ></iframe>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aprovan/mcp-app-server",
+  "version": "0.1.0-dev.4d82df8",
+  "description": "MCP App Server — hosts MCP tools that render interactive UIs in Claude Desktop and Claude web.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mcp-app-server": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "zod": "^3.23.0",
+    "@aprovan/patchwork-compiler": "0.1.2-dev.4d82df8",
+    "@aprovan/patchwork-image-shadcn": "0.1.0-dev.4d82df8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.10.5",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.3.5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup && vite build --config vite.runtime.config.ts && vite build --config vite.shell.config.ts",
+    "build:runtime": "vite build --config vite.runtime.config.ts",
+    "build:shell": "vite build --config vite.shell.config.ts",
+    "check-types": "tsc --noEmit",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run src/",
+    "e2e:visual": "pnpm build:runtime && playwright test --config playwright.config.ts",
+    "artifacts:export": "tsx src/scripts/export-artifacts.ts"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig, devices } from "@playwright/test";
+import { join } from "node:path";
+
+const ARTIFACTS_DIR = join(process.cwd(), ".artifacts");
+
+/**
+ * Playwright configuration for visual widget tests.
+ *
+ * Run with: pnpm run e2e:visual
+ *
+ * Setup required before first run:
+ *   npx playwright install chromium
+ *
+ * Global setup starts an in-process Express widget server and compiles
+ * reference widgets before any tests run, so no external server is needed.
+ */
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env["CI"],
+  retries: process.env["CI"] ? 1 : 0,
+  workers: 1,
+  timeout: 120_000,
+  globalSetup: "./e2e/global-setup.ts",
+  globalTeardown: "./e2e/global-teardown.ts",
+  snapshotDir: join(ARTIFACTS_DIR, "snapshots"),
+  outputDir: join(ARTIFACTS_DIR, "playwright"),
+  reporter: [
+    ["list"],
+    ["html", { outputFolder: join(ARTIFACTS_DIR, "playwright-report"), open: "never" }],
+  ],
+  use: {
+    baseURL: "http://localhost:3002",
+    screenshot: "on",
+    trace: "off",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});

package/src/__tests__/live-update.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  appendEvent,
+  getEvents,
+  pushStreamUpdate,
+  currentSeq,
+  registerSession,
+  unregisterSession,
+  subscribeSession,
+  unsubscribeSession,
+  _resetForTests,
+} from "../live-update.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Minimal McpServer stub — `server.notification()` is the SDK's one-way push method
+function makeMockServer(notificationFn = vi.fn().mockResolvedValue(undefined)) {
+  return {
+    server: { notification: notificationFn },
+  } as unknown as McpServer;
+}
+
+beforeEach(() => {
+  _resetForTests();
+});
+
+describe("appendEvent / getEvents", () => {
+  it("stores events and retrieves them by afterSeq", () => {
+    appendEvent("prices", { price: 100 });
+    appendEvent("prices", { price: 101 });
+    const events = getEvents("prices", 0);
+    expect(events).toHaveLength(2);
+    expect(events[0]!.data).toEqual({ price: 100 });
+    expect(events[1]!.data).toEqual({ price: 101 });
+  });
+
+  it("only returns events after the given seq", () => {
+    appendEvent("prices", { price: 1 });
+    const e2 = appendEvent("prices", { price: 2 });
+    appendEvent("prices", { price: 3 });
+
+    const events = getEvents("prices", e2.seq);
+    expect(events).toHaveLength(1);
+    expect(events[0]!.data).toEqual({ price: 3 });
+  });
+
+  it("returns empty array for unknown stream", () => {
+    expect(getEvents("unknown", 0)).toEqual([]);
+  });
+
+  it("assigns monotonically increasing seq numbers across streams", () => {
+    const a = appendEvent("a", 1);
+    const b = appendEvent("b", 2);
+    expect(b.seq).toBeGreaterThan(a.seq);
+  });
+
+  it("evicts oldest events when buffer exceeds 100 entries", () => {
+    for (let i = 0; i < 110; i++) {
+      appendEvent("big", i);
+    }
+    // We can still get events after seq 0, but only the last 100
+    const events = getEvents("big", 0);
+    expect(events.length).toBe(100);
+  });
+});
+
+describe("currentSeq", () => {
+  it("starts at 0 and increments on append", () => {
+    expect(currentSeq()).toBe(0);
+    appendEvent("s", 1);
+    expect(currentSeq()).toBe(1);
+    appendEvent("s", 2);
+    expect(currentSeq()).toBe(2);
+  });
+});
+
+describe("session registry", () => {
+  it("registers and unregisters sessions", () => {
+    const server = makeMockServer();
+    registerSession("sess-1", server);
+    // After registering, subscribing should work without error
+    subscribeSession("sess-1", "prices");
+    unregisterSession("sess-1");
+    // After unregistering, subscribe is a no-op (doesn't throw)
+    expect(() => subscribeSession("sess-1", "prices")).not.toThrow();
+  });
+
+  it("unsubscribeSession removes a stream", () => {
+    const notify = vi.fn().mockResolvedValue(undefined);
+    const server = makeMockServer(notify);
+    registerSession("sess-2", server);
+    subscribeSession("sess-2", "prices");
+    unsubscribeSession("sess-2", "prices");
+
+    // pushStreamUpdate should not call notify since we unsubscribed
+    return pushStreamUpdate("prices", { price: 99 }).then(() => {
+      expect(notify).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("pushStreamUpdate", () => {
+  it("buffers the event and returns its seq", async () => {
+    const seq = await pushStreamUpdate("orders", { id: 1 });
+    expect(seq).toBeGreaterThan(0);
+    const events = getEvents("orders", 0);
+    expect(events).toHaveLength(1);
+    expect(events[0]!.data).toEqual({ id: 1 });
+  });
+
+  it("sends notifications/tools/list_changed to subscribed sessions", async () => {
+    const notify = vi.fn().mockResolvedValue(undefined);
+    const server = makeMockServer(notify);
+    registerSession("sess-a", server);
+    subscribeSession("sess-a", "prices");
+
+    await pushStreamUpdate("prices", { price: 42 });
+
+    expect(notify).toHaveBeenCalledWith({
+      method: "notifications/tools/list_changed",
+    });
+  });
+
+  it("does not notify sessions subscribed to a different stream", async () => {
+    const notify = vi.fn().mockResolvedValue(undefined);
+    const server = makeMockServer(notify);
+    registerSession("sess-b", server);
+    subscribeSession("sess-b", "quotes"); // subscribed to "quotes", not "prices"
+
+    await pushStreamUpdate("prices", { price: 42 });
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  it("notifies multiple sessions subscribed to the same stream", async () => {
+    const notify1 = vi.fn().mockResolvedValue(undefined);
+    const notify2 = vi.fn().mockResolvedValue(undefined);
+    registerSession("sess-c", makeMockServer(notify1));
+    registerSession("sess-d", makeMockServer(notify2));
+    subscribeSession("sess-c", "trades");
+    subscribeSession("sess-d", "trades");
+
+    await pushStreamUpdate("trades", { trade: "AAPL" });
+    expect(notify1).toHaveBeenCalledOnce();
+    expect(notify2).toHaveBeenCalledOnce();
+  });
+
+  it("continues notifying other sessions if one throws", async () => {
+    const failing = vi.fn().mockRejectedValue(new Error("transport closed"));
+    const ok = vi.fn().mockResolvedValue(undefined);
+    registerSession("sess-fail", makeMockServer(failing));
+    registerSession("sess-ok", makeMockServer(ok));
+    subscribeSession("sess-fail", "events");
+    subscribeSession("sess-ok", "events");
+
+    // Should not reject even if one session fails
+    await expect(pushStreamUpdate("events", { msg: "hi" })).resolves.toBeDefined();
+    expect(ok).toHaveBeenCalledOnce();
+  });
+});