pmx-canvas 0.6.4 → 0.7.0

package/src/server/canvas-operations.ts

@@ -5,6 +5,7 @@ import { recomputeCodeGraph } from './code-graph.js';
 import { diffLayouts } from './mutation-history.js';
 import {
   canvasState,
+  defaultBoardName,
   type CanvasEdge,
   type CanvasNodeState,
   type CanvasNodeUpdate,
@@ -20,6 +21,7 @@ import {
   type ExternalMcpTransportConfig,
 } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
+import { intentRegistry } from './intent-registry.js';
 import { clampCreateNodeSize } from './canvas-validation.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
@@ -33,6 +35,7 @@ import {
   emptyStreamingSpec,
   GRAPH_NODE_SIZE,
   inferJsonRenderNodeTitle,
+  jsonRenderFormWarnings,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -118,6 +121,29 @@ export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
 export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
+export interface CanvasSizeAdjustment {
+  requested: { width: number | null; height: number | null };
+  applied: { width: number; height: number };
+  reason: 'defaulted' | 'clamped-to-minimum' | 'defaulted-and-clamped-to-minimum' | 'fit-to-children';
+}
+
+export function describeCreateSize(
+  requestedWidth: number | undefined,
+  requestedHeight: number | undefined,
+  resolvedWidth: number,
+  resolvedHeight: number,
+  applied: { width: number; height: number },
+): CanvasSizeAdjustment | undefined {
+  const defaulted = requestedWidth === undefined || requestedHeight === undefined;
+  const clamped = applied.width !== resolvedWidth || applied.height !== resolvedHeight;
+  if (!defaulted && !clamped) return undefined;
+  return {
+    requested: { width: requestedWidth ?? null, height: requestedHeight ?? null },
+    applied,
+    reason: defaulted && clamped ? 'defaulted-and-clamped-to-minimum' : clamped ? 'clamped-to-minimum' : 'defaulted',
+  };
+}
+
 // Per-type minimum creation sizes + clamp live in canvas-validation.ts
 // (NODE_MIN_CREATE_SIZES / clampCreateNodeSize) — shared with the validate
 // surface's sizeWarnings.
@@ -621,6 +647,7 @@ export function primeCanvasRuntimeBackends(options: { forceRehydrateExtApps?: bo
 export async function syncCanvasRuntimeBackends(
   options: { forceRehydrateExtApps?: boolean; alreadyPrimed?: boolean } = {},
 ): Promise<{ rehydrated: number; failed: number }> {
+  const boardGeneration = canvasState.boardGeneration;
   const targetIds =
     options.alreadyPrimed === true
       ? canvasState
@@ -632,6 +659,7 @@ export async function syncCanvasRuntimeBackends(
   let failed = 0;
 
   for (const nodeId of targetIds) {
+    if (canvasState.boardGeneration !== boardGeneration) break;
     const current = canvasState.getNode(nodeId);
     if (!isExtAppNode(current)) continue;
 
@@ -659,6 +687,10 @@ export async function syncCanvasRuntimeBackends(
           ? { serverName: current.data.serverName.trim() }
           : {}),
       });
+      if (canvasState.boardGeneration !== boardGeneration) {
+        closeMcpAppSession(opened.sessionId);
+        continue;
+      }
       const toolInput = resolveExtAppRehydratedToolInput(current, opened.toolInput);
       const storedCheckpointId = getStoredExcalidrawCheckpointId(current);
       const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
@@ -683,6 +715,7 @@ export async function syncCanvasRuntimeBackends(
       });
       rehydrated++;
     } catch (error) {
+      if (canvasState.boardGeneration !== boardGeneration) continue;
       canvasState.withSuppressedRecording(() => {
         setExtAppRuntimeState(nodeId, {
           appSessionId: null,
@@ -923,17 +956,15 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
   id: string;
   node: CanvasNodeState;
   needsCodeGraphRecompute: boolean;
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   if (input.type === 'json-render' || input.type === 'graph') {
     throw new Error(`Use the dedicated ${input.type} node APIs for structured viewer nodes.`);
   }
 
-  const { width, height } = clampCreateNodeSize(
-    input.type,
-    input.width ?? input.defaultWidth ?? 720,
-    input.height ?? input.defaultHeight ?? 600,
-    input.strictSize,
-  );
+  const resolvedWidth = input.width ?? input.defaultWidth ?? 720;
+  const resolvedHeight = input.height ?? input.defaultHeight ?? 600;
+  const { width, height } = clampCreateNodeSize(input.type, resolvedWidth, resolvedHeight, input.strictSize);
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -959,7 +990,16 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     watchFileForNode(id, filePath);
   }
 
-  return { id, node: storedNode, needsCodeGraphRecompute: input.type === 'file' };
+  const sizeAdjustment = describeCreateSize(input.width, input.height, resolvedWidth, resolvedHeight, {
+    width,
+    height,
+  });
+  return {
+    id,
+    node: storedNode,
+    needsCodeGraphRecompute: input.type === 'file',
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  };
 }
 
 export function resolveCanvasNode(nodeRef: CanvasNodeLookupInput):
@@ -1029,6 +1069,7 @@ export async function refreshCanvasWebpageNode(
   }
 
   const currentData = existing.data;
+  const boardGeneration = canvasState.boardGeneration;
   const configuredUrl =
     typeof options.url === 'string' && options.url.trim().length > 0
       ? options.url
@@ -1054,16 +1095,11 @@ export async function refreshCanvasWebpageNode(
     };
   }
 
-  const fetchingData: Record<string, unknown> = {
-    ...currentData,
-    url: normalizedUrl,
-    status: 'fetching',
-  };
-  delete fetchingData.error;
-  canvasState.updateNode(id, { data: fetchingData });
-
   try {
     const snapshot = await fetchWebpageSnapshot(normalizedUrl);
+    if (canvasState.boardGeneration !== boardGeneration) {
+      return { ok: false, id, error: 'The board changed during webpage refresh.' };
+    }
     const latest = canvasState.getNode(id);
     if (!latest || latest.type !== 'webpage') {
       return { ok: false, id, error: `Webpage node "${id}" disappeared during refresh.` };
@@ -1097,6 +1133,9 @@ export async function refreshCanvasWebpageNode(
     canvasState.updateNode(id, { data: nextData });
     return { ok: true, id };
   } catch (error) {
+    if (canvasState.boardGeneration !== boardGeneration) {
+      return { ok: false, id, error: 'The board changed during webpage refresh.' };
+    }
     const details = getWebpageFetchErrorDetails(error);
     const latest = canvasState.getNode(id);
     if (latest?.type === 'webpage') {
@@ -1415,7 +1454,8 @@ export function saveCanvasSnapshotWithReuse(name: string): { snapshot: CanvasSna
         diff.removedNodes.length === 0 &&
         diff.modifiedNodes.length === 0 &&
         diff.addedEdges.length === 0 &&
-        diff.removedEdges.length === 0;
+        diff.removedEdges.length === 0 &&
+        JSON.stringify(newestData.tour) === JSON.stringify(canvasState.getTour());
       if (identical) return { snapshot: newest, reused: true };
     }
   }
@@ -1430,14 +1470,65 @@ export async function restoreCanvasSnapshot(idOrName: string): Promise<{ ok: boo
   const ok = canvasState.restoreSnapshot(idOrName);
   if (ok) {
     primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
+    const boardGeneration = canvasState.boardGeneration;
     void syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true }).finally(() => {
-      emitCanvasLayoutUpdate();
+      if (canvasState.boardGeneration === boardGeneration) emitCanvasLayoutUpdate();
     });
     canvasState.flushToDisk();
   }
   return { ok };
 }
 
+/**
+ * Open a board (or Home for null): the state layer saves the current board and
+ * loads the next, and everything else that holds the old board in memory is
+ * reset — undo closures, pending intents, file watchers, app sessions and the
+ * code graph (the trace chain restarts itself when its last node is gone).
+ * Agent and human presence are kept: they belong to the people and agents,
+ * not to a board.
+ */
+export function openCanvasBoard(id: string | null): { ok: boolean } {
+  if (!canvasState.switchBoard(id)) return { ok: false };
+  mutationHistory.reset();
+  intentRegistry.reset();
+  startBoardRuntime();
+  return { ok: true };
+}
+
+function startBoardRuntime(): void {
+  primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
+  scheduleCodeGraphRecompute();
+  emitCanvasLayoutUpdate();
+  // App rehydration can take a network round trip; it finishes in the background.
+  const boardGeneration = canvasState.boardGeneration;
+  void syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true }).finally(() => {
+    if (canvasState.boardGeneration === boardGeneration) emitCanvasLayoutUpdate();
+  });
+}
+
+/**
+ * Restore the whole library from a backup file (the current file is kept as
+ * `<db>.before-restore`); the restored library opens on its last open board.
+ */
+export function restoreCanvasLibrary(file: string): void {
+  canvasState.replaceDatabase(file);
+  mutationHistory.reset();
+  intentRegistry.reset();
+  startBoardRuntime();
+}
+
+/**
+ * A write that arrives while no board is open (Home) lands on the most recently
+ * opened board, or on a new board when the workspace has none — nothing on
+ * Home is displaced, because Home holds nothing. Intents and undo history are
+ * kept: whatever was signalled on Home was aimed at the board this opens.
+ */
+export function openBoardForWrite(): void {
+  if (canvasState.activeBoardId) return;
+  const recent = canvasState.listBoards()[0] ?? canvasState.createBoard(defaultBoardName());
+  if (recent && canvasState.switchBoard(recent.id)) startBoardRuntime();
+}
+
 export function deleteCanvasSnapshot(id: string): { ok: boolean } {
   return { ok: canvasState.deleteSnapshot(id) };
 }
@@ -1508,7 +1599,11 @@ export function removeCanvasEdge(id: string): { removed: boolean } {
   return { removed: canvasState.removeEdge(id) };
 }
 
-export function createCanvasGroup(input: CanvasCreateGroupInput): { id: string; node: CanvasNodeState } {
+export function createCanvasGroup(input: CanvasCreateGroupInput): {
+  id: string;
+  node: CanvasNodeState;
+  sizeAdjustment?: CanvasSizeAdjustment;
+} {
   let x = input.x;
   let y = input.y;
   let width = input.width ?? 600;
@@ -1566,22 +1661,42 @@ export function createCanvasGroup(input: CanvasCreateGroupInput): { id: string;
   if (!node) {
     throw new Error(`Group "${id}" was not created.`);
   }
-  return { id, node };
+  const adjusted = input.width !== node.size.width || input.height !== node.size.height;
+  const fitted = childIds.length > 0 && ((input.x === undefined && input.y === undefined) || !explicitFrame);
+  return {
+    id,
+    node,
+    ...(adjusted
+      ? {
+          sizeAdjustment: {
+            requested: { width: input.width ?? null, height: input.height ?? null },
+            applied: node.size,
+            reason: fitted ? ('fit-to-children' as const) : ('defaulted' as const),
+          },
+        }
+      : {}),
+  };
 }
 
 export function groupCanvasNodes(
   groupId: string,
   childIds: string[],
   options: { childLayout?: CanvasArrangeMode } = {},
-): { ok: boolean } {
+): { ok: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
+  const before = canvasState.getNode(groupId)?.size;
+  const ok = canvasState.groupNodes(groupId, childIds, {
+    // Preserve existing child positions unless an explicit layout is asked
+    // for — matching createCanvasGroup and the batch group.add path. Without
+    // this, grouping silently auto-packs the nodes into a grid.
+    preservePositions: options.childLayout === undefined,
+    ...(options.childLayout ? { layout: options.childLayout } : {}),
+  });
+  const applied = canvasState.getNode(groupId)?.size;
   return {
-    ok: canvasState.groupNodes(groupId, childIds, {
-      // Preserve existing child positions unless an explicit layout is asked
-      // for — matching createCanvasGroup and the batch group.add path. Without
-      // this, grouping silently auto-packs the nodes into a grid.
-      preservePositions: options.childLayout === undefined,
-      ...(options.childLayout ? { layout: options.childLayout } : {}),
-    }),
+    ok,
+    ...(before && applied && (before.width !== applied.width || before.height !== applied.height)
+      ? { sizeAdjustment: { requested: before, applied, reason: 'fit-to-children' as const } }
+      : {}),
   };
 }
 
@@ -1600,6 +1715,8 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   url: string;
   spec: JsonRenderSpec;
   node: CanvasNodeState;
+  warnings: string[];
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
   const { width, height } = clampCreateNodeSize(
@@ -1628,7 +1745,24 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   };
 
   canvasState.addJsonRenderNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.height,
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    {
+      width,
+      height,
+    },
+  );
+  return {
+    id,
+    url: String(node.data.url),
+    spec,
+    node,
+    warnings: jsonRenderFormWarnings(spec),
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  };
 }
 
 /**
@@ -1643,7 +1777,7 @@ export function createCanvasStreamingJsonRenderNode(input: {
   width?: number;
   height?: number;
   strictSize?: boolean;
-}): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
+}): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState; sizeAdjustment?: CanvasSizeAdjustment } {
   const spec = emptyStreamingSpec();
   const { width, height } = clampCreateNodeSize(
     'json-render',
@@ -1673,7 +1807,17 @@ export function createCanvasStreamingJsonRenderNode(input: {
   };
 
   canvasState.addJsonRenderNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.height,
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    {
+      width,
+      height,
+    },
+  );
+  return { id, url: String(node.data.url), spec, node, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
 }
 
 /**
@@ -1717,6 +1861,7 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   url: string;
   spec: JsonRenderSpec;
   node: CanvasNodeState;
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   const title = input.title?.trim() || 'Graph';
   const spec = buildGraphSpec(input);
@@ -1747,7 +1892,14 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   };
 
   canvasState.addGraphNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.heightPx,
+    input.width ?? GRAPH_NODE_SIZE.width,
+    input.heightPx ?? GRAPH_NODE_SIZE.height,
+    { width, height },
+  );
+  return { id, url: String(node.data.url), spec, node, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
 }
 
 /**

package/src/server/canvas-provenance.ts

@@ -7,6 +7,7 @@ export type CanvasNodeType =
   | 'webpage'
   | 'json-render'
   | 'graph'
+  | 'board'
   | 'prompt'
   | 'response'
   | 'status'

package/src/server/canvas-schema.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { describeJsonRenderCatalog, type JsonRenderComponentDescriptor } from '../json-render/catalog.js';
 import {
   buildGraphSpec,
+  jsonRenderFormWarnings,
   normalizeAndValidateJsonRenderSpec,
   normalizeGraphType,
   type GraphNodeInput,
@@ -38,6 +39,7 @@ export interface StructuredValidationResult {
   ok: true;
   type: 'json-render' | 'graph' | 'html-primitive';
   normalizedSpec?: JsonRenderSpec;
+  warnings?: string[];
   normalizedPrimitive?: {
     kind: string;
     title: string;
@@ -105,6 +107,18 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'When a markdown node is path-backed (`data.path`), the server persists `data.provenance` so snapshots keep a refreshable file source.',
     ],
   },
+  {
+    type: 'board',
+    kind: 'node',
+    description: 'Text-only link to another board by durable id.',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Pinned fallback title.' },
+      { name: 'data', type: 'object', required: true, description: 'Contains boardId, the durable target board id.' },
+    ],
+    example: { type: 'board', title: 'Research', data: { boardId: 'board-abc123' } },
+  },
   {
     type: 'status',
     kind: 'node',
@@ -235,6 +249,13 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'content', type: 'string', required: false, description: 'Mermaid diagram source text.' },
+      {
+        name: 'data.fit',
+        type: '"contain" | "none"',
+        required: false,
+        description:
+          'Default contain: shrink overflowing diagrams proportionally, without enlarging. none: 100% with scrolling. Open as site always uses 100%. CLI: --fit contain|none.',
+      },
     ],
     example: {
       type: 'mermaid',
@@ -1013,6 +1034,7 @@ export function validateStructuredCanvasPayload(input: {
       ok: true,
       type: 'json-render',
       normalizedSpec,
+      warnings: jsonRenderFormWarnings(normalizedSpec),
       summary: {
         root: normalizedSpec.root,
         elementCount: Object.keys(normalizedSpec.elements).length,