pmx-canvas 0.1.2 → 0.1.3

package/src/server/diagram-presets.ts

@@ -1,8 +1,40 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 
 export const EXCALIDRAW_MCP_URL = 'https://mcp.excalidraw.com/mcp';
 export const EXCALIDRAW_SERVER_NAME = 'Excalidraw';
 export const EXCALIDRAW_CREATE_VIEW_TOOL = 'create_view';
+export const EXCALIDRAW_SAVE_CHECKPOINT_TOOL = 'save_checkpoint';
+export const EXCALIDRAW_READ_CHECKPOINT_TOOL = 'read_checkpoint';
+const EXCALIDRAW_CAMERA_PADDING = 80;
+const EXCALIDRAW_MIN_CAMERA_WIDTH = 320;
+const EXCALIDRAW_MIN_CAMERA_HEIGHT = 240;
+const EXCALIDRAW_CAMERA_ASPECT_RATIO = 4 / 3;
+const EXCALIDRAW_CAMERA_SIZES = [
+  { width: 400, height: 300 },
+  { width: 600, height: 450 },
+  { width: 800, height: 600 },
+  { width: 1200, height: 900 },
+  { width: 1600, height: 1200 },
+];
+
+export const DEFAULT_EXCALIDRAW_ELEMENTS: ReadonlyArray<Record<string, unknown>> = [
+  {
+    type: 'rectangle',
+    id: 'pmx-start',
+    x: 80,
+    y: 80,
+    width: 280,
+    height: 120,
+    roundness: { type: 3 },
+    backgroundColor: '#a5d8ff',
+    fillStyle: 'solid',
+    label: {
+      text: 'PMX Canvas',
+      fontSize: 24,
+    },
+  },
+];
 
 export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
   type: 'http',
@@ -30,7 +62,11 @@ export interface ExcalidrawOpenMcpAppInput {
   height?: number;
 }
 
