pmx-canvas 0.1.13 → 0.1.15

package/src/server/server.ts

@@ -65,7 +65,13 @@ import {
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
 import { searchNodes, buildSpatialContext } from './spatial-analysis.js';
 import { diffLayouts, formatDiff, mutationHistory } from './mutation-history.js';
-import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from './canvas-serialization.js';
+import {
+  buildCanvasSummary,
+  serializeCanvasLayout,
+  serializeCanvasLayoutWithBlobSummaries,
+  serializeCanvasNode,
+  serializeCanvasNodeWithBlobSummaries,
+} from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
 import { validateLocalImageFile } from './image-source.js';
@@ -82,6 +88,7 @@ import {
   deleteCanvasSnapshot,
   executeCanvasBatch,
   fitCanvasView,
+  gcCanvasSnapshots,
   groupCanvasNodes,
   listCanvasSnapshots,
   refreshCanvasWebpageNode,
@@ -91,11 +98,14 @@ import {
   saveCanvasSnapshot,
   scheduleCodeGraphRecompute,
   primeCanvasRuntimeBackends,
+  setCanvasLayoutUpdateEmitter,
   syncCanvasRuntimeBackends,
   setCanvasContextPins,
   ungroupCanvasNodes,
   validateCanvasNodePatch,
   hasStructuredNodeUpdateFields,
+  hasTraceNodeDataFields,
+  mergeTraceNodeDataFields,
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
@@ -1184,7 +1194,15 @@ function serveCanvasFavicon(): Response {
 async function handleCanvasUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const updates = Array.isArray(body.updates) ? body.updates : [];
-  const result = applyCanvasNodeUpdates(updates);
+  const result = body.recordHistory === false
+    ? (() => {
+        let suppressedResult: ReturnType<typeof applyCanvasNodeUpdates> = { applied: 0, skipped: updates.length };
+        canvasState.withSuppressedRecording(() => {
+          suppressedResult = applyCanvasNodeUpdates(updates);
+        });
+        return suppressedResult;
+      })()
+    : applyCanvasNodeUpdates(updates);
   if (result.applied > 0) {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
@@ -1234,7 +1252,7 @@ async function handleCanvasImage(pathname: string): Promise<Response> {
 }
 
 // ── Add node from client ─────────────────────────────────────
-const VALID_NODE_TYPES = new Set(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'mcp-app', 'webpage', 'group']);
+const VALID_NODE_TYPES = new Set(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'mcp-app', 'webpage', 'html', 'group']);
 
 function buildNodeResponse(node: CanvasNodeState): Record<string, unknown> {
   const serialized = serializeCanvasNode(node);
@@ -1323,6 +1341,11 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const content = type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string'
     ? body.path
     : body.content;
+  // For html nodes, accept top-level `html` field and merge into data so callers
+  // can POST { type: 'html', title, html } without nesting under `data`.
+  const htmlMergedData = type === 'html' && typeof body.html === 'string'
+    ? { ...(extraData ?? {}), html: body.html }
+    : extraData;
   let added: ReturnType<typeof addCanvasNode>;
   const geometry = resolveCreateGeometry(body);
   try {
@@ -1330,11 +1353,17 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
       type: type as CanvasNodeState['type'],
       ...(typeof body.title === 'string' ? { title: body.title } : {}),
       ...(typeof content === 'string' ? { content } : {}),
-      ...(extraData ? { data: extraData } : {}),
+      ...(htmlMergedData ? { data: htmlMergedData } : {}),
+      ...(type === 'trace' && typeof body.toolName === 'string' ? { toolName: body.toolName } : {}),
+      ...(type === 'trace' && typeof body.category === 'string' ? { category: body.category } : {}),
+      ...(type === 'trace' && typeof body.status === 'string' ? { status: body.status } : {}),
+      ...(type === 'trace' && typeof body.duration === 'string' ? { duration: body.duration } : {}),
+      ...(type === 'trace' && typeof body.resultSummary === 'string' ? { resultSummary: body.resultSummary } : {}),
+      ...(type === 'trace' && typeof body.error === 'string' ? { error: body.error } : {}),
       ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
-      defaultWidth: 360,
-      defaultHeight: 200,
+      defaultWidth: type === 'html' ? 720 : 360,
+      defaultHeight: type === 'html' ? 640 : 200,
       fileMode: 'auto',
     });
   } catch (error) {
@@ -1495,7 +1524,14 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
     } catch (error) {
       return responseJson({ ok: false, error: error instanceof Error ? error.message : String(error) }, 400);
     }
-  } else if (body.title !== undefined || body.content !== undefined || body.data || typeof body.arrangeLocked === 'boolean' || typeof body.strictSize === 'boolean') {
+  } else if (
+    body.title !== undefined ||
+    body.content !== undefined ||
+    body.data ||
+    typeof body.arrangeLocked === 'boolean' ||
+    typeof body.strictSize === 'boolean' ||
+    (existing.type === 'trace' && hasTraceNodeDataFields(body))
+  ) {
     const data = { ...existing.data };
     if (body.title !== undefined) {
       data.title = String(body.title);
@@ -1524,7 +1560,9 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
         }
       }
     }
