pmx-canvas 0.1.2 → 0.1.4

package/src/server/server.ts

@@ -39,12 +39,14 @@ import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } fro
 import { basename, extname, join, relative, resolve } from 'node:path';
 import * as marked from 'marked';
 import type {
+  CallToolResult,
   ListPromptsResult,
   ListResourcesResult,
   ListResourceTemplatesResult,
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
 import { type CanvasEdge, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
 import {
@@ -92,7 +94,16 @@ import {
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
-import { buildExcalidrawOpenMcpAppInput } from './diagram-presets.js';
+import {
+  EXCALIDRAW_READ_CHECKPOINT_TOOL,
+  EXCALIDRAW_SAVE_CHECKPOINT_TOOL,
+  buildExcalidrawCheckpointId,
+  buildExcalidrawOpenMcpAppInput,
+  buildExcalidrawRestoreCheckpointToolInput,
+  ensureExcalidrawCheckpointId,
+  getExcalidrawCheckpointIdFromToolResult,
+  isExcalidrawCreateView,
+} from './diagram-presets.js';
 import { traceManager } from './trace-manager.js';
 import { buildWebArtifactOnCanvas, resolveWorkspacePath } from './web-artifacts.js';
 import {
@@ -592,18 +603,102 @@ function getMarkdownPlacement(): { x: number; y: number } {
 }
 
 function findCanvasExtAppNodeId(toolCallId: string): string | null {
-  const directId = `ext-app-${toolCallId}`;
-  if (canvasState.getNode(directId)) return directId;
-  for (const node of canvasState.getLayout().nodes) {
-    if (
-      node.type === 'mcp-app' &&
-      node.data.mode === 'ext-app' &&
-      node.data.toolCallId === toolCallId
-    ) {
-      return node.id;
-    }
+  return findCanvasExtAppNodeIdShared(toolCallId, {
+    getNode: (id) => canvasState.getNode(id),
+    listNodes: () => canvasState.getLayout().nodes,
+  });
+}
+
+function isCheckpointToolName(toolName: string): boolean {
+  return toolName === EXCALIDRAW_SAVE_CHECKPOINT_TOOL || toolName === EXCALIDRAW_READ_CHECKPOINT_TOOL;
+}
+
+/**
+ * Decide whether a fresh `callServerTool` result should *replace* the
+ * canvas node's bootstrap-replay `toolResult`.
+ *
+ * The bootstrap-replay toolResult is what the server re-sends to the
+ * widget on reload to restore visible state. We only want to overwrite
+ * it when the new result genuinely carries widget state — `isError` or
+ * `structuredContent`. A plain-text result (e.g. `read_checkpoint`
+ * returning a string status, or any informational message) updates
+ * `appModelContext` for the agent's record but should *not* clobber the
+ * bootstrap entry, because doing so would replace the widget's restored
+ * state with conversational noise on the next reload.
+ *
+ * This separation is exercised by:
+ *   - tests/unit/server-api.test.ts "keeps ext-app model context
+ *     separate from the replayed tool result" (text-only result preserves
+ *     bootstrap replay)
+ *   - tests/unit/server-api.test.ts "app-only text tool results update
+ *     model context without replacing bootstrap replay"
+ *   - tests/unit/server-api.test.ts "rehydrates Excalidraw checkpoint
+ *     replay after server restart" (structured-content result becomes
+ *     the new bootstrap replay)
+ */
+function shouldReplayAppToolResult(toolName: string, result: CallToolResult): boolean {
+  void toolName;
+  return Boolean(result.isError || result.structuredContent);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function getExtAppNodeCheckpointId(node: CanvasNodeState): string {
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  const storedCheckpointId = appCheckpoint?.id;
+  if (typeof storedCheckpointId === 'string' && storedCheckpointId.trim().length > 0) {
+    return storedCheckpointId.trim();
   }
-  return null;
+  return getExcalidrawCheckpointIdFromToolResult(node.data.toolResult) ?? buildExcalidrawCheckpointId(node.id);
+}
+
+function getLocalExcalidrawCheckpointData(
+  node: CanvasNodeState,
+  args: Record<string, unknown> | undefined,
+): string | null {
+  if (!isExcalidrawCreateView(node.data.serverName, node.data.toolName)) return null;
+  if (!isRecord(args) || typeof args.id !== 'string') return null;
+  if (args.id.trim() !== getExtAppNodeCheckpointId(node)) return null;
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  const data = appCheckpoint?.data;
+  return typeof data === 'string' ? data : '';
+}
+
+function persistExcalidrawCheckpointToNode(
+  nodeId: string,
+  node: CanvasNodeState,
+  args: Record<string, unknown> | undefined,
+): boolean {
+  if (!isExcalidrawCreateView(node.data.serverName, node.data.toolName)) return false;
+  if (!isRecord(args) || typeof args.id !== 'string') return false;
+  const checkpointId = getExtAppNodeCheckpointId(node);
+  if (args.id.trim() !== checkpointId) return false;
+
+  const currentToolInput = isRecord(node.data.toolInput) ? node.data.toolInput : {};
+  const nextToolInput = {
+    ...currentToolInput,
+    elements: buildExcalidrawRestoreCheckpointToolInput(checkpointId, args.data),
+  };
+  const currentToolResult = isRecord(node.data.toolResult)
+    ? ensureExcalidrawCheckpointId(node.data.toolResult as CallToolResult, node.id, checkpointId)
+    : undefined;
+
+  canvasState.updateNode(nodeId, {
+    data: {
+      ...node.data,
+      toolInput: nextToolInput,
+      ...(currentToolResult ? { toolResult: currentToolResult } : {}),
+      appCheckpoint: {
+        toolName: EXCALIDRAW_SAVE_CHECKPOINT_TOOL,
+        id: checkpointId,
+        ...(typeof args.data === 'string' ? { data: args.data } : {}),
+        updatedAt: new Date().toISOString(),
+      },
+    },
+  });
+  return true;
 }
 
 function findReusableCanvasExtAppNodeId(serverName: string, toolName: string): string | null {
@@ -1323,7 +1418,13 @@ async function handleCanvasArrange(req: Request): Promise<Response> {
   }
   const result = arrangeCanvasNodes(layout as 'grid' | 'column' | 'flow');
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-  return responseJson({ ok: true, arranged: result.arranged, layout: result.layout });
+  const validation = validateCanvasLayout(canvasState.getLayout());
+  return responseJson({
+    ok: validation.ok,
+    arranged: result.arranged,
+    layout: result.layout,
+    ...(validation.ok ? {} : { validation, collisions: validation.summary.collisions }),
+  });
 }
 
 // ── Focus on node ───────────────────────────────────────────
@@ -1333,11 +1434,17 @@ async function handleCanvasFocus(req: Request): Promise<Response> {
   if (!nodeId) return responseJson({ ok: false, error: 'Missing id.' }, 400);
   const node = canvasState.getNode(nodeId);
   if (!node) return responseJson({ ok: false, error: `Node "${nodeId}" not found.` }, 404);
-  canvasState.setViewport({ x: node.position.x - 100, y: node.position.y - 100 });
-  emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId });
-  emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
+  const noPan = body.noPan === true;
+  if (!noPan) {
+    canvasState.setViewport({ x: node.position.x - 100, y: node.position.y - 100 });
+  } else {
+    const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
+    canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });
+  }
+  emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId, noPan });
+  if (!noPan) emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-  return responseJson({ ok: true, focused: nodeId });
+  return responseJson({ ok: true, focused: nodeId, panned: !noPan });
 }
 
 async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
@@ -1375,6 +1482,9 @@ async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
       ...(typeof body.bundleScriptPath === 'string'
         ? { bundleScriptPath: body.bundleScriptPath }
         : {}),
+      ...(Array.isArray(body.deps)
+        ? { deps: body.deps.filter((dep): dep is string => typeof dep === 'string') }
+        : {}),
       ...(typeof body.timeoutMs === 'number' ? { timeoutMs: body.timeoutMs } : {}),
       ...(typeof body.openInCanvas === 'boolean' ? { openInCanvas: body.openInCanvas } : {}),
     });
