Add @mcpjam/chat-ui (Tier A read-only transcript renderer) (#2678)

Co-authored-by: Claude <noreply@anthropic.com>

Author: chelojimenez

.changeset/chat-ui-tier-a.md

@@ -0,0 +1,11 @@
+---
+"@mcpjam/chat-ui": minor
+---
+
+Introduce `@mcpjam/chat-ui` — a reusable, read-only transcript renderer (Tier
+A) for AI SDK `UIMessage`s. Renders text, reasoning, files, sources, JSON/data
+parts, approvals-as-state, and tool call/result blocks. Widget-bearing tool
+calls render a deterministic placeholder; the package is provider-free (no
+Convex/PostHog/inspector/widget-runtime imports, enforced by a build-time
+guard). Hosts can inject interactive tool/widget rendering via the
+`renderTool`/`renderWidget` seams on `Transcript`.

.gitignore

@@ -9,3 +9,4 @@ mcpjam-inspector/server/routes/apps/**/*.bundled.ts
 mcpjam-inspector/server/utils/browser-harness/*.generated.ts
 cli/dist/
 sdk/dist/
+chat-ui/dist/

chat-ui/README.md

@@ -0,0 +1,88 @@
+# @mcpjam/chat-ui
+
+A reusable, **read-only transcript renderer** for AI SDK-style chat messages
+(`UIMessage`). Renders text, reasoning, files, sources, JSON/data parts,
+approvals-as-state, and tool call/result blocks.
+
+This is **Tier A**: it does **not** render MCP Apps widgets. Widget-bearing tool
+calls render a deterministic placeholder (or are hidden). It has **zero runtime
+imports** from Convex, PostHog, inspector stores/state/contexts, the MCP Apps
+renderer, sandbox/iframe code, or widget replay — enforced by
+`scripts/check-no-tier-b-imports.mjs`.
+
+## Install
+
+```bash
+npm install @mcpjam/chat-ui
+```
+
+Peer deps: `react`, `react-dom`, `ai`, `@ai-sdk/react`.
+
+## Usage
+
+```tsx
+import { ReadOnlyTranscript } from "@mcpjam/chat-ui";
+import "@mcpjam/chat-ui/styles.css";
+
+export function Transcript({ messages }) {
+  return (
+    <ReadOnlyTranscript
+      messages={messages}
+      model={{ id: "gpt-5", name: "GPT-5", provider: "openai" }}
+      reasoningDisplayMode="collapsed"
+      widgetPolicy="placeholder"
+      themeMode="system"
+    />
+  );
+}
+```
+
+### `ReadOnlyTranscript` props
+
+| Prop                   | Type                                            | Default                                            |
+| ---------------------- | ----------------------------------------------- | -------------------------------------------------- |
+| `messages`             | `UIMessage[]`                                   | —                                                  |
+| `model`                | `ChatUiModel`                                   | `{ id: "unknown", name: "Unknown", provider: "custom" }` |
+| `toolsMetadata`        | `Record<string, Record<string, unknown>>`       | `{}`                                               |
+| `toolServerMap`        | `Record<string, string>`                        | `{}`                                               |
+| `toolRenderOverrides`  | `Record<string, ToolRenderOverride>`            | —                                                  |
+| `themeMode`            | `"light" \| "dark" \| "system"`                 | `"system"`                                         |
+| `reasoningDisplayMode` | `"inline" \| "collapsible" \| "collapsed" \| "hidden"` | `"inline"`                                  |
+| `widgetPolicy`         | `"placeholder" \| "hidden"`                     | `"placeholder"`                                    |
+| `className`            | `string`                                        | —                                                  |
+
+### Host integration (interactive embedders)
+
+`ReadOnlyTranscript` is fully static. Hosts that need interactivity (e.g. the
+MCPJam inspector) use the lower-level `Transcript` and inject seams — keeping
+the package free of their wiring:
+
+- `renderTool(ctx)` — render your own interactive tool block (save-view,
+  display-mode controls, etc.) instead of the static `ToolCallPart`.
+- `renderWidget(input)` — mount a real widget surface instead of the placeholder.
+
+```tsx
+import { Transcript } from "@mcpjam/chat-ui";
+
+<Transcript
+  messages={messages}
+  renderWidget={(input) => <MyWidget {...input} />}
+  renderTool={(ctx) => <MyInteractiveToolPart {...ctx} />}
+/>;
+```
+
+## Styling
+
+The renderer uses shadcn-style semantic utility classes
+(`text-muted-foreground`, `bg-card`, `border-border`, …). Consumers need a
+Tailwind v4-compatible utility layer. `@mcpjam/chat-ui/styles.css` ships the
+token *values* (scoped to `.mcpjam-chat-ui`) with light/dark defaults; override
+any `--token` to theme.
+
+> A fully self-contained compiled CSS bundle (so consumers don't need their own
+> Tailwind) is a planned follow-up.
+
+## Scope
+
+Tier A is read-only transcript review. Full MCP Apps widget replay (sandbox
+origin, CSP, security review) is a separate Tier B effort.

chat-ui/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mcpjam/chat-ui",
+  "version": "0.0.0",
+  "description": "Reusable, read-only transcript renderer for AI SDK chat messages (MCPJam).",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "npm run check:tier-b && tsup && node scripts/copy-css.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run check:tier-b && vitest run",
+    "check:tier-b": "node scripts/check-no-tier-b-imports.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@ai-sdk/react": "^3.0.0",
+    "ai": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.525.0",
+    "streamdown": "^2.1.0",
+    "tailwind-merge": "^3.3.1"
+  },
+  "devDependencies": {
+    "@ai-sdk/react": "^3.0.156",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "ai": "^6.0.154",
+    "jsdom": "^27.4.0",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}

chat-ui/scripts/check-no-tier-b-imports.mjs

@@ -0,0 +1,85 @@
+// Tier A guard: @mcpjam/chat-ui must stay provider-free and must not pull in
+// any inspector wiring, MCP Apps widget runtime, sandbox/iframe, or analytics.
+//
+// This is the package-local equivalent of the root
+// `check:mcp-v1-runtime-imports` script. It fails the build if any forbidden
+// module is imported anywhere under src/ (tests included — the renderer must
+// be testable without these too).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const srcDir = join(here, "..", "src");
+
+// Each entry is matched against the *module specifier* of every import/export
+// `from "..."` and dynamic `import("...")` in the source.
+const FORBIDDEN = [
+  "convex",
+  "posthog-js",
+  "@/stores",
+  "@/state",
+  "@/contexts",
+  "@/hooks",
+  "widget-replay",
+  "mcp-apps",
+  "csp-workbench",
+  "sandboxed-iframe",
+  "sandbox-proxy",
+  "@modelcontextprotocol/ext-apps",
+  "@mcp-ui/client",
+  "@/lib/client-config",
+  "@/lib/app-navigation",
+  "@/lib/host-capabilities",
+  "@mcpjam/design-system",
+];
+
+const SPECIFIER_RE =
+  /(?:import|export)\s[^;]*?from\s*["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else if (/\.(ts|tsx)$/.test(name)) out.push(full);
+  }
+  return out;
+}
+
+const violations = [];
+for (const file of walk(srcDir)) {
+  const text = readFileSync(file, "utf8");
+  let m;
+  while ((m = SPECIFIER_RE.exec(text)) !== null) {
+    const spec = m[1] ?? m[2];
+    if (!spec) continue;
+    const segments = spec.split("/");
+    for (const bad of FORBIDDEN) {
+      // Match an exact specifier, a subpath import (`bad/...`), or `bad` as a
+      // full path segment (so `./widget-replay` and `../mcp-apps/x` are
+      // caught) — without flagging unrelated names that merely contain the
+      // substring (e.g. `my-convex-helper`).
+      if (
+        spec === bad ||
+        spec.startsWith(`${bad}/`) ||
+        segments.includes(bad)
+      ) {
+        violations.push({ file: relative(srcDir, file), spec, bad });
+      }
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error("Tier A import guard FAILED. Forbidden imports found:\n");
+  for (const v of violations) {
+    console.error(`  ${v.file}: "${v.spec}" (matches "${v.bad}")`);
+  }
+  console.error(
+    "\n@mcpjam/chat-ui (Tier A) must not import provider/widget/inspector modules.",
+  );
+  process.exit(1);
+}
+
+console.log("Tier A import guard passed: no forbidden imports under src/.");

chat-ui/scripts/copy-css.mjs

@@ -0,0 +1,20 @@
+// Copy package-owned CSS into dist so consumers can `import
+// "@mcpjam/chat-ui/styles.css"`. tsup only emits the JS/d.ts bundle; the
+// stylesheet is shipped as-is.
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+const src = join(root, "src", "styles.css");
+const distDir = join(root, "dist");
+const dest = join(distDir, "styles.css");
+
+if (!existsSync(src)) {
+  console.error(`[copy-css] missing source stylesheet: ${src}`);
+  process.exit(1);
+}
+mkdirSync(distDir, { recursive: true });
+copyFileSync(src, dest);
+console.log(`[copy-css] ${src} -> ${dest}`);

chat-ui/src/__tests__/factories.ts

@@ -0,0 +1,38 @@
+import type { UIMessage } from "@ai-sdk/react";
+
+// Minimal UIMessage factories for tests. We cast through `unknown` because the
+// renderer only reads `id`, `role`, and `parts` — building the full AI SDK
+// message shape in every test would be noise.
+
+export function userText(text: string, id = "u1"): UIMessage {
+  return {
+    id,
+    role: "user",
+    parts: [{ type: "text", text }],
+  } as unknown as UIMessage;
+}
+
+export function assistantParts(
+  parts: Array<Record<string, unknown>>,
+  id = "a1",
+): UIMessage {
+  return { id, role: "assistant", parts } as unknown as UIMessage;
+}
+
+export function toolPart(opts: {
+  toolName: string;
+  toolCallId?: string;
+  state?: string;
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+}): Record<string, unknown> {
+  return {
+    type: `tool-${opts.toolName}`,
+    toolCallId: opts.toolCallId ?? "call-1",
+    state: opts.state ?? "output-available",
+    input: opts.input,
+    output: opts.output,
+    errorText: opts.errorText,
+  };
+}

chat-ui/src/__tests__/helpers.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+
+import { safeStringify } from "../internal/thread-helpers";
+import { isSafeImageUrl } from "../internal/safe-external-url";
+import {
+  UIType,
+  detectUIType,
+  getUIResourceUri,
+  isWidgetUiType,
+} from "../internal/widget-detection";
+
+describe("safeStringify", () => {
+  it("always returns a string (even for undefined)", () => {
+    expect(typeof safeStringify(undefined)).toBe("string");
+    expect(safeStringify(undefined)).toBe("undefined");
+    expect(safeStringify({ a: 1 })).toContain("\"a\": 1");
+  });
+});
+
+describe("isSafeImageUrl", () => {
+  it("allows inline data:image/* and absolute https:", () => {
+    expect(isSafeImageUrl("data:image/png;base64,AAAA")).toBe(true);
+    expect(isSafeImageUrl("https://example.com/cat.png")).toBe(true);
+  });
+
+  it("rejects http, javascript:, non-image data:, and junk", () => {
+    expect(isSafeImageUrl("http://example.com/cat.png")).toBe(false);
+    expect(isSafeImageUrl("javascript:alert(1)")).toBe(false);
+    expect(isSafeImageUrl("data:text/html,<script>")).toBe(false);
+    expect(isSafeImageUrl("")).toBe(false);
+    expect(isSafeImageUrl(undefined)).toBe(false);
+  });
+});
+
+describe("detectUIType", () => {
+  it("detects MCP Apps via flat (ui/resourceUri) and nested keys", () => {
+    expect(detectUIType({ "ui/resourceUri": "ui://x" }, undefined)).toBe(
+      UIType.MCP_APPS,
+    );
+    expect(detectUIType({ ui: { resourceUri: "ui://x" } }, undefined)).toBe(
+      UIType.MCP_APPS,
+    );
+    expect(getUIResourceUri(UIType.MCP_APPS, { "ui/resourceUri": "ui://x" })).toBe(
+      "ui://x",
+    );
+  });
+
+  it("only treats a non-empty string openai/outputTemplate as a widget", () => {
+    // Truthy non-string metadata must NOT classify as a widget.
+    expect(detectUIType({ "openai/outputTemplate": true }, undefined)).toBeNull();
+    expect(detectUIType({ "openai/outputTemplate": "" }, undefined)).toBeNull();
+    const ok = detectUIType({ "openai/outputTemplate": "ui://tmpl" }, undefined);
+    expect(ok).toBe(UIType.OPENAI_SDK);
+    expect(isWidgetUiType(ok)).toBe(true);
+  });
+
+  it("returns null for plain tools", () => {
+    expect(detectUIType({ foo: "bar" }, undefined)).toBeNull();
+    expect(isWidgetUiType(null)).toBe(false);
+  });
+});