-    patch.data = data;
+    patch.data = existing.type === 'trace'
+      ? mergeTraceNodeDataFields(data, body)
+      : data;
   }
   const error = validateCanvasNodePatch({
     ...(patch.position ? { position: patch.position as { x: number; y: number } } : {}),
@@ -1639,7 +1677,10 @@ async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
       bytes: result.fileSize,
       projectPath: result.projectPath,
       openedInCanvas: result.openedInCanvas,
+      startedAt: result.startedAt,
       completedAt: result.completedAt,
+      durationMs: result.durationMs,
+      timeoutMs: result.timeoutMs,
       // `id` is the canvas node id alias used by every other add-style
       // response. It is only present when a canvas node was actually
       // created (i.e. openInCanvas was not explicitly disabled). When
@@ -1888,6 +1929,13 @@ function responseText(text: string, status = 400): Response {
   });
 }
 
+function parsePositiveIntegerParam(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return Math.floor(parsed);
+}
+
 function handleArtifactView(url: URL): Response {
   const pathLike = url.searchParams.get('path') ?? '';
   const safePath = resolveWorkspaceArtifactPath(pathLike);
@@ -2111,29 +2159,44 @@ interface RunAndEmitOpenMcpAppParams {
   transport: ExternalMcpTransportConfig;
   toolName: string;
   toolArguments?: Record<string, unknown>;
+  nodeId?: string;
   serverName?: string;
   title?: string;
   x?: number;
   y?: number;
   width?: number;
   height?: number;
+  timeoutMs?: number;
 }
 
 async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise<Response> {
   try {
+    const targetNode = params.nodeId ? canvasState.getNode(params.nodeId) : undefined;
+    if (params.nodeId && !targetNode) {
+      return responseJson({ ok: false, error: `Node "${params.nodeId}" not found.` }, 404);
+    }
+    if (targetNode && (targetNode.type !== 'mcp-app' || targetNode.data.mode !== 'ext-app')) {
+      return responseJson({ ok: false, error: `Node "${params.nodeId}" is not an external app node.` }, 400);
+    }
+
     const opened = await openMcpApp({
       transport: params.transport,
       toolName: params.toolName,
       ...(params.toolArguments ? { toolArguments: params.toolArguments } : {}),
       ...(params.serverName ? { serverName: params.serverName } : {}),
+      ...(typeof params.timeoutMs === 'number' ? { timeoutMs: params.timeoutMs } : {}),
     });
 
     const toolCallId = randomExtAppToolCallId();
-    const nodeIdSeed = toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`;
+    if (params.nodeId) closeNodeAppSession(targetNode);
+    const nodeIdSeed = params.nodeId ?? (toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`);
     const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
       ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
       : opened.toolResult;
-    const nodeTitle = params.title ?? opened.tool.title ?? opened.tool.name;
+    const nodeTitle = params.title
+      ?? (typeof targetNode?.data.title === 'string' ? targetNode.data.title : undefined)
+      ?? opened.tool.title
+      ?? opened.tool.name;
 
     emitPrimaryWorkbenchEvent('ext-app-open', {
       toolCallId,
@@ -2163,7 +2226,7 @@ async function runAndEmitOpenMcpApp(params: RunAndEmitOpenMcpAppParams): Promise
       success: toolResult.isError !== true,
       result: toolResult,
     });
-    const nodeId = findCanvasExtAppNodeId(toolCallId);
+    const nodeId = params.nodeId ?? findCanvasExtAppNodeId(toolCallId);
 
     return responseJson({
       ok: true,
@@ -2202,17 +2265,22 @@ async function handleCanvasOpenMcpApp(req: Request): Promise<Response> {
   const requestedServerName = typeof body.serverName === 'string' && body.serverName.trim().length > 0
     ? body.serverName.trim()
     : undefined;
+  const requestedNodeId = typeof body.nodeId === 'string' && body.nodeId.trim().length > 0
+    ? body.nodeId.trim()
+    : undefined;
 
   return runAndEmitOpenMcpApp({
     transport,
     toolName,
     ...(toolArguments ? { toolArguments } : {}),
+    ...(requestedNodeId ? { nodeId: requestedNodeId } : {}),
     ...(requestedServerName ? { serverName: requestedServerName } : {}),
     ...(requestedTitle ? { title: requestedTitle } : {}),
     ...(typeof body.x === 'number' ? { x: body.x } : {}),
     ...(typeof body.y === 'number' ? { y: body.y } : {}),
     ...(typeof body.width === 'number' ? { width: body.width } : {}),
     ...(typeof body.height === 'number' ? { height: body.height } : {}),
+    ...(typeof body.timeoutMs === 'number' ? { timeoutMs: body.timeoutMs } : {}),
   });
 }
 
@@ -2222,11 +2290,13 @@ async function handleCanvasAddDiagram(req: Request): Promise<Response> {
   try {
     built = buildExcalidrawOpenMcpAppInput({
       elements: body.elements,
+      ...(typeof body.nodeId === 'string' ? { nodeId: body.nodeId } : {}),
       ...(typeof body.title === 'string' ? { title: body.title } : {}),
       ...(typeof body.x === 'number' ? { x: body.x } : {}),
       ...(typeof body.y === 'number' ? { y: body.y } : {}),
       ...(typeof body.width === 'number' ? { width: body.width } : {}),
       ...(typeof body.height === 'number' ? { height: body.height } : {}),
+      ...(typeof body.timeoutMs === 'number' ? { timeoutMs: body.timeoutMs } : {}),
     });
   } catch (error) {
     return responseJson({
@@ -2239,11 +2309,13 @@ async function handleCanvasAddDiagram(req: Request): Promise<Response> {
     toolName: built.toolName,
     toolArguments: built.toolArguments,
     serverName: built.serverName,
+    ...(built.nodeId ? { nodeId: built.nodeId } : {}),
     ...(built.title ? { title: built.title } : {}),
     ...(typeof built.x === 'number' ? { x: built.x } : {}),
     ...(typeof built.y === 'number' ? { y: built.y } : {}),
     ...(typeof built.width === 'number' ? { width: built.width } : {}),
     ...(typeof built.height === 'number' ? { height: built.height } : {}),
+    ...(typeof built.timeoutMs === 'number' ? { timeoutMs: built.timeoutMs } : {}),
   });
 }
 
@@ -3044,6 +3116,18 @@ async function handleSnapshotSave(req: Request): Promise<Response> {
   return responseJson({ ok: true, id: snapshot.id, snapshot });
 }
 
+async function handleSnapshotGc(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const keepValue = body.keep;
+  const keep = typeof keepValue === 'number'
+    ? keepValue
+    : typeof keepValue === 'string'
+      ? Number(keepValue)
+      : undefined;
+  const dryRun = body.dryRun === true || body['dry-run'] === true;
+  return responseJson(gcCanvasSnapshots({ keep, dryRun }));
+}
+
 async function handleContextPinsUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const MAX_PINS = 20;
@@ -3284,9 +3368,9 @@ function syncContextNodeToCanvasState(
       position: { x: 1130, y: 80 },
       size: { width: 320, height: 400 },
       zIndex: 1,
-      collapsed: false,
+      collapsed: true,
       pinned: false,
-      dockPosition: null,
+      dockPosition: 'right',
       data: mergedData,
     });
     return;
@@ -3408,52 +3492,56 @@ 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)
-        : null);
-    if (!id) return;
-    const existing = canvasState.getNode(id);
-    if (existing) {
-      canvasState.updateNode(id, { data: { ...existing.data, html: payload.html } });
-    }
+    canvasState.withSuppressedRecording(() => {
+      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)
+          : null);
+      if (!id) return;
+      const existing = canvasState.getNode(id);
+      if (existing) {
+        canvasState.updateNode(id, { data: { ...existing.data, html: payload.html } });
+      }
+    });
   } 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)
