pmx-canvas 0.1.23 → 0.1.25

package/src/server/server.ts

@@ -35,6 +35,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
@@ -46,7 +47,7 @@ import type {
   ListResourceTemplatesResult,
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
-import { type CanvasAnnotation, type CanvasEdge, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
@@ -75,11 +76,15 @@ import {
 } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { buildCanvasAxContext } from './ax-context.js';
+import type { PmxAxSource } from './ax-state.js';
+import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   addCanvasEdge,
   MARKDOWN_NODE_DEFAULT_SIZE,
+  MCP_APP_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   buildStructuredNodeUpdate,
   arrangeCanvasNodes,
@@ -145,9 +150,7 @@ let nextWorkbenchSubscriberId = 1;
 const workbenchSubscribers = new Map<number, ReadableStreamDefaultController<Uint8Array>>();
 const textEncoder = new TextEncoder();
 let primaryWorkbenchAutoOpenEnabled = true;
-const canvasThemeSetting = (['dark', 'light', 'high-contrast'].includes(process.env.PMX_CANVAS_THEME ?? '')
-  ? process.env.PMX_CANVAS_THEME!
-  : 'dark');
+const initialCanvasThemeSetting = normalizeCanvasTheme(process.env.PMX_CANVAS_THEME);
 let lastWorkbenchContextCardsEnvelope: Record<string, unknown> | null = null;
 
 function normalizeGraphViewerSpec(
@@ -788,6 +791,64 @@ function parseGraphPayloadData(value: unknown): Array<Record<string, unknown>> |
   return value as Array<Record<string, unknown>>;
 }
 
+type StringListField = { value?: string[]; error?: string };
+
+function parseStringListField(field: string, value: unknown): StringListField {
+  if (value === undefined) return {};
+  if (!Array.isArray(value)) return { error: `"${field}" must be an array of node IDs.` };
+  const invalid = value.find((item) => typeof item !== 'string' || item.trim().length === 0);
+  if (invalid !== undefined) return { error: `"${field}" must contain only non-empty node IDs.` };
+  return { value };
+}
+
+function pickGroupChildIds(body: Record<string, unknown>): StringListField {
+  if ('children' in body) return parseStringListField('children', body.children);
+  if ('childIds' in body) return parseStringListField('childIds', body.childIds);
+  const data = isRecord(body.data) ? body.data : undefined;
+  return data && 'children' in data ? parseStringListField('data.children', data.children) : {};
+}
+
+function validateGroupChildIds(groupId: string, childIds: string[]): string | null {
+  const missingChildIds = childIds.filter((id) => !canvasState.getNode(id));
+  if (missingChildIds.length > 0) {
+    return `Missing child node ID${missingChildIds.length === 1 ? '' : 's'}: ${missingChildIds.join(', ')}.`;
+  }
+  const invalidChildIds = childIds.filter((id) => {
+    const node = canvasState.getNode(id);
+    return id === groupId || node?.type === 'group';
+  });
+  if (invalidChildIds.length > 0) {
+    return `Invalid group child ID${invalidChildIds.length === 1 ? '' : 's'}: ${invalidChildIds.join(', ')}.`;
+  }
+  return null;
+}
+
+function setGroupChildrenFromApi(groupId: string, childIds: string[]): boolean {
+  const group = canvasState.getNode(groupId);
+  if (!group || group.type !== 'group') return false;
+
+  const dataChildIds = Array.isArray(group.data.children)
+    ? group.data.children.filter((id): id is string => typeof id === 'string')
+    : [];
+  const parentBackrefIds = canvasState.getLayout().nodes
+    .filter((node) => node.id !== groupId && node.data.parentGroup === groupId)
+    .map((node) => node.id);
+  const currentChildIds = [...new Set([...dataChildIds, ...parentBackrefIds])];
+  if (currentChildIds.length > 0) {
+    if (currentChildIds.length !== dataChildIds.length || currentChildIds.some((id) => !dataChildIds.includes(id))) {
+      canvasState.updateNode(groupId, { data: { ...group.data, children: currentChildIds } });
+    }
+    canvasState.ungroupNodes(groupId);
+  }
+  if (childIds.length === 0) return true;
+
+  const latestGroup = canvasState.getNode(groupId);
+  return canvasState.groupNodes(groupId, childIds, {
+    preservePositions: true,
+    keepGroupFrame: latestGroup?.data.frameMode === 'manual',
+  });
+}
+
 function getExtAppNodeCheckpointId(node: CanvasNodeState): string {
   const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
   const storedCheckpointId = appCheckpoint?.id;
@@ -1038,6 +1099,24 @@ function normalizeMarkdownExternalUrls(markdown: string): string {
 
 // ── Canvas SPA HTML ────────────────────────────────────────────
 
+const CANVAS_ASSET_VERSION = Date.now().toString(36);
+const MAX_FRAME_DOCUMENTS = 128;
+const MAX_FRAME_DOCUMENT_BYTES = 5 * 1024 * 1024;
+const DEFAULT_FRAME_DOCUMENT_SANDBOX = 'allow-scripts';
+const SAFE_FRAME_DOCUMENT_SANDBOX_TOKENS = new Set([
+  'allow-downloads',
+  'allow-forms',
+  'allow-modals',
+  'allow-orientation-lock',
+  'allow-pointer-lock',
+  'allow-popups',
+  'allow-popups-to-escape-sandbox',
+  'allow-presentation',
+  'allow-scripts',
+  'allow-storage-access-by-user-activation',
+]);
+const frameDocuments = new Map<string, { html: string; sandbox: string }>();
+
 function canvasSpaHtml(): string {
   return `<!doctype html>
 <html lang="en">
@@ -1106,7 +1185,7 @@ function canvasSpaHtml(): string {
       color: #eef4ff;
     }
   </style>
-  <link rel="stylesheet" href="/canvas/global.css" />
+  <link rel="stylesheet" href="/canvas/global.css?v=${CANVAS_ASSET_VERSION}" />
 </head>
 <body>
   <div id="canvasBootstrap">
@@ -1143,7 +1222,7 @@ function canvasSpaHtml(): string {
       }, 4000);
     })();
   </script>
-  <script type="module" src="/canvas/index.js"></script>
+  <script type="module" src="/canvas/index.js?v=${CANVAS_ASSET_VERSION}"></script>
 </body>
 </html>`;
 }
@@ -1229,6 +1308,61 @@ function serveCanvasFavicon(): Response {
 
 // ── Canvas REST handlers ──────────────────────────────────────
 
+function normalizeFrameDocumentSandbox(value: unknown): string | null {
+  if (value === undefined || value === null) return DEFAULT_FRAME_DOCUMENT_SANDBOX;
+  if (typeof value !== 'string') return null;
+  const tokens = value.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return DEFAULT_FRAME_DOCUMENT_SANDBOX;
+  const uniqueTokens: string[] = [];
+  for (const token of tokens) {
+    if (!SAFE_FRAME_DOCUMENT_SANDBOX_TOKENS.has(token)) return null;
+    if (!uniqueTokens.includes(token)) uniqueTokens.push(token);
+  }
+  return uniqueTokens.join(' ');
+}
+
+function addFrameDocument(html: string, sandbox: string): string {
+  const id = randomUUID();
+  frameDocuments.set(id, { html, sandbox });
+  while (frameDocuments.size > MAX_FRAME_DOCUMENTS) {
+    const firstKey = frameDocuments.keys().next().value;
+    if (typeof firstKey !== 'string') break;
+    frameDocuments.delete(firstKey);
+  }
+  return `/api/canvas/frame-documents/${id}`;
+}
+
+async function handleCreateFrameDocument(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const html = body.html;
+  if (typeof html !== 'string' || !html) {
+    return responseJson({ ok: false, error: 'Frame document requires non-empty html.' }, 400);
+  }
+  if (new TextEncoder().encode(html).byteLength > MAX_FRAME_DOCUMENT_BYTES) {
+    return responseJson({ ok: false, error: 'Frame document is too large.' }, 413);
+  }
+  const sandbox = normalizeFrameDocumentSandbox(body.sandbox);
+  if (!sandbox) {
+    return responseJson({ ok: false, error: 'Frame document sandbox contains unsupported tokens.' }, 400);
+  }
+  return responseJson({ ok: true, url: addFrameDocument(html, sandbox) });
+}
+
+function handleFrameDocument(pathname: string): Response {
+  const id = decodeURIComponent(pathname.slice('/api/canvas/frame-documents/'.length));
+  const document = frameDocuments.get(id);
+  if (!document) return responseText('Frame document not found.', 404);
+  return new Response(document.html, {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': `sandbox ${document.sandbox}`,
+      'Referrer-Policy': 'no-referrer',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
+
 async function handleCanvasUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const updates = Array.isArray(body.updates) ? body.updates : [];
@@ -1392,6 +1526,20 @@ function buildNodeResponse(node: CanvasNodeState): Record<string, unknown> {
   };
 }
 
+function withContextPinReadState(node: CanvasNodeState): CanvasNodeState {
+  return {
+    ...node,
+    pinned: node.pinned || canvasState.contextPinnedNodeIds.has(node.id),
+  };
+}
+
+function withContextPinLayoutReadState(layout: CanvasLayout): CanvasLayout {
+  return {
+    ...layout,
+    nodes: layout.nodes.map(withContextPinReadState),
+  };
+}
+
 async function createCanvasWebpageNode(body: Record<string, unknown>): Promise<Response> {
   const rawUrl = typeof body.url === 'string' && body.url.trim().length > 0
     ? body.url
@@ -1472,6 +1620,23 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
     return createCanvasHtmlPrimitiveNode(body);
   }
 
+  if (type === 'group') {
+    const geometry = resolveCreateGeometry(body);
+    const childList = pickGroupChildIds(body);
+    if (childList.error) return responseJson({ ok: false, error: `Cannot create group: ${childList.error}` }, 400);
+    const childIds = childList.value ?? [];
+    const childError = validateGroupChildIds('', childIds);
+    if (childError) return responseJson({ ok: false, error: `Cannot create group: ${childError}` }, 400);
+    const { node } = createCanvasGroup({
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      childIds,
+      ...(typeof body.color === 'string' ? { color: body.color } : {}),
+      ...geometry,
+    });
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return responseJson(buildNodeResponse(node));
+  }
+
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
@@ -1517,8 +1682,20 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
       ...(type === 'trace' && typeof body.error === 'string' ? { error: body.error } : {}),
       ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
-      defaultWidth: type === 'html' ? 720 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
-      defaultHeight: type === 'html' ? 640 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
+      defaultWidth: type === 'html'
+        ? 720
+        : type === 'markdown'
+          ? MARKDOWN_NODE_DEFAULT_SIZE.width
+          : type === 'mcp-app'
+            ? MCP_APP_NODE_DEFAULT_SIZE.width
+            : 360,
+      defaultHeight: type === 'html'
+        ? 640
+        : type === 'markdown'
+          ? MARKDOWN_NODE_DEFAULT_SIZE.height
+          : type === 'mcp-app'
+            ? MCP_APP_NODE_DEFAULT_SIZE.height
+            : 200,
       fileMode: 'auto',
     });
   } catch (error) {
@@ -1722,6 +1899,13 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
   if (existing.type === 'webpage' && body.refresh === true) {
     return handleCanvasRefreshWebpageNode(nodeId, req);
   }
+  const groupChildList = existing.type === 'group' ? pickGroupChildIds(body) : {};
+  if (groupChildList.error) return responseJson({ ok: false, error: `Cannot update group: ${groupChildList.error}` }, 400);
+  const groupChildIds = groupChildList.value;
+  if (groupChildIds !== undefined) {
+    const childError = validateGroupChildIds(nodeId, groupChildIds);
+    if (childError) return responseJson({ ok: false, error: `Cannot update group: ${childError}` }, 400);
+  }
   const patch: Record<string, unknown> = resolvePatchGeometry(body, existing);
   if (body.collapsed !== undefined) patch.collapsed = body.collapsed;
   if (body.pinned !== undefined) patch.pinned = Boolean(body.pinned);
@@ -1780,6 +1964,9 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
   });
   if (error) return responseJson({ ok: false, error }, 400);
   canvasState.updateNode(nodeId, patch as Partial<CanvasNodeState>);
+  if (groupChildIds !== undefined && !setGroupChildrenFromApi(nodeId, groupChildIds)) {
+    return responseJson({ ok: false, error: `Group "${nodeId}" not found.` }, 404);
+  }
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   const updated = canvasState.getNode(nodeId);
   return responseJson(updated ? buildNodeResponse(updated) : { ok: true, id: nodeId });
@@ -1817,10 +2004,16 @@ async function handleCanvasFocus(req: Request): Promise<Response> {
     const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
     canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });
   }
+  const focus = canvasState.setAxFocus([nodeId], { source: 'api', recordHistory: false });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
   emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId, noPan });
   if (!noPan) emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-  return responseJson({ ok: true, focused: nodeId, panned: !noPan });
