pmx-canvas 0.6.3 → 0.6.5

package/src/server/canvas-operations.ts

@@ -33,6 +33,7 @@ import {
   emptyStreamingSpec,
   GRAPH_NODE_SIZE,
   inferJsonRenderNodeTitle,
+  jsonRenderFormWarnings,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -118,6 +119,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.
@@ -923,17 +947,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 +981,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):
@@ -1415,7 +1446,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 };
     }
   }
@@ -1508,7 +1540,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 +1602,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 +1656,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 +1686,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 +1718,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 +1748,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 +1802,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 +1833,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-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;
@@ -235,6 +237,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 +1022,7 @@ export function validateStructuredCanvasPayload(input: {
       ok: true,
       type: 'json-render',
       normalizedSpec,
+      warnings: jsonRenderFormWarnings(normalizedSpec),
       summary: {
         root: normalizedSpec.root,
         elementCount: Object.keys(normalizedSpec.elements).length,

package/src/server/canvas-state.ts

@@ -13,6 +13,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { tourSchema, type Tour } from '../shared/tour.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
@@ -223,6 +224,7 @@ export interface CanvasAnnotation {
 }
 
 export interface CanvasLayout {
+  tour?: Tour;
   viewport: ViewportState;
   theme: CanvasTheme;
   nodes: CanvasNodeState[];
@@ -333,6 +335,7 @@ class CanvasStateManager {
   private edges = new Map<string, CanvasEdge>();
   private annotations = new Map<string, CanvasAnnotation>();
   private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
+  private _tour: Tour | undefined;
   private _theme: CanvasTheme = 'dark';
   private _contextPinnedNodeIds = new Set<string>();
   private _workspaceRoot = process.cwd();
@@ -899,6 +902,7 @@ class CanvasStateManager {
       const payload = this.externalizePersistedStateBlobs({
         version: 1,
         theme: this._theme,
+        tour: this._tour,
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
@@ -957,6 +961,7 @@ class CanvasStateManager {
   }
 
   private applyPersistedState(state: PersistedCanvasState): void {
+    this._tour = state.tour ? structuredClone(state.tour) : undefined;
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();
@@ -1091,7 +1096,7 @@ class CanvasStateManager {
         contextPins: Array.from(this._contextPinnedNodeIds),
         ax: this.getAxState(),
       });
-      saveSnapshotToDB(this._db, snapshot, payload);
+      saveSnapshotToDB(this._db, snapshot, { ...payload, tour: this._tour });
       snapshot.nodeCount = payload.nodes.length;
       snapshot.edgeCount = payload.edges.length;
       return snapshot;
@@ -1176,6 +1181,7 @@ class CanvasStateManager {
 
     const previousState: PersistedCanvasState = this.externalizePersistedStateBlobs({
       version: 1,
+      tour: this._tour,
       theme: this._theme,
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
@@ -1186,6 +1192,7 @@ class CanvasStateManager {
     });
     const nextState: PersistedCanvasState = {
       version: 1,
+      tour: resolved.state.tour,
       theme: normalizeCanvasTheme(resolved.state.theme, this._theme),
       viewport: structuredClone(resolved.state.viewport),
       nodes: Array.isArray(resolved.state.nodes) ? resolved.state.nodes.map((node) => structuredClone(node)) : [],
@@ -1233,9 +1240,13 @@ class CanvasStateManager {
   }
 
   /** Read a snapshot's data without restoring it (for diff). Resolves by ID or name. */
-  getSnapshotData(
-    idOrName: string,
-  ): { name: string; nodes: CanvasNodeState[]; edges: CanvasEdge[]; annotations: CanvasAnnotation[] } | null {
+  getSnapshotData(idOrName: string): {
+    name: string;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+    annotations: CanvasAnnotation[];
+    tour?: Tour;
+  } | null {
     const resolved = this.readResolvedSnapshot(idOrName);
     if (!resolved) return null;
     const state = {
@@ -1246,6 +1257,7 @@ class CanvasStateManager {
     };
     return {
       name: resolved.snapshot.name,
+      ...(state.tour ? { tour: structuredClone(state.tour) } : {}),
       nodes: Array.isArray(state.nodes) ? state.nodes.map((node) => structuredClone(node)) : [],
       edges: Array.isArray(state.edges) ? state.edges.map((edge) => structuredClone(edge)) : [],
       annotations: Array.isArray(state.annotations)
@@ -1620,6 +1632,7 @@ class CanvasStateManager {
 
   getLayout(): CanvasLayout {
     return {
+      tour: this.getTour(),
       viewport: structuredClone(this._viewport),
       theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.nodeForRead(node))),
@@ -1630,6 +1643,7 @@ class CanvasStateManager {
 
   getLayoutForPersistence(): CanvasLayout {
     return {
+      tour: this.getTour(),
       viewport: structuredClone(this._viewport),
       theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.externalizeNodeDataBlobs(node))),
@@ -1638,6 +1652,24 @@ class CanvasStateManager {
     };
   }
 
+  getTour(): Tour | undefined {
+    return this._tour ? structuredClone(this._tour) : undefined;
+  }
+
+  setTour(tour: Tour | null): void {
+    const previous = this.getTour();
+    this._tour = tour === null ? undefined : tourSchema.parse(tour);
+    const next = this.getTour();
+    this.scheduleSave();
+    this.notifyChange('nodes');
+    this.recordMutation({
+      operationType: 'viewport',
+      description: 'Updated board tour',
+      forward: this.suppressed(() => this.setTour(next ?? null)),
+      inverse: this.suppressed(() => this.setTour(previous ?? null)),
+    });
+  }
+
   applyUpdates(updates: CanvasNodeUpdate[], options: ApplyUpdatesOptions = {}): { applied: number; skipped: number } {
     let applied = 0;
     let skipped = 0;
@@ -2246,6 +2278,8 @@ class CanvasStateManager {
   }
 
   clear(): void {
+    const oldTour = this.getTour();
+    this._tour = undefined;
     const oldNodes = Array.from(this.nodes.values()).map((n) => structuredClone(n));
     const oldEdges = Array.from(this.edges.values()).map((e) => structuredClone(e));
     const oldAnnotations = Array.from(this.annotations.values()).map((annotation) => structuredClone(annotation));
@@ -2274,6 +2308,7 @@ class CanvasStateManager {
         for (const e of oldEdges) this.addEdge(structuredClone(e));
         for (const annotation of oldAnnotations) this.addAnnotation(structuredClone(annotation));
         this.setContextPins(oldPins);
+        this.setTour(oldTour ?? null);
         this.ax.applyPersistedAx(oldAxState);
         this.setViewport(oldViewport);
         this.notifyChange('ax');

package/src/server/canvas-validation.ts

@@ -36,6 +36,8 @@ export interface CanvasValidationResult {
   collisions: CanvasValidationPair[];
   containments: CanvasContainmentIssue[];
   containmentViolations: CanvasContainmentIssue[];
+  /** Group frames overlapping nodes that are not members (advisory). */
+  groupFrameOverlaps: CanvasValidationPair[];
   missingEdgeEndpoints: Array<{ edgeId: string; from: string; to: string }>;
   /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
   sizeWarnings: CanvasSizeWarning[];
@@ -45,6 +47,7 @@ export interface CanvasValidationResult {
     collisions: number;
     containments: number;
     containmentViolations: number;
+    groupFrameOverlaps: number;
     missingEdgeEndpoints: number;
     sizeWarnings: number;
   };
@@ -97,6 +100,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
   const collisions: CanvasValidationPair[] = [];
   const containments: CanvasContainmentIssue[] = [];
   const containmentViolations: CanvasContainmentIssue[] = [];
+  const groupFrameOverlaps: CanvasValidationPair[] = [];
 
   for (let i = 0; i < layout.nodes.length; i++) {
     const a = layout.nodes[i]!;
@@ -113,7 +117,9 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
         continue;
       }
 
-      collisions.push(pair(a, b));
+      const overlap = pair(a, b);
+      collisions.push(overlap);
+      if (a.type === 'group' || b.type === 'group') groupFrameOverlaps.push(overlap);
     }
   }
 
@@ -150,6 +156,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
     collisions,
     containments,
     containmentViolations,
+    groupFrameOverlaps,
     missingEdgeEndpoints,
     sizeWarnings,
     summary: {
@@ -158,6 +165,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       collisions: collisions.length,
       containments: containments.length,
       containmentViolations: containmentViolations.length,
+      groupFrameOverlaps: groupFrameOverlaps.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
       sizeWarnings: sizeWarnings.length,
     },