@@ -1447,10 +1557,22 @@ async function handleCanvasValidateSpec(req: Request): Promise<Response> {
         data,
         ...(typeof body.xKey === 'string' ? { xKey: body.xKey } : {}),
         ...(typeof body.yKey === 'string' ? { yKey: body.yKey } : {}),
+        ...(typeof body.zKey === 'string' ? { zKey: body.zKey } : {}),
         ...(typeof body.nameKey === 'string' ? { nameKey: body.nameKey } : {}),
         ...(typeof body.valueKey === 'string' ? { valueKey: body.valueKey } : {}),
+        ...(typeof body.axisKey === 'string' ? { axisKey: body.axisKey } : {}),
+        ...(Array.isArray(body.metrics)
+          ? { metrics: body.metrics.filter((m: unknown): m is string => typeof m === 'string') }
+          : {}),
+        ...(Array.isArray(body.series)
+          ? { series: body.series.filter((s: unknown): s is string => typeof s === 'string') }
+          : {}),
+        ...(typeof body.barKey === 'string' ? { barKey: body.barKey } : {}),
+        ...(typeof body.lineKey === 'string' ? { lineKey: body.lineKey } : {}),
         ...(aggregate ? { aggregate } : {}),
         ...(typeof body.color === 'string' ? { color: body.color } : {}),
+        ...(typeof body.barColor === 'string' ? { barColor: body.barColor } : {}),
+        ...(typeof body.lineColor === 'string' ? { lineColor: body.lineColor } : {}),
         ...(typeof body.height === 'number' ? { height: body.height } : {}),
       },
     }));
