pmx-canvas 0.1.13 → 0.1.15

package/src/mcp/server.ts

@@ -165,9 +165,73 @@ function encodeBase64(bytes: Uint8Array): string {
   return Buffer.from(bytes).toString('base64');
 }
 
-async function createdNodePayload(c: CanvasAccess, id: string): Promise<Record<string, unknown>> {
+function wantsFullPayload(input: { full?: boolean; verbose?: boolean; includeData?: boolean } = {}): boolean {
+  return input.full === true || input.verbose === true || input.includeData === true;
+}
+
+function compactNodePayload(node: Awaited<ReturnType<CanvasAccess['getNode']>>): Record<string, unknown> | null {
+  if (!node) return null;
+  const serialized = serializeCanvasNode(node);
+  return {
+    id: serialized.id,
+    type: serialized.type,
+    kind: serialized.kind,
+    title: serialized.title,
+    content: serialized.content,
+    position: serialized.position,
+    size: serialized.size,
+    pinned: serialized.pinned,
+    collapsed: serialized.collapsed,
+    dockPosition: serialized.dockPosition,
+    provenance: serialized.provenance,
+  };
+}
+
+function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
+  return {
+    summary: buildSummaryFromLayout(layout, pinnedIds),
+    viewport: layout.viewport,
+    nodes: layout.nodes.map((node) => compactNodePayload(node)).filter((node): node is Record<string, unknown> => node !== null),
+    edges: layout.edges.map((edge) => ({
+      id: edge.id,
+      from: edge.from,
+      to: edge.to,
+      type: edge.type,
+      ...(edge.label ? { label: edge.label } : {}),
+      ...(edge.style ? { style: edge.style } : {}),
+      ...(edge.animated !== undefined ? { animated: edge.animated } : {}),
+    })),
+  };
+}
+
+function compactBatchValue(value: unknown): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  const record = value as Record<string, unknown>;
+  const nodeLike = typeof record.id === 'string' && typeof record.type === 'string';
+  const compact: Record<string, unknown> = {};
+  for (const key of ['ok', 'id', 'type', 'kind', 'title', 'content', 'position', 'size', 'fetch', 'error', 'from', 'to', 'groupId', 'nodeIds', 'snapshot', 'arranged', 'layout']) {
+    if (record[key] !== undefined) compact[key] = record[key];
+  }
+  if (nodeLike) return compact;
+  return record;
+}
+
+function compactBatchResult(result: { ok: boolean; results: Array<Record<string, unknown>>; refs: Record<string, unknown>; failedIndex?: number; error?: string }): Record<string, unknown> {
+  return {
+    ok: result.ok,
+    ...(result.failedIndex !== undefined ? { failedIndex: result.failedIndex } : {}),
+    ...(result.error ? { error: result.error } : {}),
+    results: result.results.map((entry) => compactBatchValue(entry)),
+    refs: Object.fromEntries(Object.entries(result.refs).map(([key, value]) => [key, compactBatchValue(value)])),
+  };
+}
+
+async function createdNodePayload(c: CanvasAccess, id: string, options: { full?: boolean; verbose?: boolean; includeData?: boolean } = {}): Promise<Record<string, unknown>> {
   const node = await c.getNode(id);
   if (!node) return { ok: true, id };
+  if (!wantsFullPayload(options)) {
+    return { ok: true, node: compactNodePayload(node), id };
+  }
   const serialized = serializeCanvasNode(node);
   return { ok: true, node: serialized, ...serialized };
 }