-        : null);
-    if (!id) return;
-    if (payload.success === false) {
-      closeNodeAppSession(canvasState.getNode(id));
-      canvasState.removeNode(id);
-      return;
-    }
-    const existing = canvasState.getNode(id);
-    if (existing) {
-      canvasState.updateNode(id, {
-        data: {
-          ...existing.data,
-          toolResult: normalizeExtAppToolResult({
-            result: payload.result,
-            success: typeof payload.success === 'boolean' ? payload.success : undefined,
-            error: typeof payload.error === 'string' ? payload.error : undefined,
-            content: typeof payload.content === 'string' ? payload.content : undefined,
-            detailedContent:
-              typeof payload.detailedContent === 'string' ? payload.detailedContent : undefined,
-          }),
-        },
-      });
-    }
+    canvasState.withSuppressedRecording(() => {
+      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)
+          : null);
+      if (!id) return;
+      if (payload.success === false) {
+        closeNodeAppSession(canvasState.getNode(id));
+        canvasState.removeNode(id);
+        return;
+      }
+      const existing = canvasState.getNode(id);
+      if (existing) {
+        canvasState.updateNode(id, {
+          data: {
+            ...existing.data,
+            toolResult: normalizeExtAppToolResult({
+              result: payload.result,
+              success: typeof payload.success === 'boolean' ? payload.success : undefined,
+              error: typeof payload.error === 'string' ? payload.error : undefined,
+              content: typeof payload.content === 'string' ? payload.content : undefined,
+              detailedContent:
+                typeof payload.detailedContent === 'string' ? payload.detailedContent : undefined,
+            }),
+          },
+        });
+      }
+    });
   } else if (event === 'context-cards') {
     syncContextNodeToCanvasState(
       { cards: Array.isArray(payload.cards) ? payload.cards : [] },
@@ -3755,6 +3843,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   // ── Canvas persistence: set workspace root and load saved state ──
   canvasState.setWorkspaceRoot(activeWorkspaceRoot);
   const loaded = canvasState.loadFromDisk({ clearExisting: true });
+  setCanvasLayoutUpdateEmitter(() => {
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  });
   if (loaded) {
     console.log('  Canvas state restored from .pmx-canvas/state.json');
     primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
@@ -3858,7 +3949,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
           // Canvas state API
           if (url.pathname === '/api/canvas/state' && req.method === 'GET') {
-            return responseJson(serializeCanvasLayout(canvasState.getLayout()));
+            const includeBlobs = url.searchParams.get('includeBlobs') === 'true';
+            return responseJson(includeBlobs
+              ? serializeCanvasLayout(canvasState.getLayout())
+              : serializeCanvasLayoutWithBlobSummaries(canvasState.getLayoutForPersistence()));
           }
 
           if (url.pathname === '/api/canvas/summary' && req.method === 'GET') {
@@ -3908,10 +4002,13 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           }
 
           if (url.pathname.startsWith('/api/canvas/node/') && req.method === 'GET') {
-            const nodeId = url.pathname.slice('/api/canvas/node/'.length);
-            const node = canvasState.getNode(nodeId);
+            const nodeId = decodeURIComponent(url.pathname.slice('/api/canvas/node/'.length));
+            const includeBlobs = url.searchParams.get('includeBlobs') === 'true';
+            const node = includeBlobs ? canvasState.getNode(nodeId) : canvasState.getNodeForPersistence(nodeId);
             if (!node) return responseJson({ ok: false, error: `Node "${nodeId}" not found.` }, 404);
-            return responseJson(serializeCanvasNode(node));
+            return responseJson(includeBlobs
+              ? serializeCanvasNode(node)
+              : serializeCanvasNodeWithBlobSummaries(node));
           }
 
           if (url.pathname.startsWith('/api/canvas/node/') && req.method === 'PATCH') {
@@ -3947,13 +4044,21 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
           // Snapshot API
           if (url.pathname === '/api/canvas/snapshots' && req.method === 'GET') {
-            return responseJson(listCanvasSnapshots());
+            return responseJson(listCanvasSnapshots({
+              limit: parsePositiveIntegerParam(url.searchParams.get('limit')),
+              query: url.searchParams.get('q') ?? url.searchParams.get('query') ?? undefined,
+              all: url.searchParams.get('all') === 'true',
+            }));
           }
 
           if (url.pathname === '/api/canvas/snapshots' && req.method === 'POST') {
             return handleSnapshotSave(req);
           }
 
+          if (url.pathname === '/api/canvas/snapshots/gc' && req.method === 'POST') {
+            return handleSnapshotGc(req);
+          }
+
           if (url.pathname.startsWith('/api/canvas/snapshots/') && url.pathname.endsWith('/diff') && req.method === 'GET') {
             const id = decodeURIComponent(url.pathname.slice('/api/canvas/snapshots/'.length, -'/diff'.length));
             const snapshot = canvasState.getSnapshotData(id);
@@ -4137,6 +4242,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 export function stopCanvasServer(): void {
   canvasState.flushToDisk();
   closeAllMcpAppSessions();
+  setCanvasLayoutUpdateEmitter(null);
   void closeCanvasAutomationWebViewInternal().catch((error) => {
     logWorkbenchWarning('stopCanvasServer closeCanvasAutomationWebViewInternal', error);
   });

package/src/server/web-artifacts.ts

@@ -28,6 +28,11 @@ const DEFAULT_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_PACKAGE_MANAGER = 'pnpm@10.33.0';
 const DEFAULT_WEB_ARTIFACT_NODE_SIZE = { width: 960, height: 720 };
 const FALLBACK_PATH_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'];
+const WEB_ARTIFACT_CONTEXT_MAX_LENGTH = 1200;
+const WEB_ARTIFACT_SOURCE_PREVIEW_MAX_LENGTH = 700;
+const WEB_ARTIFACT_CSS_PREVIEW_MAX_LENGTH = 260;
+const WEB_ARTIFACT_MAX_LISTED_SOURCE_FILES = 8;
+const WEB_ARTIFACT_MAX_STORED_SOURCE_FILES = 32;
 
 export interface WebArtifactBuildInput {
   title: string;
@@ -49,6 +54,7 @@ export interface WebArtifactBuildOutput {
   fileSize: number;
   projectPath: string;
   metadata: Record<string, unknown>;
+  sourceContext: WebArtifactSourceContext;
   logs?: {
     stdout?: WebArtifactLogSummary;
     stderr?: WebArtifactLogSummary;
@@ -64,6 +70,14 @@ export interface WebArtifactLogSummary {
   suppressedNoiseCount: number;
 }
 
+export interface WebArtifactSourceContext {
+  content: string;
+  sourceFiles: string[];
+  sourceFileCount: number;
+  sourcePreview: string;
+  deps?: string[];
+}
+
 export interface WebArtifactCanvasOpenResult {
   nodeId: string;
   url: string;
@@ -73,7 +87,10 @@ export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
   openedInCanvas: boolean;
   nodeId?: string;
   url?: string;
+  startedAt: string;
   completedAt: string;
+  durationMs: number;
+  timeoutMs: number;
 }
 
 function currentWorkspaceRoot(): string {
@@ -114,6 +131,67 @@ function slugify(value: string): string {
   return slug.length > 0 ? slug : 'web-artifact';
 }
 
+function normalizePreviewText(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t\f\v]+/g, ' ')
+    .replace(/\n\s+/g, '\n')
+    .replace(/\s+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function truncatePreviewText(text: string, maxLength: number): string {
+  if (maxLength <= 0) return '';
+  const normalized = normalizePreviewText(text);
+  if (normalized.length <= maxLength) return normalized;
+  if (maxLength <= 3) return normalized.slice(0, maxLength);
+  return `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function formatSourceFileList(files: string[]): string {
+  const visible = files.slice(0, WEB_ARTIFACT_MAX_LISTED_SOURCE_FILES);
+  const remaining = files.length - visible.length;
+  return `${visible.join(', ')}${remaining > 0 ? `, +${remaining} more` : ''}`;
+}
+
+function buildWebArtifactSourceContext(
+  input: Pick<WebArtifactBuildInput, 'title' | 'appTsx' | 'indexCss' | 'mainTsx' | 'indexHtml' | 'files'>,
+  options: { deps: string[]; fileSize: number },
+): WebArtifactSourceContext {
+  const sourceFiles = new Set<string>(['src/App.tsx']);
+  if (typeof input.indexCss === 'string') sourceFiles.add('src/index.css');
+  if (typeof input.mainTsx === 'string') sourceFiles.add('src/main.tsx');
+  if (typeof input.indexHtml === 'string') sourceFiles.add('index.html');
+  for (const pathKey of Object.keys(input.files ?? {}).sort()) {
+    sourceFiles.add(pathKey);
+  }
+
+  const appPreview = truncatePreviewText(input.appTsx, WEB_ARTIFACT_SOURCE_PREVIEW_MAX_LENGTH);
+  const cssPreview = typeof input.indexCss === 'string'
+    ? truncatePreviewText(input.indexCss, WEB_ARTIFACT_CSS_PREVIEW_MAX_LENGTH)
+    : '';
+  const allSourceFiles = [...sourceFiles];
+  const storedSourceFiles = allSourceFiles.slice(0, WEB_ARTIFACT_MAX_STORED_SOURCE_FILES);
+  const parts = [
+    `Web artifact: ${input.title}`,
+    `Source files: ${formatSourceFileList(allSourceFiles)}`,
+    `Artifact bytes: ${options.fileSize}`,
+    options.deps.length > 0 ? `Dependencies: ${options.deps.join(', ')}` : '',
+    `App source preview:\n${appPreview}`,
+    cssPreview ? `CSS source preview:\n${cssPreview}` : '',
+  ].filter(Boolean);
+
+  const content = truncatePreviewText(parts.join('\n'), WEB_ARTIFACT_CONTEXT_MAX_LENGTH);
+  return {
+    content,
+    sourceFiles: storedSourceFiles,
+    sourceFileCount: allSourceFiles.length,
+    sourcePreview: appPreview,
+    ...(options.deps.length > 0 ? { deps: options.deps } : {}),
+  };
+}
+
 function isPathInside(base: string, candidate: string): boolean {
   const rel = relative(base, candidate);
   if (rel === '') return true;
@@ -458,19 +536,23 @@ export async function executeWebArtifactBuild(
   // on a filesystem failure. A post-copy size check would be redundant
   // defensive noise — see CLAUDE.md TypeScript Guardrail #3.
   const fileSize = bundleSize;
+  const sourceContext = buildWebArtifactSourceContext(input, { deps, fileSize });
 
   return {
     filePath: outputPath,
     fileSize,
     projectPath,
+    sourceContext,
     metadata: {
       title: input.title,
       bundlePath,
       projectPath,
+      sourceFiles: sourceContext.sourceFiles,
+      sourceFileCount: sourceContext.sourceFileCount,
+      sourcePreview: sourceContext.sourcePreview,
       hasIndexCss: typeof input.indexCss === 'string',
       ...(deps.length > 0 ? { deps } : {}),
       extraFileCount: Object.keys(input.files ?? {}).length,
-      outputPreview: readFileSync(outputPath, 'utf-8').slice(0, 200),
     },
     logs: {
       ...(summarizeArtifactLog(stdout) ? { stdout: summarizeArtifactLog(stdout) } : {}),
@@ -484,6 +566,13 @@ export async function executeWebArtifactBuild(
 export function openWebArtifactInCanvas(input: {
   title: string;
   filePath: string;
+  fileSize?: number;
+  projectPath?: string;
+  content?: string;
+  sourceFiles?: string[];
+  sourceFileCount?: number;
+  sourcePreview?: string;
+  deps?: string[];
 }): WebArtifactCanvasOpenResult {
   const width = DEFAULT_WEB_ARTIFACT_NODE_SIZE.width;
   const height = DEFAULT_WEB_ARTIFACT_NODE_SIZE.height;
@@ -501,8 +590,15 @@ export function openWebArtifactInCanvas(input: {
     dockPosition: null,
     data: {
       title: input.title,
+      ...(typeof input.content === 'string' ? { content: input.content } : {}),
       url,
       path: input.filePath,
+      ...(typeof input.fileSize === 'number' ? { artifactBytes: input.fileSize } : {}),
+      ...(typeof input.projectPath === 'string' ? { projectPath: input.projectPath } : {}),
+      ...(Array.isArray(input.sourceFiles) ? { sourceFiles: input.sourceFiles } : {}),
+      ...(typeof input.sourceFileCount === 'number' ? { sourceFileCount: input.sourceFileCount } : {}),
+      ...(typeof input.sourcePreview === 'string' ? { sourcePreview: input.sourcePreview } : {}),
+      ...(Array.isArray(input.deps) && input.deps.length > 0 ? { deps: input.deps } : {}),
       trustedDomain: true,
       sourceServer: 'pmx-canvas',
       hostMode: 'hosted',
@@ -518,19 +614,36 @@ export function openWebArtifactInCanvas(input: {
 export async function buildWebArtifactOnCanvas(input: WebArtifactBuildInput & {
   openInCanvas?: boolean;
 }): Promise<WebArtifactCanvasBuildResult> {
+  const startedMs = Date.now();
+  const startedAt = new Date(startedMs).toISOString();
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const build = await executeWebArtifactBuild(input);
+  const completedMs = Date.now();
+  const timing = {
+    startedAt,
+    completedAt: new Date(completedMs).toISOString(),
+    durationMs: completedMs - startedMs,
+    timeoutMs,
+  };
   if (input.openInCanvas === false) {
-    return { ...build, openedInCanvas: false, completedAt: new Date().toISOString() };
+    return { ...build, openedInCanvas: false, ...timing };
   }
   const opened = openWebArtifactInCanvas({
     title: input.title,
     filePath: build.filePath,
+    fileSize: build.fileSize,
+    projectPath: build.projectPath,
+    content: build.sourceContext.content,
+    sourceFiles: build.sourceContext.sourceFiles,
+    sourceFileCount: build.sourceContext.sourceFileCount,
+    sourcePreview: build.sourceContext.sourcePreview,
+    ...(Array.isArray(build.sourceContext.deps) ? { deps: build.sourceContext.deps } : {}),
   });
   return {
     ...build,
     openedInCanvas: true,
     nodeId: opened.nodeId,
     url: opened.url,
-    completedAt: new Date().toISOString(),
+    ...timing,
   };
 }

package/src/shared/canvas-node-kind.ts

@@ -0,0 +1,14 @@
+export interface CanvasNodeKindInput {
+  type: string;
+  data: Record<string, unknown>;
+}
+
+export function getCanvasNodeKind(node: CanvasNodeKindInput): string {
+  if (node.type !== 'mcp-app') return node.type;
+
+  const data = node.data;
+  if (data.viewerType === 'web-artifact') return 'web-artifact';
+  if (data.mode === 'ext-app') return 'external-app';
+  if (data.hostMode === 'hosted' && typeof data.path === 'string') return 'web-artifact';
+  return 'mcp-app';
+}