@@ -1773,7 +1895,7 @@ function handleRead(pathLike: string): Response {
 }
 
 function randomExtAppToolCallId(): string {
-  return `ext-app-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
 function nodeAppSessionId(node: CanvasNodeState | undefined): string | null {
@@ -1853,10 +1975,15 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
     });
 
     const toolCallId = randomExtAppToolCallId();
+    const nodeIdSeed = toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`;
+    const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
+      ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
+      : opened.toolResult;
     const nodeTitle = params.title ?? opened.tool.title ?? opened.tool.name;
 
     emitPrimaryWorkbenchEvent('ext-app-open', {
       toolCallId,
+      nodeId: nodeIdSeed,
       title: nodeTitle,
       html: opened.html,
       toolInput: opened.toolInput,
@@ -1876,15 +2003,17 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
     });
     emitPrimaryWorkbenchEvent('ext-app-result', {
       toolCallId,
+      nodeId: nodeIdSeed,
       serverName: opened.serverName,
       toolName: opened.toolName,
-      success: opened.toolResult.isError !== true,
-      result: opened.toolResult,
+      success: toolResult.isError !== true,
+      result: toolResult,
     });
     const nodeId = findCanvasExtAppNodeId(toolCallId);
 
     return responseJson({
       ok: true,
+      ...(nodeId ? { id: nodeId } : {}),
       nodeId,
       toolCallId,
       sessionId: opened.sessionId,
@@ -1979,35 +2108,53 @@ async function handleExtAppCallTool(req: Request): Promise<Response> {
   const nodeId = typeof body.nodeId === 'string' ? body.nodeId.trim() : '';
 
   try {
-    const result = await callMcpAppTool(sessionId, toolName, args);
+    const requestedNode = nodeId ? canvasState.getNode(nodeId) : undefined;
+    const canReadLocalCheckpoint =
+      requestedNode?.type === 'mcp-app' &&
+      requestedNode.data.mode === 'ext-app' &&
+      requestedNode.data.appSessionId === sessionId;
+    const localCheckpointData = canReadLocalCheckpoint && toolName === EXCALIDRAW_READ_CHECKPOINT_TOOL
+      ? getLocalExcalidrawCheckpointData(requestedNode, args)
+      : null;
+    const result = localCheckpointData === null
+      ? await callMcpAppTool(sessionId, toolName, args)
+      : { content: [{ type: 'text', text: localCheckpointData }] } satisfies CallToolResult;
     if (nodeId) {
       const node = canvasState.getNode(nodeId);
       if (node?.type === 'mcp-app' && node.data.mode === 'ext-app' && node.data.appSessionId === sessionId) {
-        const nextData: Record<string, unknown> = {
-          ...node.data,
-          toolResult: result,
-        };
-        const nextModelContext: Record<string, unknown> = {};
-        if (Array.isArray(result.content)) {
-          nextModelContext.content = result.content;
-        }
-        if (result.structuredContent && typeof result.structuredContent === 'object' && !Array.isArray(result.structuredContent)) {
-          nextModelContext.structuredContent = result.structuredContent;
+        let changed = false;
+        if (toolName === EXCALIDRAW_SAVE_CHECKPOINT_TOOL && persistExcalidrawCheckpointToNode(nodeId, node, args)) {
+          // Checkpoint saves are replayed through toolInput.elements instead of
+          // replacing the original create_view result with a generic "ok".
+          changed = true;
+        } else if (!(isExcalidrawCreateView(node.data.serverName, node.data.toolName) && isCheckpointToolName(toolName))) {
+          const nextData: Record<string, unknown> = { ...node.data };
+          if (shouldReplayAppToolResult(toolName, result)) nextData.toolResult = result;
+          const nextModelContext: Record<string, unknown> = {};
+          if (Array.isArray(result.content)) {
+            nextModelContext.content = result.content;
+          }
+          if (result.structuredContent && typeof result.structuredContent === 'object' && !Array.isArray(result.structuredContent)) {
+            nextModelContext.structuredContent = result.structuredContent;
+          }
+          if (Object.keys(nextModelContext).length > 0) {
+            nextData.appModelContext = {
+              ...nextModelContext,
+              updatedAt: new Date().toISOString(),
+            };
+          }
+          canvasState.updateNode(nodeId, {
+            data: nextData,
+          });
+          changed = true;
         }
-        if (Object.keys(nextModelContext).length > 0) {
-          nextData.appModelContext = {
-            ...nextModelContext,
-            updatedAt: new Date().toISOString(),
-          };
+        if (changed) {
+          broadcastWorkbenchEvent('canvas-layout-update', {
+            layout: canvasState.getLayout(),
+            sessionId: primaryWorkbenchSessionId,
+            timestamp: new Date().toISOString(),
+          });
         }
-        canvasState.updateNode(nodeId, {
-          data: nextData,
-        });
-        broadcastWorkbenchEvent('canvas-layout-update', {
-          layout: canvasState.getLayout(),
-          sessionId: primaryWorkbenchSessionId,
-          timestamp: new Date().toISOString(),
-        });
       }
     }
     return responseJson({ ok: true, result });
@@ -3031,10 +3178,13 @@ function syncEventToCanvasState(event: string, payload: PrimaryWorkbenchEventPay
   } else if (event === 'ext-app-open') {
     const toolCallId = payload.toolCallId as string;
     if (!toolCallId) return;
-    const id = `ext-app-${toolCallId}`;
+    const id = typeof payload.nodeId === 'string' && payload.nodeId.length > 0
+      ? payload.nodeId
+      : toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`;
     const dataPatch = {
       mode: 'ext-app',
       toolCallId,
+      nodeId: id,
       ...(typeof payload.title === 'string' && payload.title.trim().length > 0
         ? { title: payload.title.trim() }
         : {}),
@@ -3102,7 +3252,9 @@ function syncEventToCanvasState(event: string, payload: PrimaryWorkbenchEventPay
   } else if (event === 'ext-app-update') {
     const toolCallId = payload.toolCallId as string;
     if (!toolCallId) return;
+    const payloadNodeId = typeof payload.nodeId === 'string' ? payload.nodeId : '';
     const id =
+      (payloadNodeId && canvasState.getNode(payloadNodeId) ? payloadNodeId : null) ||
       findCanvasExtAppNodeId(toolCallId) ||
       (typeof payload.serverName === 'string' && typeof payload.toolName === 'string'
         ? findOnlyPendingCanvasExtAppNodeId(payload.serverName, payload.toolName)
@@ -3115,7 +3267,9 @@ function syncEventToCanvasState(event: string, payload: PrimaryWorkbenchEventPay
   } else if (event === 'ext-app-result') {
     const toolCallId = payload.toolCallId as string;
     if (!toolCallId) return;
+    const payloadNodeId = typeof payload.nodeId === 'string' ? payload.nodeId : '';
     const id =
+      (payloadNodeId && canvasState.getNode(payloadNodeId) ? payloadNodeId : null) ||
       findCanvasExtAppNodeId(toolCallId) ||
       (typeof payload.serverName === 'string' && typeof payload.toolName === 'string'
         ? findOnlyPendingCanvasExtAppNodeId(payload.serverName, payload.toolName)

package/src/server/web-artifacts/scripts/bundle-artifact.sh

@@ -152,10 +152,20 @@ rm -rf dist bundle.html
 echo "🔨 Building with Parcel..."
 run_with_filtered_stderr run_local_binary parcel build index.html --dist-dir dist --no-source-maps --log-level error
 
+if [ ! -s "dist/index.html" ]; then
+  echo "❌ Error: Parcel did not produce dist/index.html" >&2
+  exit 1
+fi
+
 # Inline everything into single HTML
 echo "🎯 Inlining all assets into single HTML file..."
 run_with_filtered_stderr run_local_binary html-inline dist/index.html > bundle.html
 
+if [ ! -s "bundle.html" ]; then
+  echo "❌ Error: Bundled artifact is empty" >&2
+  exit 1
+fi
+
 # Get file size
 FILE_SIZE=$(du -h bundle.html | cut -f1)
 

package/src/server/web-artifacts/scripts/init-artifact.sh

@@ -173,7 +173,7 @@ fi
 
 echo "📦 Installing Tailwind CSS and dependencies..."
 run_pnpm_allow_build add -D tailwindcss@3.4.1 postcss @types/node tailwindcss-animate parcel @parcel/config-default parcel-resolver-tspaths html-inline
-run_pnpm_quiet add class-variance-authority clsx tailwind-merge lucide-react next-themes
+run_pnpm_quiet add class-variance-authority clsx tailwind-merge lucide-react next-themes recharts
 
 echo "⚙️  Creating Tailwind and PostCSS configuration..."
 cat > .postcssrc.json << 'EOF'

package/src/server/web-artifacts.ts

@@ -38,6 +38,7 @@ export interface WebArtifactBuildInput {
   outputPath?: string;
   initScriptPath?: string;
   bundleScriptPath?: string;
+  deps?: string[];
   timeoutMs?: number;
 }
 
@@ -322,6 +323,19 @@ function ensurePackageManagerBoundary(dirPath: string): void {
   writeFileSync(packageJsonPath, JSON.stringify(nextPackageJson, null, 2), 'utf-8');
 }
 
+function normalizeDependencyNames(deps: string[] | undefined): string[] {
+  const normalized = new Set<string>();
+  for (const dep of deps ?? []) {
+    const trimmed = dep.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('-') || !/^(@[a-z0-9._-]+\/)?[a-z0-9._-]+(@[\w.+~^*-][\w.+~^*-]*)?$/i.test(trimmed)) {
+      throw new Error(`Invalid web-artifact dependency name: ${dep}`);
+    }
+    normalized.add(trimmed);
+  }
+  return [...normalized];
+}
+
 function summarizeArtifactLog(text: string): WebArtifactLogSummary | undefined {
   if (!text.trim()) return undefined;
 
@@ -391,6 +405,23 @@ export async function executeWebArtifactBuild(
 
   writeProjectFiles(projectPath, input);
 
+  const deps = normalizeDependencyNames(input.deps);
+  if (deps.length > 0) {
+    const quotedDeps = deps.map((dep) => `'${dep.replaceAll("'", "'\\''")}'`).join(' ');
+    const pnpmVersion = DEFAULT_PACKAGE_MANAGER.split('@')[1] ?? '10.33.0';
+    // Use `bash -c` (not `-lc`): `-lc` sources the user's login profile
+    // (~/.bashrc, ~/.zshrc), which can mutate PATH or set aliases that
+    // change install behavior. With deps already validated against
+    // npm-name format and quoted via single-quote escaping, the regular
+    // shell is sufficient and reproducible across machines.
+    const depResult = await runProcess('bash', ['-c', `if command -v pnpm >/dev/null 2>&1; then pnpm --silent add --ignore-scripts -- ${quotedDeps}; elif command -v bun >/dev/null 2>&1; then bun x pnpm@${pnpmVersion} --silent add --ignore-scripts -- ${quotedDeps}; else npm install --ignore-scripts -- ${quotedDeps}; fi`], {
+      cwd: projectPath,
+      timeoutMs,
+    });
+    stdout = [stdout, depResult.stdout].filter(Boolean).join('\n');
+    stderr = [stderr, depResult.stderr].filter(Boolean).join('\n');
+  }
+
   const bundleResult = await runProcess('bash', [bundleScriptPath], {
     cwd: projectPath,
     timeoutMs,
@@ -403,18 +434,29 @@ export async function executeWebArtifactBuild(
     throw new Error(`Expected bundled artifact at ${bundlePath}`);
   }
 
+  const bundleSize = statSync(bundlePath).size;
+  if (bundleSize <= 0) {
+    throw new Error(`Bundled artifact is empty: ${bundlePath}`);
+  }
+
   mkdirSync(dirname(outputPath), { recursive: true });
   copyFileSync(bundlePath, outputPath);
+  // The script-side check in bundle-artifact.sh and the bundleSize check
+  // above already guarantee a non-empty source; copyFileSync would throw
+  // on a filesystem failure. A post-copy size check would be redundant
+  // defensive noise — see CLAUDE.md TypeScript Guardrail #3.
+  const fileSize = bundleSize;
 
   return {
     filePath: outputPath,
-    fileSize: statSync(outputPath).size,
+    fileSize,
     projectPath,
     metadata: {
       title: input.title,
       bundlePath,
       projectPath,
       hasIndexCss: typeof input.indexCss === 'string',
+      ...(deps.length > 0 ? { deps } : {}),
       extraFileCount: Object.keys(input.files ?? {}).length,
       outputPreview: readFileSync(outputPath, 'utf-8').slice(0, 200),
     },
@@ -452,6 +494,7 @@ export function openWebArtifactInCanvas(input: {
       trustedDomain: true,
       sourceServer: 'pmx-canvas',
       hostMode: 'hosted',
+      viewerType: 'web-artifact',
     },
   };