-export function normalizeExcalidrawElements(elements: unknown): string {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseExcalidrawElements(elements: unknown): Array<Record<string, unknown>> {
   if (typeof elements === 'string') {
     const trimmed = elements.trim();
     if (!trimmed) {
@@ -46,16 +82,195 @@ export function normalizeExcalidrawElements(elements: unknown): string {
     if (!Array.isArray(parsed)) {
       throw new Error('diagram.elements string must encode a JSON array.');
     }
-    return JSON.stringify(parsed);
+    return parsed.filter(isRecord);
   }
+
   if (Array.isArray(elements)) {
-    return JSON.stringify(elements);
+    return elements.filter(isRecord);
   }
+
   throw new Error('diagram.elements must be a JSON array string or an array of Excalidraw elements.');
 }
 
+function parseExcalidrawCheckpointElements(data: unknown): Array<Record<string, unknown>> | null {
+  let parsed: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+
+  if (Array.isArray(parsed)) return parsed.filter(isRecord);
+  if (isRecord(parsed) && Array.isArray(parsed.elements)) return parsed.elements.filter(isRecord);
+  return null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boolean {
+  return elements.some((element) => element.type === 'cameraUpdate');
+}
+
+function resolveExcalidrawCameraSize(width: number, height: number): { width: number; height: number } {
+  const requiredWidth = Math.max(EXCALIDRAW_MIN_CAMERA_WIDTH, width);
+  const requiredHeight = Math.max(EXCALIDRAW_MIN_CAMERA_HEIGHT, height);
+  const standard = EXCALIDRAW_CAMERA_SIZES.find(
+    (size) => size.width >= requiredWidth && size.height >= requiredHeight,
+  );
+  if (standard) return standard;
+
+  const heightFromWidth = requiredWidth / EXCALIDRAW_CAMERA_ASPECT_RATIO;
+  const widthFromHeight = requiredHeight * EXCALIDRAW_CAMERA_ASPECT_RATIO;
+  const cameraWidth = Math.ceil(Math.max(requiredWidth, widthFromHeight));
+  return {
+    width: cameraWidth,
+    height: Math.ceil(cameraWidth / EXCALIDRAW_CAMERA_ASPECT_RATIO),
+  };
+}
+
+export function inferExcalidrawCameraUpdate(
+  elements: Array<Record<string, unknown>>,
+): Record<string, unknown> | null {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+
+  const includePoint = (x: number, y: number) => {
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x);
+    maxY = Math.max(maxY, y);
+  };
+
+  for (const element of elements) {
+    if (element.isDeleted === true || element.type === 'cameraUpdate' || element.type === 'restoreCheckpoint' || element.type === 'delete') {
+      continue;
+    }
+
+    const x = finiteNumber(element.x);
+    const y = finiteNumber(element.y);
+    if (x === null || y === null) continue;
+
+    includePoint(x, y);
+    const width = finiteNumber(element.width) ?? 0;
+    const height = finiteNumber(element.height) ?? 0;
+    includePoint(x + width, y + height);
+
+    if (Array.isArray(element.points)) {
+      for (const point of element.points) {
+        if (!Array.isArray(point)) continue;
+        const pointX = finiteNumber(point[0]);
+        const pointY = finiteNumber(point[1]);
+        if (pointX === null || pointY === null) continue;
+        includePoint(x + pointX, y + pointY);
+      }
+    }
+  }
+
+  if (!Number.isFinite(minX) || !Number.isFinite(minY) || !Number.isFinite(maxX) || !Number.isFinite(maxY)) {
+    return null;
+  }
+
+  const contentWidth = Math.max(1, maxX - minX);
+  const contentHeight = Math.max(1, maxY - minY);
+  const padding = Math.max(
+    EXCALIDRAW_CAMERA_PADDING,
+    Math.round(Math.max(contentWidth, contentHeight) * 0.18),
+  );
+  const camera = resolveExcalidrawCameraSize(contentWidth + padding * 2, contentHeight + padding * 2);
+  const centerX = minX + contentWidth / 2;
+  const centerY = minY + contentHeight / 2;
+
+  return {
+    type: 'cameraUpdate',
+    x: Math.round(centerX - camera.width / 2),
+    y: Math.round(centerY - camera.height / 2),
+    width: camera.width,
+    height: camera.height,
+  };
+}
+
+function withInferredCameraUpdate(
+  elements: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  if (elementHasCameraUpdate(elements)) return elements;
+  const camera = inferExcalidrawCameraUpdate(elements);
+  return camera ? [camera, ...elements] : elements;
+}
+
+export function normalizeExcalidrawElements(elements: unknown): string {
+  const parsed = parseExcalidrawElements(elements);
+  return JSON.stringify(parsed.length > 0 ? parsed : DEFAULT_EXCALIDRAW_ELEMENTS);
+}
+
+export function normalizeExcalidrawElementsForToolInput(elements: unknown): string {
+  const parsed = parseExcalidrawElements(elements);
+  const seeded = parsed.length > 0 ? parsed : [...DEFAULT_EXCALIDRAW_ELEMENTS];
+  return JSON.stringify(withInferredCameraUpdate(seeded));
+}
+
+export function normalizeExcalidrawCheckpointDataForToolInput(data: unknown): string | null {
+  const elements = parseExcalidrawCheckpointElements(data);
+
+  return elements ? JSON.stringify(withInferredCameraUpdate(elements)) : null;
+}
+
+export function buildExcalidrawRestoreCheckpointToolInput(checkpointId: string, data?: unknown): string {
+  const elements = parseExcalidrawCheckpointElements(data);
+  const camera = elements ? inferExcalidrawCameraUpdate(elements) : null;
+  return JSON.stringify([
+    { type: 'restoreCheckpoint', id: checkpointId },
+    ...(camera ? [camera] : []),
+  ]);
+}
+
+export function isExcalidrawCreateView(serverName: unknown, toolName: unknown): boolean {
+  return serverName === EXCALIDRAW_SERVER_NAME && toolName === EXCALIDRAW_CREATE_VIEW_TOOL;
+}
+
+export function buildExcalidrawCheckpointId(seed: string): string {
+  const safe = seed.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 96);
+  return `pmx-${safe || 'checkpoint'}`;
+}
+
+export function getExcalidrawCheckpointIdFromToolResult(result: unknown): string | null {
+  if (!isRecord(result) || !isRecord(result.structuredContent)) return null;
+  const checkpointId = result.structuredContent.checkpointId;
+  return typeof checkpointId === 'string' && checkpointId.trim().length > 0 ? checkpointId.trim() : null;
+}
+
+export function withExcalidrawCheckpointId(
+  result: CallToolResult,
+  checkpointId: string,
+): CallToolResult {
+  const structuredContent = isRecord(result.structuredContent) ? result.structuredContent : {};
+  return {
+    ...result,
+    structuredContent: {
+      ...structuredContent,
+      checkpointId,
+    },
+  };
+}
+
+export function ensureExcalidrawCheckpointId(
+  result: CallToolResult,
+  seed: string,
+  checkpointId?: string | null,
+): CallToolResult {
+  return withExcalidrawCheckpointId(
+    result,
+    checkpointId ?? getExcalidrawCheckpointIdFromToolResult(result) ?? buildExcalidrawCheckpointId(seed),
+  );
+}
+
 export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput {
-  const elements = normalizeExcalidrawElements(input.elements);
+  const elements = normalizeExcalidrawElementsForToolInput(input.elements);
   const out: ExcalidrawOpenMcpAppInput = {
     transport: EXCALIDRAW_MCP_TRANSPORT,
     toolName: EXCALIDRAW_CREATE_VIEW_TOOL,

package/src/server/index.ts

@@ -44,6 +44,8 @@ import {
 } from './mcp-app-runtime.js';
 import {
   buildExcalidrawOpenMcpAppInput,
+  ensureExcalidrawCheckpointId,
+  isExcalidrawCreateView,
   type DiagramPresetOpenInput,
 } from './diagram-presets.js';
 import {
@@ -323,16 +325,22 @@ export class PmxCanvas extends EventEmitter {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
 
-  focusNode(id: string): void {
+  focusNode(id: string, options?: { noPan?: boolean }): { focused: string; panned: boolean } | null {
     const node = canvasState.getNode(id);
-    if (!node) return;
-    canvasState.setViewport({
-      x: node.position.x - 100,
-      y: node.position.y - 100,
-    });
-    emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId: id });
-    emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
+    if (!node) return null;
+    const noPan = options?.noPan === true;
+    if (!noPan) {
+      canvasState.setViewport({
+        x: node.position.x - 100,
+        y: node.position.y - 100,
+      });
+    }
+    emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId: id, noPan });
+    if (!noPan) {
+      emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
+    }
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return { focused: id, panned: !noPan };
   }
 
   getLayout(): CanvasLayout {
@@ -488,6 +496,10 @@ export class PmxCanvas extends EventEmitter {
       ...(input.serverName ? { serverName: input.serverName } : {}),
     });
     const toolCallId = `ext-app-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const nodeIdSeed = `ext-app-${toolCallId}`;
+    const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
+      ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
+      : opened.toolResult;
     emitPrimaryWorkbenchEvent('ext-app-open', {
       toolCallId,
       title: input.title ?? opened.tool.title ?? opened.tool.name,
@@ -511,8 +523,8 @@ export class PmxCanvas extends EventEmitter {
       toolCallId,
       serverName: opened.serverName,
       toolName: opened.toolName,
-      success: opened.toolResult.isError !== true,
-      result: opened.toolResult,
+      success: toolResult.isError !== true,
+      result: toolResult,
     });
     const nodeId = this.findCanvasExtAppNodeId(toolCallId);
     return {

package/src/server/server.ts

@@ -39,6 +39,7 @@ 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,
@@ -92,7 +93,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 {
@@ -606,6 +616,79 @@ function findCanvasExtAppNodeId(toolCallId: string): string | null {
   return null;
 }
 
+function isCheckpointToolName(toolName: string): boolean {
+  return toolName === EXCALIDRAW_SAVE_CHECKPOINT_TOOL || toolName === EXCALIDRAW_READ_CHECKPOINT_TOOL;
+}
+
+function shouldReplayAppToolResult(toolName: string, result: CallToolResult): boolean {
+  void toolName;
+  return Boolean(
+    result.isError ||
+      result.structuredContent ||
+      result.content.some((entry) => entry.type !== 'text' || entry.text !== 'ok'),
+  );
+}
+
+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 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 {
   for (const node of canvasState.getLayout().nodes) {
     if (
@@ -1323,7 +1406,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 +1422,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 +1470,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 } : {}),
     });
@@ -1853,6 +1951,10 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
     });
 
     const toolCallId = randomExtAppToolCallId();
+    const nodeIdSeed = `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', {
@@ -1878,8 +1980,8 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
       toolCallId,
       serverName: opened.serverName,
       toolName: opened.toolName,
-      success: opened.toolResult.isError !== true,
-      result: opened.toolResult,
+      success: toolResult.isError !== true,
+      result: toolResult,
     });
     const nodeId = findCanvasExtAppNodeId(toolCallId);
 
@@ -1979,35 +2081,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 });

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),
     },