pmx-canvas 0.1.3 → 0.1.5

package/src/server/canvas-serialization.ts

@@ -6,6 +6,7 @@ import {
 } from './canvas-provenance.js';
 
 export interface SerializedCanvasNode extends CanvasNodeState {
+  kind: string;
   title: string | null;
   content: string | null;
   path: string | null;
@@ -26,6 +27,21 @@ function pickProvenance(value: unknown): CanvasNodeProvenance | null {
   return value as CanvasNodeProvenance;
 }
 
+function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string {
+  if (node.type !== 'mcp-app') return node.type;
+  // Authoritative discriminator added in v0.1.4. New web-artifacts always set
+  // it; matching here first means a future URL-only artifact (no `data.path`)
+  // still classifies correctly without falling through to the legacy heuristic.
+  if (data.viewerType === 'web-artifact') return 'web-artifact';
+  if (data.mode === 'ext-app') return 'external-app';
+  // Transitional fallback for canvas state.json files persisted before v0.1.4
+  // introduced `viewerType`. Web-artifacts written by older versions always
+  // stored a `path` to the bundled HTML file, so this heuristic is safe for
+  // existing data. Remove in v0.2.x once a one-shot migration runs at boot.
+  if (data.hostMode === 'hosted' && typeof data.path === 'string') return 'web-artifact';
+  return 'mcp-app';
+}
+
 export function getCanvasNodeTitle(node: CanvasNodeState): string | null {
   return pickString(node.data.title)
     ?? (node.type === 'webpage' ? pickString(node.data.pageTitle) : null)
@@ -47,6 +63,7 @@ export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode
   return {
     ...node,
     data,
+    kind: getCanvasNodeKind(node, data),
     title: getCanvasNodeTitle(node),
     content: getCanvasNodeContent(node),
     path: pickString(data.path),
@@ -77,7 +94,8 @@ export function buildCanvasSummary(): CanvasSummary {
 
   const typeCounts: Record<string, number> = {};
   for (const n of layout.nodes) {
-    typeCounts[n.type] = (typeCounts[n.type] ?? 0) + 1;
+    const kind = getCanvasNodeKind(n, normalizeCanvasNodeData(n.type, n.data));
+    typeCounts[kind] = (typeCounts[kind] ?? 0) + 1;
   }
 
   const pinnedTitles = layout.nodes

package/src/server/ext-app-lookup.ts

@@ -0,0 +1,49 @@
+/**
+ * Resolve the canvas node ID for a given ext-app `toolCallId`.
+ *
+ * v0.1.4 fixed a long-standing `ext-app-ext-app-…` double-prefix bug where
+ * both `nodeId` and `toolCallId` carried the `ext-app-` prefix. This helper
+ * encodes the lookup contract so it doesn't drift between the
+ * `PmxCanvas` SDK class and the HTTP server.
+ *
+ * Resolution order:
+ *   1. The direct prefixed form (`ext-app-<toolCallId>` if not already
+ *      prefixed, otherwise `toolCallId` as-is).
+ *   2. The legacy `ext-app-ext-app-…` form, for canvases persisted before
+ *      v0.1.4 and still on disk. Remove this fallback in v0.2.x.
+ *   3. A scan of the layout for any `mcp-app` ext-app node carrying that
+ *      `toolCallId` in its data.
+ */
+import type { CanvasNodeState } from './canvas-state.js';
+
+export interface ExtAppLookupSource {
+  getNode(id: string): CanvasNodeState | undefined;
+  listNodes(): readonly CanvasNodeState[];
+}
+
+export function findCanvasExtAppNodeId(
+  toolCallId: string,
+  source: ExtAppLookupSource,
+): string | null {
+  const directId = toolCallId.startsWith('ext-app-')
+    ? toolCallId
+    : `ext-app-${toolCallId}`;
+  if (source.getNode(directId)) return directId;
+
+  const legacyDirectId = `ext-app-${toolCallId}`;
+  if (legacyDirectId !== directId && source.getNode(legacyDirectId)) {
+    return legacyDirectId;
+  }
+
+  for (const node of source.listNodes()) {
+    if (
+      node.type === 'mcp-app' &&
+      node.data.mode === 'ext-app' &&
+      node.data.toolCallId === toolCallId
+    ) {
+      return node.id;
+    }
+  }
+
+  return null;
+}

package/src/server/image-source.ts

@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { IMAGE_MIME_MAP } from './canvas-state.js';
+
+const IMAGE_HEADER_BYTES = 512;
+const IMAGE_HEADER_READ_TIMEOUT_MS = 5000;
+// Set by `chflags hidden`, iCloud Drive, OneDrive, etc. on macOS — the
+// metadata exists but the file content has not been downloaded locally.
+const MACOS_DATALESS_FLAG = 0x40000000;
+// Per macOS `man stat -f %Xf`, this bit is also set on iCloud Documents
+// & Files for content-not-yet-downloaded entries on newer OS releases.
+const MACOS_BSD_NODUMP_FLAG = 0x00000001;
+
+function fileName(path: string): string {
+  return basename(path) || path;
+}
+
+function readMacosFileFlags(path: string): number | null {
+  if (process.platform !== 'darwin') return null;
+
+  try {
+    const raw = execFileSync('/usr/bin/stat', ['-f', '%Xf', path], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+    }).trim();
+    return raw.length > 0 ? Number.parseInt(raw, 16) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isMacosCloudPlaceholder(path: string): boolean {
+  const flags = readMacosFileFlags(path);
+  if (flags === null) return false;
+  // Both flags can indicate iCloud-on-demand status depending on macOS
+  // release; treat either as a placeholder.
+  return (flags & MACOS_DATALESS_FLAG) !== 0 || (flags & MACOS_BSD_NODUMP_FLAG) !== 0;
+}
+
+function assertNotCloudPlaceholder(path: string): void {
+  if (isMacosCloudPlaceholder(path)) {
+    throw new Error(
+      `Invalid image node: "${fileName(path)}" appears to be a cloud-on-demand placeholder. ` +
+        'Ensure the file is downloaded locally before adding it as an image.',
+    );
+  }
+}
+
+function readHeaderWithDirectFs(path: string, size: number): Buffer {
+  const length = Math.min(IMAGE_HEADER_BYTES, size);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, 'r');
+  try {
+    const bytesRead = readSync(fd, buffer, 0, length, 0);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+interface ProcessSpawnError {
+  code?: string;
+  signal?: NodeJS.Signals;
+  status?: number;
+}
+
+function isProcessSpawnError(value: unknown): value is ProcessSpawnError {
+  return value !== null && typeof value === 'object';
+}
+
+function readHeaderWithDd(path: string): Buffer {
+  return execFileSync('/bin/dd', [`if=${path}`, `bs=${IMAGE_HEADER_BYTES}`, 'count=1'], {
+    encoding: 'buffer',
+    maxBuffer: IMAGE_HEADER_BYTES,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: IMAGE_HEADER_READ_TIMEOUT_MS,
+  });
+}
+
+function readHeaderWithTimeout(path: string, size: number): Buffer {
+  // Direct fs read is the fast path on every platform — no fork, no shell,
+  // no timeout required because the kernel either returns bytes immediately
+  // or fails synchronously. The `dd` escape hatch only matters for macOS
+  // cloud-on-demand placeholders, which `assertNotCloudPlaceholder` rejected
+  // at the call site, so this path is safe.
+  try {
+    return readHeaderWithDirectFs(path, size);
+  } catch (directError) {
+    // On macOS, fall through to `/bin/dd` so a kernel-level stall on a path
+    // we did not flag as a placeholder (e.g. an unmounted SMB share that
+    // still satisfies `existsSync`) cannot wedge a Bun fiber.
+    if (process.platform !== 'darwin' || !existsSync('/bin/dd')) {
+      throw directError;
+    }
+    try {
+      return readHeaderWithDd(path);
+    } catch (ddError) {
+      const reason = isProcessSpawnError(ddError) ? ddError : null;
+      const timedOut = reason?.signal === 'SIGTERM' || reason?.code === 'ETIMEDOUT';
+      if (timedOut) {
+        throw new Error(
+          `Invalid image node: could not read image header for "${fileName(path)}" within ${IMAGE_HEADER_READ_TIMEOUT_MS}ms. ` +
+            'If this file is stored in OneDrive, iCloud Drive, or another cloud-on-demand provider, download it locally first.',
+        );
+      }
+      const detail = ddError instanceof Error ? ddError.message : String(ddError);
+      throw new Error(
+        `Invalid image node: could not read "${fileName(path)}" — ${detail}.`,
+      );
+    }
+  }
+}
+
+function hasAscii(buffer: Buffer, offset: number, value: string): boolean {
+  return buffer.subarray(offset, offset + value.length).toString('ascii') === value;
+}
+
+function detectImageMimeType(header: Buffer): string | null {
+  if (
+    header.length >= 8 &&
+    header[0] === 0x89 &&
+    hasAscii(header, 1, 'PNG') &&
+    header[4] === 0x0d &&
+    header[5] === 0x0a &&
+    header[6] === 0x1a &&
+    header[7] === 0x0a
+  ) {
+    return 'image/png';
+  }
+
+  if (header.length >= 3 && header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff) {
+    return 'image/jpeg';
+  }
+
+  if (header.length >= 6 && (hasAscii(header, 0, 'GIF87a') || hasAscii(header, 0, 'GIF89a'))) {
+    return 'image/gif';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 0, 'RIFF') && hasAscii(header, 8, 'WEBP')) {
+    return 'image/webp';
+  }
+
+  if (header.length >= 2 && hasAscii(header, 0, 'BM')) {
+    return 'image/bmp';
+  }
+
+  if (
+    header.length >= 4 &&
+    header[0] === 0x00 &&
+    header[1] === 0x00 &&
+    (header[2] === 0x01 || header[2] === 0x02) &&
+    header[3] === 0x00
+  ) {
+    return 'image/x-icon';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 4, 'ftyp')) {
+    const brandArea = header.subarray(8, Math.min(header.length, 32)).toString('ascii');
+    if (brandArea.includes('avif') || brandArea.includes('avis')) return 'image/avif';
+  }
+
+  const text = header.toString('utf8').replace(/^\uFEFF/, '').trimStart().toLowerCase();
+  if (text.startsWith('<svg') || (text.startsWith('<?xml') && text.includes('<svg'))) {
+    return 'image/svg+xml';
+  }
+
+  return null;
+}
+
+export function validateLocalImageFile(path: string): { mimeType: string } {
+  const name = fileName(path);
+  if (!existsSync(path)) {
+    throw new Error(`Invalid image node: "${name}" does not exist.`);
+  }
+
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    throw new Error(`Invalid image node: "${name}" is not a regular file.`);
+  }
+  if (stat.size <= 0) {
+    throw new Error(`Invalid image node: "${name}" is empty.`);
+  }
+
+  const ext = name.split('.').pop()?.toLowerCase() ?? '';
+  if (!IMAGE_MIME_MAP[ext]) {
+    throw new Error(
+      `Invalid image node: "${name}" has unsupported extension ".${ext}". ` +
+        `Accepted: ${Object.keys(IMAGE_MIME_MAP).join(', ')}. ` +
+        'For non-image files use type="file" (live viewer) or type="webpage" (URL) instead.',
+    );
+  }
+
+  assertNotCloudPlaceholder(path);
+  const header = readHeaderWithTimeout(path, stat.size);
+  const mimeType = detectImageMimeType(header);
+  if (!mimeType) {
+    throw new Error(
+      `Invalid image node: "${name}" is not a recognized image file. ` +
+        'Expected PNG, JPEG, GIF, SVG, WebP, BMP, ICO, or AVIF image bytes.',
+    );
+  }
+
+  return { mimeType };
+}

package/src/server/index.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
 import type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
+import { findCanvasExtAppNodeId } from './ext-app-lookup.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
 import { searchNodes, buildSpatialContext } from './spatial-analysis.js';
@@ -440,18 +441,10 @@ export class PmxCanvas extends EventEmitter {
   }
 
   private 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 null;
+    return findCanvasExtAppNodeId(toolCallId, {
+      getNode: (id) => canvasState.getNode(id),
+      listNodes: () => canvasState.getLayout().nodes,
+    });
   }
 
   describeSchema() {
@@ -488,20 +481,21 @@ export class PmxCanvas extends EventEmitter {
     y?: number;
     width?: number;
     height?: number;
-  }): Promise<{ ok: true; nodeId: string | null; toolCallId: string; sessionId: string; resourceUri: string }> {
+  }): Promise<{ ok: true; id?: string; nodeId: string | null; toolCallId: string; sessionId: string; resourceUri: string }> {
     const opened = await openExternalMcpApp({
       transport: input.transport,
       toolName: input.toolName,
       ...(input.toolArguments ? { toolArguments: input.toolArguments } : {}),
       ...(input.serverName ? { serverName: input.serverName } : {}),
     });
-    const toolCallId = `ext-app-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const toolCallId = `${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,
+      nodeId: nodeIdSeed,
       title: input.title ?? opened.tool.title ?? opened.tool.name,
       html: opened.html,
       toolInput: opened.toolInput,
@@ -521,6 +515,7 @@ export class PmxCanvas extends EventEmitter {
     });
     emitPrimaryWorkbenchEvent('ext-app-result', {
       toolCallId,
+      nodeId: nodeIdSeed,
       serverName: opened.serverName,
       toolName: opened.toolName,
       success: toolResult.isError !== true,
@@ -529,6 +524,7 @@ export class PmxCanvas extends EventEmitter {
     const nodeId = this.findCanvasExtAppNodeId(toolCallId);
     return {
       ok: true,
+      ...(nodeId ? { id: nodeId } : {}),
       nodeId,
       toolCallId,
       sessionId: opened.sessionId,
@@ -538,7 +534,7 @@ export class PmxCanvas extends EventEmitter {
 
   async addDiagram(
     input: DiagramPresetOpenInput,
-  ): Promise<{ ok: true; nodeId: string | null; toolCallId: string; sessionId: string; resourceUri: string }> {
+  ): Promise<{ ok: true; id?: string; nodeId: string | null; toolCallId: string; sessionId: string; resourceUri: string }> {
     const built = buildExcalidrawOpenMcpAppInput(input);
     return this.openMcpApp(built);
   }

package/src/server/server.ts

@@ -36,6 +36,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
 import * as marked from 'marked';
 import type {
@@ -46,6 +47,7 @@ import type {
   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 {
@@ -66,6 +68,7 @@ import { diffLayouts, formatDiff, mutationHistory } from './mutation-history.js'
 import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   addCanvasEdge,
@@ -602,31 +605,42 @@ 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 null;
+  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 ||
-      result.content.some((entry) => entry.type !== 'text' || entry.text !== 'ok'),
-  );
+  return Boolean(result.isError || result.structuredContent);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -1079,7 +1093,7 @@ async function handleCanvasViewport(req: Request): Promise<Response> {
 }
 
 // ── Serve image file for image nodes ─────────────────────────
-function handleCanvasImage(pathname: string): Response {
+async function handleCanvasImage(pathname: string): Promise<Response> {
   const nodeId = pathname.replace('/api/canvas/image/', '');
   const node = canvasState.getNode(nodeId);
   if (!node || node.type !== 'image') {
@@ -1093,9 +1107,13 @@ function handleCanvasImage(pathname: string): Response {
   if (!existsSync(safePath)) {
     return responseText('Image file not found', 404);
   }
-  const ext = safePath.split('.').pop()?.toLowerCase() ?? '';
-  const contentType = IMAGE_MIME_MAP[ext] || 'application/octet-stream';
-  const data = readFileSync(safePath);
+  let contentType: string;
+  try {
+    contentType = validateLocalImageFile(safePath).mimeType;
+  } catch (error) {
+    return responseText(error instanceof Error ? error.message : 'Invalid image file', 400);
+  }
+  const data = await readFile(safePath);
   return new Response(data, {
     headers: {
       'Content-Type': contentType,
@@ -1545,10 +1563,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 } : {}),
       },
     }));
@@ -1871,7 +1901,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 {
@@ -1951,7 +1981,7 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
     });
 
     const toolCallId = randomExtAppToolCallId();
-    const nodeIdSeed = `ext-app-${toolCallId}`;
+    const nodeIdSeed = toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`;
     const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
       ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
       : opened.toolResult;
@@ -1959,6 +1989,7 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
 
     emitPrimaryWorkbenchEvent('ext-app-open', {
       toolCallId,
+      nodeId: nodeIdSeed,
       title: nodeTitle,
       html: opened.html,
       toolInput: opened.toolInput,
@@ -1978,6 +2009,7 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
     });
     emitPrimaryWorkbenchEvent('ext-app-result', {
       toolCallId,
+      nodeId: nodeIdSeed,
       serverName: opened.serverName,
       toolName: opened.toolName,
       success: toolResult.isError !== true,
@@ -1987,6 +2019,7 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
 
     return responseJson({
       ok: true,
+      ...(nodeId ? { id: nodeId } : {}),
       nodeId,
       toolCallId,
       sessionId: opened.sessionId,
@@ -3151,10 +3184,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() }
         : {}),
@@ -3222,7 +3258,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)
@@ -3235,7 +3273,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)
@@ -3739,7 +3779,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           }
 
           if (url.pathname.startsWith('/api/canvas/image/') && req.method === 'GET') {
-            return handleCanvasImage(url.pathname);
+            return await handleCanvasImage(url.pathname);
           }
 
           if (url.pathname === '/api/canvas/edge' && req.method === 'POST') {

package/src/server/web-artifacts.ts

@@ -494,6 +494,7 @@ export function openWebArtifactInCanvas(input: {
       trustedDomain: true,
       sourceServer: 'pmx-canvas',
       hostMode: 'hosted',
+      viewerType: 'web-artifact',
     },
   };