pmx-canvas 0.1.1 → 0.1.3

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 (
@@ -1105,19 +1188,26 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
-  const { id, node, needsCodeGraphRecompute } = addCanvasNode({
-    type: type as CanvasNodeState['type'],
-    ...(typeof body.title === 'string' ? { title: body.title } : {}),
-    ...(typeof body.content === 'string' ? { content: body.content } : {}),
-    ...(extraData ? { data: extraData } : {}),
-    ...(typeof body.x === 'number' ? { x: body.x } : {}),
-    ...(typeof body.y === 'number' ? { y: body.y } : {}),
-    ...(typeof body.width === 'number' ? { width: body.width } : {}),
-    ...(typeof body.height === 'number' ? { height: body.height } : {}),
-    defaultWidth: 360,
-    defaultHeight: 200,
-    fileMode: 'auto',
-  });
+  let added: ReturnType<typeof addCanvasNode>;
+  try {
+    added = addCanvasNode({
+      type: type as CanvasNodeState['type'],
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(typeof body.content === 'string' ? { content: body.content } : {}),
+      ...(extraData ? { data: extraData } : {}),
+      ...(typeof body.x === 'number' ? { x: body.x } : {}),
+      ...(typeof body.y === 'number' ? { y: body.y } : {}),
+      ...(typeof body.width === 'number' ? { width: body.width } : {}),
+      ...(typeof body.height === 'number' ? { height: body.height } : {}),
+      defaultWidth: 360,
+      defaultHeight: 200,
+      fileMode: 'auto',
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return responseJson({ ok: false, error: message }, 400);
+  }
+  const { node, needsCodeGraphRecompute } = added;
 
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   if (needsCodeGraphRecompute) {
@@ -1316,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 ───────────────────────────────────────────
@@ -1326,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> {
@@ -1368,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 } : {}),
     });
@@ -1846,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', {
@@ -1871,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);
 
@@ -1972,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;
 }
 
@@ -163,6 +164,12 @@ async function runProcess(
       ]).has(key);
     }),
   );
+  // Spawn in its own process group (POSIX only — Windows has a different model).
+  // This lets us kill every descendant — pnpm, bun, parcel, swc, lmdb, etc. —
+  // if the build hangs or times out, instead of leaving orphans that accumulate
+  // file descriptors and processes across retries (seen as later
+  // `fork: Resource temporarily unavailable` in end-user reports).
+  const isPosix = process.platform !== 'win32';
   const child = spawn(command, args, {
     cwd: options.cwd,
     env: {
@@ -171,10 +178,33 @@ async function runProcess(
       CI: '1',
       npm_config_yes: 'true',
       pnpm_config_yes: 'true',
+      // Cap pnpm's internal child concurrency so installs don't blow past
+      // macOS default ulimit -u (often 256-2048) when resolving the ~30
+      // radix-ui dependencies in one `pnpm add` call.
+      pnpm_config_child_concurrency: '2',
+      NPM_CONFIG_CHILD_CONCURRENCY: '2',
     },
     stdio: ['ignore', 'pipe', 'pipe'],
+    detached: isPosix,
   });
 
+  const killTree = (signal: NodeJS.Signals): void => {
+    if (isPosix && typeof child.pid === 'number') {
+      try {
+        // Negative pid = send to the whole process group.
+        process.kill(-child.pid, signal);
+        return;
+      } catch {
+        // fall through to direct kill
+      }
+    }
+    try {
+      child.kill(signal);
+    } catch {
+      // ignore
+    }
+  };
+
   let stdout = '';
   let stderr = '';
   let timedOut = false;
@@ -189,12 +219,13 @@ async function runProcess(
   await new Promise<void>((resolvePromise, rejectPromise) => {
     const timer = setTimeout(() => {
       timedOut = true;
-      child.kill('SIGKILL');
+      killTree('SIGKILL');
       rejectPromise(new Error(`Command timed out after ${options.timeoutMs}ms: ${command}`));
     }, options.timeoutMs);
 
     child.on('error', (error) => {
       clearTimeout(timer);
+      killTree('SIGKILL');
       rejectPromise(error);
     });
 
@@ -202,9 +233,17 @@ async function runProcess(
       clearTimeout(timer);
       if (timedOut) return;
       if (code !== 0) {
+        const trimmedStderr = stderr.trim();
+        const stderrTail = trimmedStderr.split('\n').slice(-20).join('\n');
+        const trimmedStdout = stdout.trim();
+        const stdoutTail = trimmedStdout.split('\n').slice(-20).join('\n');
         rejectPromise(
           new Error(
-            [`Command failed (${code}): ${command} ${args.join(' ')}`, stderr.trim()]
+            [
+              `Command failed (${code}): ${command} ${args.join(' ')}`,
+              stderrTail && `stderr:\n${stderrTail}`,
+              !trimmedStderr && stdoutTail && `stdout:\n${stdoutTail}`,
+            ]
               .filter(Boolean)
               .join('\n'),
           ),
@@ -284,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;
 
@@ -353,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,
@@ -365,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),
     },

package/src/shared/ext-app-tool-result.ts

@@ -74,3 +74,28 @@ export function normalizeExtAppToolResult(
     isError,
   };
 }
+
+/**
+ * Structural equality between two `CallToolResult` values, used by the host
+ * ExtAppFrame to suppress echo-back re-renders when an SSE layout update
+ * mints a new object reference for an otherwise-unchanged tool result.
+ *
+ * JSON-stringify is adequate here: tool results are strictly JSON (no
+ * functions, symbols, or cycles), typically small, and on the hot path we
+ * only hit this when references already differ. For very large payloads
+ * (> ~2MB) an early length check skips the stringify to avoid a user-visible
+ * stall — such results are treated as "changed" and forwarded to the widget.
+ */
+export function extAppToolResultsMatch(a: CallToolResult, b: CallToolResult): boolean {
+  if (a === b) return true;
+  if (a.isError !== b.isError) return false;
+  try {
+    const sa = JSON.stringify(a);
+    const sb = JSON.stringify(b);
+    if (sa === undefined || sb === undefined) return false;
+    if (Math.abs(sa.length - sb.length) > 2_000_000) return false;
+    return sa === sb;
+  } catch {
+    return false;
+  }
+}