@@ -214,13 +278,19 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_get_layout ──────────────────────────────────────────
   server.tool(
     'canvas_get_layout',
-    'Get the full canvas state: all nodes, edges, and viewport. Call this first to understand what is on the canvas.',
-    {},
-    async () => {
+    'Get the canvas layout. Defaults to a compact agent-safe projection; pass full:true for full node data.',
+    {
+      full: z.boolean().optional().describe('Return the full layout including node data. Default false keeps responses compact.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
+    },
+    async (input) => {
       const c = await ensureCanvas();
-      const layout = serializeCanvasLayout(await c.getLayout());
+      const layout = await c.getLayout();
+      const payload = wantsFullPayload(input)
+        ? serializeCanvasLayout(layout)
+        : compactLayoutPayload(layout, await c.getPinnedNodeIds());
       return {
-        content: [{ type: 'text', text: JSON.stringify(layout, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };
     },
   );
@@ -228,19 +298,24 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_get_node ────────────────────────────────────────────
   server.tool(
     'canvas_get_node',
-    'Get a single node by ID, including its full data.',
-    { id: z.string().describe('The node ID to retrieve') },
-    async ({ id }) => {
+    'Get a single node by ID. Defaults to compact metadata; pass full:true to include full data/tool results.',
+    {
+      id: z.string().describe('The node ID to retrieve'),
+      full: z.boolean().optional().describe('Include full node data, including mcp-app tool results. Default false.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
+    },
+    async (input) => {
       const c = await ensureCanvas();
-      const node = await c.getNode(id);
+      const node = await c.getNode(input.id);
       if (!node) {
         return {
-          content: [{ type: 'text', text: `Node "${id}" not found.` }],
+          content: [{ type: 'text', text: `Node "${input.id}" not found.` }],
           isError: true,
         };
       }
+      const payload = wantsFullPayload(input) ? serializeCanvasNode(node) : compactNodePayload(node);
       return {
-        content: [{ type: 'text', text: JSON.stringify(serializeCanvasNode(node), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };
     },
   );
@@ -248,9 +323,9 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_add_node ────────────────────────────────────────────
   server.tool(
     'canvas_add_node',
-    'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, group. Dedicated node tools: json-render -> canvas_add_json_render_node, graph -> canvas_add_graph_node, web-artifact -> canvas_build_web_artifact, external apps -> canvas_open_mcp_app, groups -> canvas_create_group. Call canvas_describe_schema for the full nodeTypeRouting table.',
+    'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, html, group. Dedicated node tools: json-render -> canvas_add_json_render_node, graph -> canvas_add_graph_node, web-artifact -> canvas_build_web_artifact, external apps -> canvas_open_mcp_app, html (preferred) -> canvas_add_html_node, groups -> canvas_create_group. Call canvas_describe_schema for the full nodeTypeRouting table.',
     {
-      type: z.enum(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'webpage', 'mcp-app', 'group'])
+      type: z.enum(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'webpage', 'mcp-app', 'html', 'group'])
         .describe('Node type (prefer canvas_create_group for groups)'),
       title: z.string().optional().describe('Node title'),
       content: z.string().optional().describe('Node content (markdown for markdown nodes, file path for file nodes, image path/URL/data-URI for image nodes, URL for webpage nodes)'),
@@ -261,6 +336,14 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 600)'),
       strictSize: z.boolean().optional().describe('Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting'),
+      toolName: z.string().optional().describe('Trace node tool or operation label'),
+      category: z.string().optional().describe('Trace node category: mcp, file, subagent, or other'),
+      status: z.string().optional().describe('Trace node status: running, success, or failed'),
+      duration: z.string().optional().describe('Trace node duration badge text'),
+      resultSummary: z.string().optional().describe('Trace node result summary'),
+      error: z.string().optional().describe('Trace node error message'),
+      full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
     async (input) => {
       const c = await ensureCanvas();
@@ -291,7 +374,39 @@ export async function startMcpServer(): Promise<void> {
         : input;
       const id = await c.addNode(nodeInput);
       return {
-        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id, input), null, 2) }],
+      };
+    },
+  );
+
+  // ── canvas_add_html_node ────────────────────────────────────────
+  server.tool(
+    'canvas_add_html_node',
+    'Add an html node: a self-contained HTML document (with optional inline <script> and CDN <script src="...">) rendered inside a sandboxed iframe (sandbox="allow-scripts"). Use this for moderate-complexity visualizations or interactive widgets that need real JS but do not warrant a full React/shadcn build. The iframe inherits canvas theme tokens via injected CSS custom properties (both --c-* and common --color-* aliases) so authored HTML using var(--color-text-secondary), var(--color-bg), etc. renders cohesively. No same-origin access; no top-navigation; no forms. For declarative-only views with zero JS, prefer canvas_add_json_render_node. For React + shadcn + routing or multi-component apps, use canvas_build_web_artifact.',
+    {
+      html: z.string().describe('HTML document or fragment. Full <html>...</html> documents are passed through with theme styles injected into <head>; bare fragments are wrapped in a minimal document. Inline <script> and remote CDN <script src="..."> are allowed.'),
+      title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
+      x: z.number().optional().describe('X position (auto-placed if omitted).'),
+      y: z.number().optional().describe('Y position (auto-placed if omitted).'),
+      width: z.number().optional().describe('Width in pixels (default: 720).'),
+      height: z.number().optional().describe('Height in pixels (default: 640).'),
+      strictSize: z.boolean().optional().describe('Keep explicit width/height fixed; iframe scrolls overflow internally.'),
+      full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      const id = await c.addHtmlNode({
+        html: input.html,
+        ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        ...(typeof input.x === 'number' ? { x: input.x } : {}),
+        ...(typeof input.y === 'number' ? { y: input.y } : {}),
+        ...(typeof input.width === 'number' ? { width: input.width } : {}),
+        ...(typeof input.height === 'number' ? { height: input.height } : {}),
+        ...(input.strictSize === true ? { strictSize: true } : {}),
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id, input), null, 2) }],
       };
     },
   );
@@ -303,11 +418,13 @@ export async function startMcpServer(): Promise<void> {
       toolName: z.string().describe('Tool name on the external MCP server'),
       serverName: z.string().optional().describe('Optional display name for the external MCP server'),
       toolArguments: z.record(z.string(), z.unknown()).optional().describe('Arguments passed to the external tool call'),
+      nodeId: z.string().optional().describe('Existing mcp-app node ID to update in place instead of creating a new node.'),
       title: z.string().optional().describe('Optional canvas node title override'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 500)'),
+      timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for cold external app servers'),
       transport: z.union([
         z.object({
           type: z.literal('stdio'),
@@ -331,11 +448,13 @@ export async function startMcpServer(): Promise<void> {
           toolName: input.toolName,
           ...(typeof input.serverName === 'string' ? { serverName: input.serverName } : {}),
           ...(input.toolArguments ? { toolArguments: input.toolArguments } : {}),
+          ...(typeof input.nodeId === 'string' ? { nodeId: input.nodeId } : {}),
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
           ...(typeof input.width === 'number' ? { width: input.width } : {}),
           ...(typeof input.height === 'number' ? { height: input.height } : {}),
+          ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
         });
         return {
           content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -357,27 +476,37 @@ export async function startMcpServer(): Promise<void> {
         z.string().describe('JSON array string of Excalidraw elements'),
         z.array(z.record(z.string(), z.unknown())).describe('Array of Excalidraw elements'),
       ]).describe('Excalidraw elements to render. See https://github.com/excalidraw/excalidraw-mcp for the element format.'),
+      nodeId: z.string().optional().describe('Existing Excalidraw mcp-app node ID to update in place instead of creating a new node.'),
       title: z.string().optional().describe('Optional canvas node title override'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 500)'),
+      timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for Excalidraw cold starts. Client-side MCP hosts may still enforce their own total request timeout.'),
     },
-    async (input) => {
+    async (input, extra) => {
       const c = await ensureCanvas();
       try {
         const result = await c.addDiagram({
           elements: input.elements,
+          ...(typeof input.nodeId === 'string' ? { nodeId: input.nodeId } : {}),
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
           ...(typeof input.width === 'number' ? { width: input.width } : {}),
           ...(typeof input.height === 'number' ? { height: input.height } : {}),
+          ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
         });
         return {
           content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
       } catch (error) {
+        if (extra.signal.aborted) {
+          return {
+            content: [{ type: 'text', text: 'canvas_add_diagram was cancelled by the MCP client before Excalidraw finished. Retry with a higher client request timeout and pass timeoutMs to PMX Canvas for the downstream Excalidraw call.' }],
+            isError: true,
+          };
+        }
         return {
           content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
           isError: true,
@@ -534,7 +663,10 @@ export async function startMcpServer(): Promise<void> {
               bytes: result.fileSize,
               projectPath: result.projectPath,
               openedInCanvas: result.openedInCanvas,
+              startedAt: result.startedAt,
               completedAt: result.completedAt,
+              durationMs: result.durationMs,
+              timeoutMs: result.timeoutMs,
               // `id` only present when a canvas node was actually created.
               // See the matching block in src/server/server.ts handleCanvasBuildWebArtifact.
               ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
@@ -700,10 +832,19 @@ export async function startMcpServer(): Promise<void> {
       xKey: z.string().optional().describe('Graph x/category key'),
       yKey: z.string().optional().describe('Graph y/value key'),
       chartHeight: z.number().optional().describe('Graph chart content height, distinct from node height'),
+      toolName: z.string().optional().describe('Trace node tool or operation label'),
+      category: z.string().optional().describe('Trace node category: mcp, file, subagent, or other'),
+      status: z.string().optional().describe('Trace node status: running, success, or failed'),
+      duration: z.string().optional().describe('Trace node duration badge text'),
+      resultSummary: z.string().optional().describe('Trace node result summary'),
+      error: z.string().optional().describe('Trace node error message'),
       collapsed: z.boolean().optional().describe('Collapse or expand the node'),
       arrangeLocked: z.boolean().optional().describe('Prevent auto-arrange from moving this node. Pinned nodes are also skipped.'),
+      full: z.boolean().optional().describe('Return the full updated node payload. Default false returns compact metadata.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
-    async ({ id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, arrangeLocked }) => {
+    async (input) => {
+      const { id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, arrangeLocked, toolName, category, status, duration, resultSummary, error } = input;
       const c = await ensureCanvas();
       const node = await c.getNode(id);
       if (!node) {
@@ -730,13 +871,19 @@ export async function startMcpServer(): Promise<void> {
       if (xKey !== undefined) patch.xKey = xKey;
       if (yKey !== undefined) patch.yKey = yKey;
       if (chartHeight !== undefined) patch.chartHeight = chartHeight;
+      if (toolName !== undefined) patch.toolName = toolName;
+      if (category !== undefined) patch.category = category;
+      if (status !== undefined) patch.status = status;
+      if (duration !== undefined) patch.duration = duration;
+      if (resultSummary !== undefined) patch.resultSummary = resultSummary;
+      if (error !== undefined) patch.error = error;
       if (arrangeLocked !== undefined) {
         patch.arrangeLocked = arrangeLocked;
       }
       await c.updateNode(id, patch);
       const updated = await c.getNode(id);
       return {
-        content: [{ type: 'text', text: JSON.stringify(updated ? await createdNodePayload(c, id) : { ok: true, id }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(updated ? await createdNodePayload(c, id, input) : { ok: true, id }, null, 2) }],
       };
     },
   );
@@ -1443,12 +1590,14 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width (auto-computed from children if omitted)'),
       height: z.number().optional().describe('Height (auto-computed from children if omitted)'),
       childLayout: z.enum(['grid', 'column', 'flow']).optional().describe('Optional child auto-layout. Omit to preserve current child positions.'),
+      full: z.boolean().optional().describe('Return the full created group payload. Default false returns compact metadata.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
     async (input) => {
       const c = await ensureCanvas();
       const id = await c.createGroup(input);
       return {
-        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id, input), null, 2) }],
       };
     },
   );
@@ -1481,12 +1630,15 @@ export async function startMcpServer(): Promise<void> {
         assign: z.string().optional().describe('Optional reference name for later operations'),
         args: z.record(z.string(), z.unknown()).optional().describe('Operation arguments'),
       })).describe('Ordered array of batch operations'),
+      full: z.boolean().optional().describe('Return full batch operation results. Default false compacts node-like payloads.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
-    async ({ operations }) => {
+    async (input) => {
       const c = await ensureCanvas();
-      const result = await c.runBatch(operations);
+      const result = await c.runBatch(input.operations);
+      const payload = wantsFullPayload(input) ? result : compactBatchResult(result);
       return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         ...(result.ok ? {} : { isError: true }),
       };
     },
@@ -1566,12 +1718,33 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_list_snapshots ───────────────────────────────────
   server.tool(
     'canvas_list_snapshots',
-    'List all saved canvas snapshots with IDs, names, timestamps, and node/edge counts.',
-    {},
-    async () => {
+    'List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
+    {
+      limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
+      query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
+      all: z.boolean().optional().describe('Return all snapshots instead of the default limit'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ snapshots: await c.listSnapshots(input) }, null, 2) }],
+      };
+    },
+  );
+
+  // ── canvas_gc_snapshots ─────────────────────────────────────
+  server.tool(
+    'canvas_gc_snapshots',
+    'Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
+    {
+      keep: z.number().optional().describe('Number of newest snapshots to keep (default: 20)'),
+      dryRun: z.boolean().optional().describe('Preview deletions without removing snapshot files'),
+    },
+    async (input) => {
       const c = await ensureCanvas();
+      const result = await c.gcSnapshots(input);
       return {
-        content: [{ type: 'text', text: JSON.stringify({ snapshots: await c.listSnapshots() }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };
     },
   );

package/src/server/agent-context.ts

@@ -1,4 +1,5 @@
 import type { CanvasNodeState } from './canvas-state.js';
+import { getCanvasNodeKind } from '../shared/canvas-node-kind.js';
 
 const DEFAULT_CONTEXT_TEXT_LENGTH = 700;
 const DEFAULT_WEBPAGE_CONTEXT_TEXT_LENGTH = 1600;
@@ -6,6 +7,7 @@ const DEFAULT_WEBPAGE_CONTEXT_TEXT_LENGTH = 1600;
 export interface AgentContextNode {
   id: string;
   type: CanvasNodeState['type'];
+  kind: string;
   title: string | null;
   content: string | null;
   metadata?: Record<string, unknown>;
@@ -118,6 +120,41 @@ function summarizeMcpAppData(data: Record<string, unknown>, maxLength: number):
   return truncateContextText(parts.join('\n'), maxLength);
 }
 
+function summarizeWebArtifactData(data: Record<string, unknown>, maxLength: number): string {
+  const parts: string[] = [];
+  const content = typeof data.content === 'string' ? data.content : '';
+  const title = typeof data.title === 'string' ? data.title : '';
+  const path = typeof data.path === 'string' ? data.path : '';
+  const url = typeof data.url === 'string' ? data.url : '';
+  const projectPath = typeof data.projectPath === 'string' ? data.projectPath : '';
+  const artifactBytes = typeof data.artifactBytes === 'number' ? data.artifactBytes : null;
+  const sourceFileCount = typeof data.sourceFileCount === 'number' ? data.sourceFileCount : null;
+  const sourceFiles = Array.isArray(data.sourceFiles)
+    ? data.sourceFiles.filter((file): file is string => typeof file === 'string')
+    : [];
+  const deps = Array.isArray(data.deps)
+    ? data.deps.filter((dep): dep is string => typeof dep === 'string')
+    : [];
+
+  if (content) parts.push(content);
+  if (!content && title) parts.push(`Web artifact: ${title}`);
+  if (sourceFiles.length > 0 && !content.includes('Source files:')) {
+    const remaining = sourceFileCount !== null ? Math.max(0, sourceFileCount - sourceFiles.length) : 0;
+    parts.push(`Source files: ${sourceFiles.join(', ')}${remaining > 0 ? `, +${remaining} more` : ''}`);
+  }
+  if (artifactBytes !== null && !content.includes('Artifact bytes:')) {
+    parts.push(`Artifact bytes: ${artifactBytes}`);
+  }
+  if (deps.length > 0 && !content.includes('Dependencies:')) {
+    parts.push(`Dependencies: ${deps.join(', ')}`);
+  }
+  if (path) parts.push(`Path: ${path}`);
+  if (projectPath) parts.push(`Project: ${projectPath}`);
+  if (url) parts.push(`URL: ${url}`);
+
+  return parts.length > 0 ? truncateContextText(parts.join('\n'), maxLength) : 'Web artifact node';
+}
+
 function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undefined {
   switch (node.type) {
     case 'webpage': {
@@ -146,9 +183,13 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
     }
     case 'mcp-app': {
       const metadata: Record<string, unknown> = {};
-      for (const key of ['url', 'path', 'mode', 'hostMode', 'serverName', 'toolName', 'resourceUri', 'sessionStatus']) {
+      for (const key of ['url', 'path', 'mode', 'hostMode', 'viewerType', 'serverName', 'toolName', 'resourceUri', 'sessionStatus', 'projectPath', 'artifactBytes', 'sourceFiles', 'sourceFileCount', 'deps']) {
         const value = node.data[key];
-        if (value !== undefined && value !== null && value !== '') metadata[key] = value;
+        if (Array.isArray(value)) {
+          if (value.length > 0) metadata[key] = value;
+        } else if (value !== undefined && value !== null && value !== '') {
+          metadata[key] = value;
+        }
       }
       return Object.keys(metadata).length > 0 ? metadata : undefined;
     }
@@ -170,6 +211,9 @@ export function summarizeNodeForAgentContext(
       return truncateContextText(content, defaultTextLength);
     }
     case 'mcp-app': {
+      if (node.data.viewerType === 'web-artifact') {
+        return summarizeWebArtifactData(node.data, defaultTextLength);
+      }
       const chartCfg = node.data.chartConfig as Record<string, unknown> | undefined;
       if (chartCfg) {
         const chartTitle = (chartCfg.title as string) || 'Untitled chart';
@@ -218,6 +262,7 @@ export function serializeNodeForAgentContext(
   return {
     id: node.id,
     type: node.type,
+    kind: getCanvasNodeKind(node),
     title: typeof node.data.title === 'string' ? node.data.title : null,
     content: summarizeNodeForAgentContext(node, options) || null,
     ...(metadata ? { metadata } : {}),
@@ -234,7 +279,9 @@ export function buildAgentContextPreamble(
       const title = (typeof node.data.title === 'string' && node.data.title) ? node.data.title : node.id;
       const content = summarizeNodeForAgentContext(node, options);
       if (!content) return '';
-      return `[Context from "${title}" (${node.type})]\n${content}\n`;
+      const kind = getCanvasNodeKind(node);
+      const typeLabel = kind === node.type ? node.type : `${node.type}/${kind}`;
+      return `[Context from "${title}" (${typeLabel})]\n${content}\n`;
     })
     .filter((section) => section.length > 0);
 

package/src/server/canvas-operations.ts

@@ -43,6 +43,16 @@ import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
 
+let canvasLayoutUpdateEmitter: (() => void) | null = null;
+
+export function setCanvasLayoutUpdateEmitter(emitter: (() => void) | null): void {
+  canvasLayoutUpdateEmitter = emitter;
+}
+
+function emitCanvasLayoutUpdate(): void {
+  canvasLayoutUpdateEmitter?.();
+}
+
 export interface CanvasFitViewOptions {
   width?: number;
   height?: number;
@@ -76,6 +86,12 @@ interface CanvasAddNodeInput {
   title?: string;
   content?: string;
   data?: Record<string, unknown>;
+  toolName?: string;
+  category?: string;
+  status?: string;
+  duration?: string;
+  resultSummary?: string;
+  error?: string;
   x?: number;
   y?: number;
   width?: number;
@@ -109,6 +125,7 @@ interface CanvasNodeLookupInput {
 }
 
 const MAX_CONTEXT_PINS = 20;
+const TRACE_DATA_FIELDS = ['toolName', 'category', 'status', 'duration', 'resultSummary', 'error'] as const;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -757,10 +774,23 @@ function buildWebpageNodeData(input: CanvasAddNodeInput): Record<string, unknown
   };
 }
 
+function normalizeTraceNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+  const data: Record<string, unknown> = { ...(input.data ?? {}) };
+  for (const field of TRACE_DATA_FIELDS) {
+    const value = input[field];
+    if (typeof value === 'string') data[field] = value;
+  }
+  if (input.title) data.title = input.title;
+  if (input.content) data.content = input.content;
+  if (input.strictSize) data.strictSize = true;
+  return data;
+}
+
 function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
   if (input.type === 'file') return buildFileNodeData(input);
   if (input.type === 'image') return buildImageNodeData(input);
   if (input.type === 'webpage') return buildWebpageNodeData(input);
+  if (input.type === 'trace') return normalizeTraceNodeData(input);
   return {
     ...(input.data ?? {}),
     ...(input.title ? { title: input.title } : {}),
@@ -769,6 +799,21 @@ function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
   };
 }
 
+export function mergeTraceNodeDataFields(
+  base: Record<string, unknown>,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...base };
+  for (const field of TRACE_DATA_FIELDS) {
+    if (typeof input[field] === 'string') next[field] = input[field];
+  }
+  return next;
+}
+
+export function hasTraceNodeDataFields(input: Record<string, unknown>): boolean {
+  return TRACE_DATA_FIELDS.some((field) => typeof input[field] === 'string');
+}
+
 export function scheduleCodeGraphRecompute(onComplete?: () => void): void {
   if (codeGraphTimer) clearTimeout(codeGraphTimer);
   codeGraphTimer = setTimeout(() => {
@@ -1114,8 +1159,8 @@ export function setCanvasContextPins(
   };
 }
 
-export function listCanvasSnapshots(): CanvasSnapshot[] {
-  return canvasState.listSnapshots();
+export function listCanvasSnapshots(options?: Parameters<typeof canvasState.listSnapshots>[0]): CanvasSnapshot[] {
+  return canvasState.listSnapshots(options);
 }
 
 export function saveCanvasSnapshot(name: string): CanvasSnapshot | null {
@@ -1125,7 +1170,10 @@ export function saveCanvasSnapshot(name: string): CanvasSnapshot | null {
 export async function restoreCanvasSnapshot(idOrName: string): Promise<{ ok: boolean }> {
   const ok = canvasState.restoreSnapshot(idOrName);
   if (ok) {
-    await syncCanvasRuntimeBackends({ forceRehydrateExtApps: true });
+    primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
+    void syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true }).finally(() => {
+      emitCanvasLayoutUpdate();
+    });
     canvasState.flushToDisk();
   }
   return { ok };
@@ -1135,6 +1183,10 @@ export function deleteCanvasSnapshot(id: string): { ok: boolean } {
   return { ok: canvasState.deleteSnapshot(id) };
 }
 
+export function gcCanvasSnapshots(options?: Parameters<typeof canvasState.gcSnapshots>[0]): ReturnType<typeof canvasState.gcSnapshots> {
+  return canvasState.gcSnapshots(options);
+}
+
 export function addCanvasEdge(input: {
   from?: string;
   to?: string;

package/src/server/canvas-provenance.ts

@@ -14,6 +14,7 @@ export type CanvasNodeType =
   | 'trace'
   | 'file'
   | 'image'
+  | 'html'
   | 'group';
 
 export type CanvasNodeProvenanceSourceKind =
@@ -199,7 +200,7 @@ function inferMcpAppProvenance(data: Record<string, unknown>): CanvasNodeProvena
   if (resourceUri) details.resourceUri = resourceUri;
   const transportType = isRecord(data.transportConfig) ? pickString(data.transportConfig.type) : null;
   if (transportType) details.transportType = transportType;
-  if (isRecord(data.toolInput)) details.toolInput = data.toolInput;
+  if (isRecord(data.toolInput) && data.toolInput.__pmxCanvasBlob !== 'v1') details.toolInput = data.toolInput;
 
   return {
     sourceKind: 'mcp-tool',