+  return responseJson({ ok: true, focused: nodeId, panned: !noPan, axFocus: focus });
 }
 
 async function handleCanvasFit(req: Request): Promise<Response> {
@@ -2105,6 +2298,18 @@ function handleCanvasValidate(): Response {
   return responseJson(validateCanvasLayout(canvasState.getLayout()));
 }
 
+async function handleCanvasThemeUpdate(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const theme = normalizeCanvasTheme(body.theme, canvasState.theme);
+  const next = canvasState.setTheme(theme);
+  broadcastWorkbenchEvent('theme-changed', {
+    theme: next,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, theme: next });
+}
+
 async function handleJsonRenderView(url: URL): Promise<Response> {
   const nodeId = url.searchParams.get('nodeId') ?? '';
   if (!nodeId) return responseText('Missing nodeId', 400);
@@ -2973,7 +3178,7 @@ function handleWorkbenchEvents(req: Request): Response {
           requestedSessionId: requestedSessionId || null,
           continuity,
           path: primaryWorkbenchPath,
-          theme: canvasThemeSetting,
+          theme: canvasState.theme,
           timestamp: new Date().toISOString(),
         }),
       );
@@ -3391,6 +3596,63 @@ function handleGetPinnedContext(): Response {
   return responseJson({ preamble, nodeIds: pinnedIds, count: pinnedIds.length, nodes });
 }
 
