pmx-canvas 0.1.14 → 0.1.15

package/src/mcp/canvas-access.ts

@@ -18,6 +18,7 @@ type OpenMcpAppResult = Awaited<ReturnType<PmxCanvas['openMcpApp']>>;
 type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
 type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
 type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
+type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
 type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
 type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
 type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
@@ -34,8 +35,11 @@ type HistoryResult = ReturnType<PmxCanvas['getHistory']>;
 type SetContextPinsResult = ReturnType<PmxCanvas['setContextPins']>;
 type RunBatchInput = Parameters<PmxCanvas['runBatch']>[0];
 type RunBatchResult = Awaited<ReturnType<PmxCanvas['runBatch']>>;
+type SnapshotListOptions = Parameters<PmxCanvas['listSnapshots']>[0];
 type SnapshotList = ReturnType<PmxCanvas['listSnapshots']>;
 type DeleteSnapshotResult = ReturnType<PmxCanvas['deleteSnapshot']>;
+type GcSnapshotsOptions = Parameters<PmxCanvas['gcSnapshots']>[0];
+type GcSnapshotsResult = ReturnType<PmxCanvas['gcSnapshots']>;
 type DiffSnapshotResult = ReturnType<PmxCanvas['diffSnapshot']>;
 type CodeGraphResult = ReturnType<PmxCanvas['getCodeGraph']>;
 type ValidationResult = ReturnType<PmxCanvas['validate']>;
@@ -97,6 +101,7 @@ export interface CanvasAccess {
   openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResult>;
   addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
   addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
+  addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
   addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
   buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
   updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
@@ -117,10 +122,11 @@ export interface CanvasAccess {
   setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove'): Promise<SetContextPinsResult>;
   getPinnedNodeIds(): Promise<string[]>;
   runBatch(operations: RunBatchInput): Promise<RunBatchResult>;
-  listSnapshots(): Promise<SnapshotList>;
+  listSnapshots(options?: SnapshotListOptions): Promise<SnapshotList>;
   saveSnapshot(name: string): Promise<CanvasSnapshot | null>;
   restoreSnapshot(id: string): Promise<{ ok: boolean }>;
   deleteSnapshot(id: string): Promise<DeleteSnapshotResult>;
+  gcSnapshots(options?: GcSnapshotsOptions): Promise<GcSnapshotsResult>;
   diffSnapshot(idOrName: string): Promise<DiffSnapshotResult>;
   getCodeGraph(): Promise<CodeGraphResult>;
   validate(): Promise<ValidationResult>;
@@ -177,6 +183,10 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.addJsonRenderNode(input);
   }
 
+  async addHtmlNode(input: AddHtmlNodeInput): Promise<string> {
+    return this.canvas.addHtmlNode(input);
+  }
+
   async addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult> {
     return this.canvas.addGraphNode(input);
   }
@@ -257,8 +267,8 @@ class LocalCanvasAccess implements CanvasAccess {
     return await this.canvas.runBatch(operations);
   }
 
-  async listSnapshots(): Promise<SnapshotList> {
-    return this.canvas.listSnapshots();
+  async listSnapshots(options?: SnapshotListOptions): Promise<SnapshotList> {
+    return this.canvas.listSnapshots(options);
   }
 
   async saveSnapshot(name: string): Promise<CanvasSnapshot | null> {
@@ -273,6 +283,10 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.deleteSnapshot(id);
   }
 
+  async gcSnapshots(options?: GcSnapshotsOptions): Promise<GcSnapshotsResult> {
+    return this.canvas.gcSnapshots(options);
+  }
+
   async diffSnapshot(idOrName: string): Promise<DiffSnapshotResult> {
     return this.canvas.diffSnapshot(idOrName);
   }
@@ -359,11 +373,11 @@ class RemoteCanvasAccess implements CanvasAccess {
   }
 
   async getLayout(): Promise<CanvasLayout> {
-    return await this.requestJson<CanvasLayout>('GET', '/api/canvas/state');
+    return await this.requestJson<CanvasLayout>('GET', '/api/canvas/state?includeBlobs=true');
   }
 
   async getNode(id: string): Promise<CanvasNodeState | undefined> {
-    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/node/${encodeURIComponent(id)}`);
+    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/node/${encodeURIComponent(id)}?includeBlobs=true`);
     if (response.status === 404) return undefined;
     const text = await response.text();
     let parsed: unknown = undefined;
@@ -415,6 +429,10 @@ class RemoteCanvasAccess implements CanvasAccess {
     return { id, url: response.url, spec: response.spec };
   }
 
+  async addHtmlNode(input: AddHtmlNodeInput): Promise<string> {
+    return await this.requestNodeId('POST', '/api/canvas/node', { type: 'html', ...input });
+  }
+
   async addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult> {
     const response = await this.requestJson<GraphNodeResponse>('POST', '/api/canvas/graph', {
       ...input,
@@ -527,8 +545,13 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<RunBatchResult>('POST', '/api/canvas/batch', { operations });
   }
 
-  async listSnapshots(): Promise<SnapshotList> {
-    return await this.requestJson<SnapshotList>('GET', '/api/canvas/snapshots');
+  async listSnapshots(options?: SnapshotListOptions): Promise<SnapshotList> {
+    const params = new URLSearchParams();
+    if (typeof options?.limit === 'number') params.set('limit', String(options.limit));
+    if (options?.query) params.set('q', options.query);
+    if (options?.all) params.set('all', 'true');
+    const query = params.size > 0 ? `?${params.toString()}` : '';
+    return await this.requestJson<SnapshotList>('GET', `/api/canvas/snapshots${query}`);
   }
 
   async saveSnapshot(name: string): Promise<CanvasSnapshot | null> {
@@ -544,6 +567,10 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<DeleteSnapshotResult>('DELETE', `/api/canvas/snapshots/${encodeURIComponent(id)}`);
   }
 
+  async gcSnapshots(options?: GcSnapshotsOptions): Promise<GcSnapshotsResult> {
+    return await this.requestJson<GcSnapshotsResult>('POST', '/api/canvas/snapshots/gc', options ?? {});
+  }
+
   async diffSnapshot(idOrName: string): Promise<DiffSnapshotResult> {
     return await this.requestJson<DiffSnapshotResult>('GET', `/api/canvas/snapshots/${encodeURIComponent(idOrName)}/diff`);
   }

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)'),
@@ -267,6 +342,8 @@ export async function startMcpServer(): Promise<void> {
       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();
@@ -297,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) }],
       };
     },
   );
@@ -554,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 } : {}),
@@ -720,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) {
@@ -750,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) }],
       };
     },
   );
@@ -1463,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) }],
       };
     },
   );
@@ -1501,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 }),
       };
     },
@@ -1586,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() }, null, 2) }],
+        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(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;
@@ -1149,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 {
@@ -1160,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 };
@@ -1170,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',