pmx-canvas 0.1.19 → 0.1.20

package/src/server/canvas-operations.ts

@@ -20,6 +20,7 @@ import { mutationHistory } from './mutation-history.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle, serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
+import { computeAutoArrange } from '../shared/auto-arrange.js';
 import {
   buildGraphSpec,
   buildGraphConfig,
@@ -102,6 +103,8 @@ interface CanvasAddNodeInput {
   strictSize?: boolean;
 }
 
+export const MARKDOWN_NODE_DEFAULT_SIZE = { width: 520, height: 360 };
+
 interface CanvasCreateGroupInput {
   title?: string;
   childIds?: string[];
@@ -1070,62 +1073,105 @@ function collectArrangeExcludedNodeIds(nodes: CanvasNodeState[]): Set<string> {
   return excluded;
 }
 
+function collectGridArrangeExcludedNodeIds(nodes: CanvasNodeState[]): Set<string> {
+  const nodesById = new Map(nodes.map((node) => [node.id, node]));
+  const excluded = new Set<string>();
+
+  for (const node of nodes) {
+    if (isArrangeLocked(node)) excluded.add(node.id);
+  }
+
+  for (const node of nodes) {
+    if (node.type !== 'group') continue;
+    const childIds = Array.isArray(node.data.children)
+      ? node.data.children.filter((id): id is string => typeof id === 'string')
+      : [];
+    const hasLockedChild = childIds.some((childId) => {
+      const child = nodesById.get(childId);
+      return child ? isArrangeLocked(child) : false;
+    });
+    if (!excluded.has(node.id) && !hasLockedChild) continue;
+
+    excluded.add(node.id);
+    for (const childId of childIds) excluded.add(childId);
+  }
+
+  return excluded;
+}
+
 export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: number; layout: CanvasArrangeMode } {
   const nodes = canvasState.getLayout().nodes;
-  const excludedIds = collectArrangeExcludedNodeIds(nodes);
+  const excludedIds = layout === 'grid'
+    ? collectGridArrangeExcludedNodeIds(nodes)
+    : collectArrangeExcludedNodeIds(nodes);
   const movableNodes = nodes.filter((node) => !excludedIds.has(node.id));
-  const gap = 24;
   const oldPositions = nodes.map((node) => ({ id: node.id, position: { ...node.position } }));
-
-  canvasState.withSuppressedRecording(() => {
-    if (layout === 'column') {
-      let y = 80;
-      for (const node of movableNodes) {
-        canvasState.updateNode(node.id, { position: { x: 40, y } });
+  const oldSizes = nodes.map((node) => ({ id: node.id, size: { ...node.size } }));
+  const newSizesById = new Map<string, CanvasNodeUpdate['size']>();
+  const oldSizesById = new Map(oldSizes.map((entry) => [entry.id, entry.size]));
+  const updates: CanvasNodeUpdate[] = [];
+
+  if (layout === 'column' || layout === 'flow') {
+    const gap = 24;
+    let x = 40;
+    let y = 80;
+    for (const node of movableNodes) {
+      updates.push({ id: node.id, position: { x, y } });
+      if (layout === 'column') {
         y += node.size.height + gap;
-      }
-      return;
-    }
-
-    if (layout === 'flow') {
-      let x = 40;
-      for (const node of movableNodes) {
-        canvasState.updateNode(node.id, { position: { x, y: 80 } });
+      } else {
         x += node.size.width + gap;
       }
-      return;
     }
-
-    const maxNodeWidth = movableNodes.reduce((max, node) => Math.max(max, node.size.width), 360);
-    const cols = Math.max(1, Math.floor(1440 / (maxNodeWidth + gap)));
-    let col = 0;
-    let rowY = 80;
-    let rowMaxHeight = 0;
-    for (const node of movableNodes) {
-      const x = 40 + col * (maxNodeWidth + gap);
-      canvasState.updateNode(node.id, { position: { x, y: rowY } });
-      rowMaxHeight = Math.max(rowMaxHeight, node.size.height);
-      col++;
-      if (col >= cols) {
-        col = 0;
-        rowY += rowMaxHeight + gap;
-        rowMaxHeight = 0;
-      }
+  } else {
+    const result = computeAutoArrange(movableNodes, canvasState.getEdges(), 'grid');
+    for (const [id, position] of result.nodePositions.entries()) {
+      updates.push({ id, position });
     }
+    for (const [groupId, bounds] of result.groupBounds.entries()) {
+      updates.push({
+        id: groupId,
+        position: { x: bounds.x, y: bounds.y },
+        size: { width: bounds.width, height: bounds.height },
+      });
+    }
+  }
+
+  canvasState.withSuppressedRecording(() => {
+    canvasState.applyUpdates(updates, layout === 'grid' ? { skipGroupChildTranslation: true } : {});
   });
 
   const newPositions = nodes.map((node) => {
     const updated = canvasState.getNode(node.id);
     return { id: node.id, position: updated ? { ...updated.position } : { ...node.position } };
   });
+  for (const node of nodes) {
+    const updated = canvasState.getNode(node.id);
+    const size = updated ? { ...updated.size } : { ...node.size };
+    newSizesById.set(node.id, size);
+  }
   mutationHistory.record({
     description: `Auto-arranged ${movableNodes.length} nodes (${layout})`,
     operationType: 'arrange',
     forward: () => canvasState.withSuppressedRecording(() => {
-      for (const position of newPositions) canvasState.updateNode(position.id, { position: position.position });
+      canvasState.applyUpdates(newPositions.map((position) => {
+        const size = newSizesById.get(position.id);
+        return {
+          id: position.id,
+          position: position.position,
+          ...(size ? { size } : {}),
+        };
+      }), layout === 'grid' ? { skipGroupChildTranslation: true } : {});
     }),
     inverse: () => canvasState.withSuppressedRecording(() => {
-      for (const position of oldPositions) canvasState.updateNode(position.id, { position: position.position });
+      canvasState.applyUpdates(oldPositions.map((position) => {
+        const size = oldSizesById.get(position.id);
+        return {
+          id: position.id,
+          position: position.position,
+          ...(size ? { size } : {}),
+        };
+      }), layout === 'grid' ? { skipGroupChildTranslation: true } : {});
     }),
   });
 
@@ -1477,6 +1523,9 @@ export async function executeCanvasBatch(
       switch (operation.op) {
         case 'node.add': {
           const type = typeof args.type === 'string' ? args.type : 'markdown';
+          if (type === 'html-primitive') {
+            throw new Error('Batch html-primitive creation is not supported yet. Use node.add with type "html" and generated html, or create the primitive through MCP/HTTP/CLI first.');
+          }
           if (type === 'webpage') {
             const created = addCanvasNode({
               type: 'webpage',
@@ -1502,18 +1551,22 @@ export async function executeCanvasBatch(
               ...(fetch.ok ? {} : { error: fetch.error }),
             };
           } else {
+            const data = isPlainRecord(args.data) ? args.data : {};
+            const htmlData = type === 'html' && typeof args.html === 'string'
+              ? { ...data, html: args.html }
+              : data;
             const created = addCanvasNode({
               type: type as CanvasNodeState['type'],
               ...(typeof args.title === 'string' ? { title: args.title } : {}),
               ...(typeof args.content === 'string' ? { content: args.content } : {}),
-              ...(isPlainRecord(args.data) ? { data: args.data } : {}),
+              ...(Object.keys(htmlData).length > 0 ? { data: htmlData } : {}),
               ...(typeof args.x === 'number' ? { x: args.x } : {}),
               ...(typeof args.y === 'number' ? { y: args.y } : {}),
               ...(typeof args.width === 'number' ? { width: args.width } : {}),
               ...(typeof args.height === 'number' ? { height: args.height } : {}),
               ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: 360,
-              defaultHeight: 200,
+              defaultWidth: type === 'html' ? 720 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
+              defaultHeight: type === 'html' ? 640 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
               fileMode: 'auto',
             });
             result = { ok: true, ...serializeCreatedNode(created.node) };

package/src/server/canvas-schema.ts

@@ -8,6 +8,12 @@ import {
   type GraphNodeInput,
   type JsonRenderSpec,
 } from '../json-render/server.js';
+import {
+  buildHtmlPrimitive,
+  isHtmlPrimitiveKind,
+  listHtmlPrimitiveDescriptors,
+  type HtmlPrimitiveDescriptor,
+} from './html-primitives.js';
 
 export interface CanvasCreateField {
   name: string;
@@ -30,8 +36,14 @@ export interface CanvasCreateTypeSchema {
 
 export interface StructuredValidationResult {
   ok: true;
-  type: 'json-render' | 'graph';
-  normalizedSpec: JsonRenderSpec;
+  type: 'json-render' | 'graph' | 'html-primitive';
+  normalizedSpec?: JsonRenderSpec;
+  normalizedPrimitive?: {
+    kind: string;
+    title: string;
+    htmlBytes: number;
+    defaultSize: { width: number; height: number };
+  };
   summary: Record<string, unknown>;
 }
 
@@ -231,6 +243,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     mcpTool: 'canvas_add_html_node',
     fields: [
       { name: 'html', type: 'string', required: false, description: 'HTML document or fragment rendered in the sandboxed iframe.', aliases: ['content', 'stdin'] },
+      { name: 'primitive', type: 'HtmlPrimitiveKind', required: false, description: 'Generate HTML from a built-in communication primitive instead of passing raw HTML.', aliases: ['kind'] },
+      { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive data when --primitive is used, or arbitrary node metadata.' },
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
@@ -245,9 +259,41 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     },
     notes: [
       'The CLI accepts --content as an alias and stores it as data.html so the renderer can load it.',
+      'Use `primitive` / `kind` with `data` to create reusable agent communication artifacts such as choice grids, plans, review sheets, explainers, and editors.',
       'HTML runs in a sandboxed iframe without same-origin access to the canvas host.',
     ],
   },
+  {
+    type: 'html-primitive',
+    kind: 'virtual-node',
+    description: 'Reusable sandboxed HTML communication primitive rendered as an html node.',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_html_primitive',
+    fields: [
+      { name: 'kind', type: 'HtmlPrimitiveKind', required: true, description: 'Primitive kind. See top-level htmlPrimitives for the supported catalog.' },
+      { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive-specific JSON object payload.' },
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
+      { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
+      { name: 'width', type: 'number', required: false, description: 'Optional node width; defaults per primitive.' },
+      { name: 'height', type: 'number', required: false, description: 'Optional node height; defaults per primitive.' },
+      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+    ],
+    example: {
+      type: 'html-primitive',
+      kind: 'choice-grid',
+      title: 'Implementation Options',
+      data: {
+        items: [
+          { title: 'Small patch', summary: 'Least disruption.', pros: ['Fast'], cons: ['Limited flexibility'] },
+        ],
+      },
+    },
+    notes: [
+      'HTTP callers may POST { type: "html-primitive", kind, data } or { type: "html", primitive: kind, data }; both create a normal html node with primitive metadata.',
+      'Interactive editor primitives include copy/export controls so the human can send edited state back to the agent.',
+    ],
+  },
   {
     type: 'mcp-app',
     kind: 'node',
@@ -449,6 +495,7 @@ export function describeCanvasSchema(): {
   graph: {
     graphTypes: CanvasGraphType[];
   };
+  htmlPrimitives: HtmlPrimitiveDescriptor[];
   mcp: {
     tools: string[];
     resources: string[];
@@ -472,9 +519,12 @@ export function describeCanvasSchema(): {
     graph: {
       graphTypes: [...CANONICAL_GRAPH_TYPES],
     },
+    htmlPrimitives: listHtmlPrimitiveDescriptors(),
     mcp: {
       tools: [
         'canvas_add_node',
+        'canvas_add_html_node',
+        'canvas_add_html_primitive',
         'canvas_add_json_render_node',
         'canvas_add_graph_node',
         'canvas_build_web_artifact',
@@ -492,9 +542,10 @@ export function describeCanvasSchema(): {
 }
 
 export function validateStructuredCanvasPayload(input: {
-  type: 'json-render' | 'graph';
+  type: 'json-render' | 'graph' | 'html-primitive';
   spec?: unknown;
   graph?: GraphNodeInput;
+  primitive?: { kind: string; title?: string; data?: Record<string, unknown> };
 }): StructuredValidationResult {
   if (input.type === 'json-render') {
     const normalizedSpec = normalizeAndValidateJsonRenderSpec(input.spec);
@@ -510,6 +561,35 @@ export function validateStructuredCanvasPayload(input: {
     };
   }
 
+  if (input.type === 'html-primitive') {
+    if (!input.primitive) {
+      throw new Error('HTML primitive validation requires a primitive payload.');
+    }
+    if (!isHtmlPrimitiveKind(input.primitive.kind)) {
+      throw new Error(`Unknown HTML primitive: ${input.primitive.kind}`);
+    }
+    const built = buildHtmlPrimitive({
+      kind: input.primitive.kind,
+      ...(typeof input.primitive.title === 'string' ? { title: input.primitive.title } : {}),
+      ...(input.primitive.data ? { data: input.primitive.data } : {}),
+    });
+    return {
+      ok: true,
+      type: 'html-primitive',
+      normalizedPrimitive: {
+        kind: built.kind,
+        title: built.title,
+        htmlBytes: Buffer.byteLength(built.html, 'utf-8'),
+        defaultSize: built.defaultSize,
+      },
+      summary: {
+        kind: built.kind,
+        title: built.title,
+        dataKeys: Object.keys(built.data),
+      },
+    };
+  }
+
   if (!input.graph) {
     throw new Error('Graph validation requires a graph payload.');
   }

package/src/server/canvas-serialization.ts

@@ -27,6 +27,7 @@ export interface CanvasAnnotationSummary {
   color: string;
   width: number;
   pointCount: number;
+  text: string | null;
   label: string | null;
   createdAt: string;
 }
@@ -75,6 +76,11 @@ export function getCanvasNodeTitle(node: CanvasNodeState): string | null {
 }
 
 export function getCanvasNodeContent(node: CanvasNodeState): string | null {
+  if (node.type === 'html' && typeof node.data.htmlPrimitive === 'string') {
+    const primitive = node.data.htmlPrimitive;
+    const description = pickString(node.data.description);
+    return description ? `${primitive}: ${description}` : primitive;
+  }
   return pickString(node.data.content)
     ?? pickString(node.data.fileContent)
     ?? pickString(node.data.text)
@@ -180,7 +186,8 @@ export function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasA
     color: annotation.color,
     width: annotation.width,
     pointCount: annotation.points.length,
-    label: annotation.label ?? null,
+    text: annotation.text ?? null,
+    label: annotation.label ?? annotation.text ?? null,
     createdAt: annotation.createdAt,
   };
 }
@@ -208,7 +215,7 @@ export function summarizeCanvasAnnotationForContext(
   const targetNodeTitles = targetNodes.map((node) => getCanvasNodeTitle(node) ?? node.id);
   return {
     id: annotation.id,
-    label: annotation.label ?? null,
+    label: annotation.label ?? annotation.text ?? null,
     bounds: annotation.bounds,
     targetNodeIds: targetNodes.map((node) => node.id),
     targetNodeTitles,

package/src/server/canvas-state.ts

@@ -162,11 +162,12 @@ export interface CanvasAnnotationPoint {
 
 export interface CanvasAnnotation {
   id: string;
-  type: 'freehand';
+  type: 'freehand' | 'text';
   points: CanvasAnnotationPoint[];
   bounds: { x: number; y: number; width: number; height: number };
   color: string;
   width: number;
+  text?: string;
   label?: string;
   createdAt: string;
 }
@@ -201,6 +202,10 @@ interface GroupNodesOptions {
   keepGroupFrame?: boolean;
 }
 
+interface ApplyUpdatesOptions {
+  skipGroupChildTranslation?: boolean;
+}
+
 function formatBatchUpdateDescription(updates: CanvasNodeUpdate[]): string {
   let moved = 0;
   let resized = 0;
@@ -1216,7 +1221,7 @@ class CanvasStateManager {
     };
   }
 
-  applyUpdates(updates: CanvasNodeUpdate[]): { applied: number; skipped: number } {
+  applyUpdates(updates: CanvasNodeUpdate[], options: ApplyUpdatesOptions = {}): { applied: number; skipped: number } {
     let applied = 0;
     let skipped = 0;
     const touchedParentGroups = new Map<string, { compact: boolean }>();
@@ -1259,7 +1264,7 @@ class CanvasStateManager {
       }
       oldSnapshots.set(update.id, structuredClone(existing));
       appliedUpdates.push({ id: update.id, ...structuredClone(nextPatch) });
-      if (existing.type === 'group' && nextPatch.position) {
+      if (existing.type === 'group' && nextPatch.position && options.skipGroupChildTranslation !== true) {
         this.translateGroupChildren(
           update.id,
           nextPatch.position.x - existing.position.x,
@@ -1297,7 +1302,7 @@ class CanvasStateManager {
         operationType: 'batch',
         description: formatBatchUpdateDescription(appliedUpdates),
         forward: this.suppressed(() => {
-          this.applyUpdates(appliedUpdates.map((update) => structuredClone(update)));
+          this.applyUpdates(appliedUpdates.map((update) => structuredClone(update)), options);
         }),
         inverse: this.suppressed(() => {
           for (const snapshot of inverseSnapshots) {