+function normalizeAxNodeIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((id): id is string => typeof id === 'string');
+}
+
+function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource {
+  return value === 'agent' ||
+    value === 'api' ||
+    value === 'browser' ||
+    value === 'cli' ||
+    value === 'codex' ||
+    value === 'copilot' ||
+    value === 'mcp' ||
+    value === 'sdk' ||
+    value === 'system'
+    ? value
+    : fallback;
+}
+
+function handleGetAxState(): Response {
+  return responseJson({ ok: true, state: canvasState.getAxState() });
+}
+
+function handleGetAxContext(): Response {
+  return responseJson(buildCanvasAxContext());
+}
+
+async function handleAxFocusUpdate(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const nodeIds = normalizeAxNodeIds(body.nodeIds);
+  const source = normalizeAxSource(body.source, 'api');
+  const focus = canvasState.setAxFocus(nodeIds, { source });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, focus });
+}
+
+async function handleAxStatePatch(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (!body.focus || typeof body.focus !== 'object' || Array.isArray(body.focus)) {
+    return responseJson({ ok: false, error: 'PATCH /api/canvas/ax currently requires a focus object.' }, 400);
+  }
+  const focusInput = body.focus as Record<string, unknown>;
+  const focus = canvasState.setAxFocus(normalizeAxNodeIds(focusInput.nodeIds), {
+    source: normalizeAxSource(focusInput.source, 'api'),
+  });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, state: canvasState.getAxState() });
+}
+
 // ── Port resolution ───────────────────────────────────────────
 
 function buildPortCandidates(preferredPort: number): number[] {
@@ -4075,6 +4337,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
   // ── Canvas persistence: set workspace root and load saved state ──
   canvasState.setWorkspaceRoot(activeWorkspaceRoot);
+  canvasState.setTheme(initialCanvasThemeSetting as CanvasTheme);
   const loaded = canvasState.loadFromDisk({ clearExisting: true });
   setCanvasLayoutUpdateEmitter(() => {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -4090,7 +4353,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   rotatePrimaryWorkbenchSessionIfNeeded();
 
   const preferredPort = options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? DEFAULT_PORT);
-  const portCandidates = options.allowPortFallback === false
+  const portCandidates = options.port === 0
+    ? [0]
+    : options.allowPortFallback === false
     ? [preferredPort > 0 ? Math.floor(preferredPort) : DEFAULT_PORT]
     : buildPortCandidates(preferredPort);
 
@@ -4119,6 +4384,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleJsonRenderView(url);
           }
 
+          if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
+            return handleCreateFrameDocument(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/frame-documents/') && req.method === 'GET') {
+            return handleFrameDocument(url.pathname);
+          }
+
           if (url.pathname === '/' || url.pathname === '/workbench' || url.pathname === '/artifact') {
             return new Response(canvasSpaHtml(), {
               headers: {
@@ -4185,13 +4458,21 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             const includeBlobs = url.searchParams.get('includeBlobs') === 'true';
             return responseJson(includeBlobs
               ? serializeCanvasLayout(canvasState.getLayout())
-              : serializeCanvasLayoutWithBlobSummaries(canvasState.getLayoutForPersistence()));
+              : serializeCanvasLayoutWithBlobSummaries(withContextPinLayoutReadState(canvasState.getLayoutForPersistence())));
           }
 
           if (url.pathname === '/api/canvas/summary' && req.method === 'GET') {
             return responseJson(buildCanvasSummary());
           }
 
+          if (url.pathname === '/api/canvas/theme' && req.method === 'GET') {
+            return responseJson({ ok: true, theme: canvasState.theme });
+          }
+
+          if (url.pathname === '/api/canvas/theme' && req.method === 'POST') {
+            return handleCanvasThemeUpdate(req);
+          }
+
           if (url.pathname === '/api/canvas/update' && req.method === 'POST') {
             return handleCanvasUpdate(req);
           }
@@ -4247,9 +4528,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             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);
+            const responseNode = withContextPinReadState(node);
             return responseJson(includeBlobs
-              ? serializeCanvasNode(node)
-              : serializeCanvasNodeWithBlobSummaries(node));
+              ? serializeCanvasNode(responseNode)
+              : serializeCanvasNodeWithBlobSummaries(responseNode));
           }
 
           if (url.pathname.startsWith('/api/canvas/node/') && req.method === 'PATCH') {
@@ -4334,6 +4616,22 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleGetPinnedContext();
           }
 
+          if (url.pathname === '/api/canvas/ax' && req.method === 'GET') {
+            return handleGetAxState();
+          }
+
+          if (url.pathname === '/api/canvas/ax' && req.method === 'PATCH') {
+            return handleAxStatePatch(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/context' && req.method === 'GET') {
+            return handleGetAxContext();
+          }
+
+          if (url.pathname === '/api/canvas/ax/focus' && req.method === 'POST') {
+            return handleAxFocusUpdate(req);
+          }
+
           // Spatial context API
           if (url.pathname === '/api/canvas/spatial-context' && req.method === 'GET') {
             const layout = canvasState.getLayout();