pmx-canvas 0.1.18 → 0.1.20

package/src/mcp/canvas-access.ts

@@ -19,6 +19,8 @@ type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
 type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
 type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
 type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
+type AddHtmlPrimitiveInput = Parameters<PmxCanvas['addHtmlPrimitive']>[0];
+type AddHtmlPrimitiveResult = ReturnType<PmxCanvas['addHtmlPrimitive']>;
 type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
 type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
 type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
@@ -102,6 +104,7 @@ export interface CanvasAccess {
   addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
   addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
   addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
+  addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult>;
   addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
   buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
   updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
@@ -188,6 +191,10 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.addHtmlNode(input);
   }
 
+  async addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult> {
+    return this.canvas.addHtmlPrimitive(input);
+  }
+
   async addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult> {
     return this.canvas.addGraphNode(input);
   }
@@ -438,6 +445,22 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestNodeId('POST', '/api/canvas/node', { type: 'html', ...input });
   }
 
+  async addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult> {
+    const response = await this.requestJson<{
+      id?: string;
+      node?: { id?: string };
+      primitive?: { kind?: string; title?: string; htmlBytes?: number };
+    }>('POST', '/api/canvas/node', { type: 'html', ...input, primitive: input.kind });
+    const id = typeof response.id === 'string' ? response.id : response.node?.id;
+    if (!id) throw new Error('html primitive response did not include a node id.');
+    return {
+      id,
+      kind: input.kind,
+      title: response.primitive?.title ?? input.title ?? input.kind,
+      htmlBytes: response.primitive?.htmlBytes ?? 0,
+    };
+  }
+
   async addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult> {
     const response = await this.requestJson<GraphNodeResponse>('POST', '/api/canvas/graph', {
       ...input,
@@ -559,6 +582,8 @@ class RemoteCanvasAccess implements CanvasAccess {
     const params = new URLSearchParams();
     if (typeof options?.limit === 'number') params.set('limit', String(options.limit));
     if (options?.query) params.set('q', options.query);
+    if (options?.before) params.set('before', options.before);
+    if (options?.after) params.set('after', options.after);
     if (options?.all) params.set('all', 'true');
     const query = params.size > 0 ? `?${params.toString()}` : '';
     return await this.requestJson<SnapshotList>('GET', `/api/canvas/snapshots${query}`);

package/src/mcp/server.ts

@@ -25,6 +25,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { isAbsolute, relative, resolve } from 'node:path';
 import { z } from 'zod';
 import { canvasState, describeCanvasSchema, validateStructuredCanvasPayload } from '../server/index.js';
+import { isHtmlPrimitiveKind } from '../server/html-primitives.js';
+import type { HtmlPrimitiveKind } from '../server/html-primitives.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
 import { wrapCanvasAutomationScript } from '../server/server.js';
@@ -56,6 +58,8 @@ const jsonRenderSpecSchema = z.union([
   }).passthrough(),
 ]);
 
+const htmlPrimitiveKindSchema = z.string().refine(isHtmlPrimitiveKind, 'Unknown HTML primitive kind');
+
 function structuredSchemaDescription(): string {
   const routing = describeCanvasSchema().mcp.nodeTypeRouting;
   return Object.entries(routing)
@@ -428,6 +432,46 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  server.tool(
+    'canvas_add_html_primitive',
+    'Create a reusable HTML communication primitive as a normal sandboxed html node. Use this instead of long markdown for side-by-side choices, implementation plans, PR review sheets, module maps, design sheets, component galleries, flowcharts, slide decks, explainers, status reports, and throwaway editors with export/copy paths.',
+    {
+      kind: htmlPrimitiveKindSchema.describe('Primitive kind. Call canvas_describe_schema and read htmlPrimitives for data shapes and examples.'),
+      title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
+      data: z.record(z.string(), z.unknown()).optional().describe('Primitive-specific data payload. See canvas_describe_schema.htmlPrimitives for each shape.'),
+      x: z.number().optional().describe('X position (auto-placed if omitted).'),
+      y: z.number().optional().describe('Y position (auto-placed if omitted).'),
+      width: z.number().optional().describe('Width in pixels (defaults per primitive).'),
+      height: z.number().optional().describe('Height in pixels (defaults per primitive).'),
+      strictSize: z.boolean().optional().describe('Keep explicit width/height fixed; iframe scrolls overflow internally.'),
+      full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
+      verbose: z.boolean().optional().describe('Alias for full:true.'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      const kind = input.kind as HtmlPrimitiveKind;
+      const result = await c.addHtmlPrimitive({
+        kind,
+        ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        ...(input.data ? { data: input.data } : {}),
+        ...(typeof input.x === 'number' ? { x: input.x } : {}),
+        ...(typeof input.y === 'number' ? { y: input.y } : {}),
+        ...(typeof input.width === 'number' ? { width: input.width } : {}),
+        ...(typeof input.height === 'number' ? { height: input.height } : {}),
+        ...(input.strictSize === true ? { strictSize: true } : {}),
+      });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ...(await createdNodePayload(c, result.id, input)),
+            primitive: { kind: result.kind, title: result.title, htmlBytes: result.htmlBytes },
+          }, null, 2),
+        }],
+      };
+    },
+  );
+
   server.tool(
     'canvas_open_mcp_app',
     'Connect to an external MCP server that declares a ui:// app resource, call the specified tool, and open the resulting MCP App inside a canvas mcp-app node. This is a full external-MCP transport call, not the CLI kind shortcut; use canvas_add_diagram for the built-in Excalidraw preset.',
@@ -543,10 +587,13 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_validate_spec',
-    'Validate a json-render spec or graph payload without creating a node. Returns the normalized json-render spec that the server would accept.',
+    'Validate a json-render spec, graph payload, or HTML primitive payload without creating a node. Returns normalized metadata the server would accept.',
     {
-      type: z.enum(['json-render', 'graph']).describe('Structured payload type to validate'),
+      type: z.enum(['json-render', 'graph', 'html-primitive']).describe('Structured payload type to validate'),
       spec: jsonRenderSpecSchema.optional().describe('json-render spec to validate when type="json-render"'),
+      kind: htmlPrimitiveKindSchema.optional().describe('HTML primitive kind when type="html-primitive"'),
+      primitive: htmlPrimitiveKindSchema.optional().describe('Alias for kind when type="html-primitive"'),
+      primitiveData: z.record(z.string(), z.unknown()).optional().describe('HTML primitive data payload when type="html-primitive"'),
       title: z.string().optional().describe('Optional graph title'),
       graphType: z.string().optional().describe('Graph type when type="graph"'),
       data: z.array(z.record(z.string(), z.unknown())).optional().describe('Graph dataset when type="graph"'),
@@ -573,29 +620,38 @@ export async function startMcpServer(): Promise<void> {
               type: 'json-render',
               spec: input.spec,
             })
-          : validateStructuredCanvasPayload({
-              type: 'graph',
-              graph: {
-                title: input.title,
-                graphType: input.graphType ?? 'line',
-                data: input.data ?? [],
-                ...(typeof input.xKey === 'string' ? { xKey: input.xKey } : {}),
-                ...(typeof input.yKey === 'string' ? { yKey: input.yKey } : {}),
-                ...(typeof input.zKey === 'string' ? { zKey: input.zKey } : {}),
-                ...(typeof input.nameKey === 'string' ? { nameKey: input.nameKey } : {}),
-                ...(typeof input.valueKey === 'string' ? { valueKey: input.valueKey } : {}),
-                ...(typeof input.axisKey === 'string' ? { axisKey: input.axisKey } : {}),
-                ...(Array.isArray(input.metrics) ? { metrics: input.metrics } : {}),
-                ...(Array.isArray(input.series) ? { series: input.series } : {}),
-                ...(typeof input.barKey === 'string' ? { barKey: input.barKey } : {}),
-                ...(typeof input.lineKey === 'string' ? { lineKey: input.lineKey } : {}),
-                ...(typeof input.aggregate === 'string' ? { aggregate: input.aggregate } : {}),
-                ...(typeof input.color === 'string' ? { color: input.color } : {}),
-                ...(typeof input.barColor === 'string' ? { barColor: input.barColor } : {}),
-                ...(typeof input.lineColor === 'string' ? { lineColor: input.lineColor } : {}),
-                ...(typeof input.height === 'number' ? { height: input.height } : {}),
-              },
-            });
+          : input.type === 'html-primitive'
+            ? validateStructuredCanvasPayload({
+                type: 'html-primitive',
+                primitive: {
+                  kind: (input.kind ?? input.primitive ?? '') as HtmlPrimitiveKind | '',
+                  ...(typeof input.title === 'string' ? { title: input.title } : {}),
+                  ...(input.primitiveData ? { data: input.primitiveData } : {}),
+                },
+              })
+            : validateStructuredCanvasPayload({
+                type: 'graph',
+                graph: {
+                  title: input.title,
+                  graphType: input.graphType ?? 'line',
+                  data: input.data ?? [],
+                  ...(typeof input.xKey === 'string' ? { xKey: input.xKey } : {}),
+                  ...(typeof input.yKey === 'string' ? { yKey: input.yKey } : {}),
+                  ...(typeof input.zKey === 'string' ? { zKey: input.zKey } : {}),
+                  ...(typeof input.nameKey === 'string' ? { nameKey: input.nameKey } : {}),
+                  ...(typeof input.valueKey === 'string' ? { valueKey: input.valueKey } : {}),
+                  ...(typeof input.axisKey === 'string' ? { axisKey: input.axisKey } : {}),
+                  ...(Array.isArray(input.metrics) ? { metrics: input.metrics } : {}),
+                  ...(Array.isArray(input.series) ? { series: input.series } : {}),
+                  ...(typeof input.barKey === 'string' ? { barKey: input.barKey } : {}),
+                  ...(typeof input.lineKey === 'string' ? { lineKey: input.lineKey } : {}),
+                  ...(typeof input.aggregate === 'string' ? { aggregate: input.aggregate } : {}),
+                  ...(typeof input.color === 'string' ? { color: input.color } : {}),
+                  ...(typeof input.barColor === 'string' ? { barColor: input.barColor } : {}),
+                  ...(typeof input.lineColor === 'string' ? { lineColor: input.lineColor } : {}),
+                  ...(typeof input.height === 'number' ? { height: input.height } : {}),
+                },
+              });
 
         return {
           content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -736,7 +792,7 @@ export async function startMcpServer(): Promise<void> {
           content: [{
             type: 'text',
             text: JSON.stringify({
-              ...await createdNodePayload(c, result.id),
+              ...(await createdNodePayload(c, result.id)),
               url: result.url,
               spec: result.spec,
             }, null, 2),
@@ -816,7 +872,7 @@ export async function startMcpServer(): Promise<void> {
           content: [{
             type: 'text',
             text: JSON.stringify({
-              ...await createdNodePayload(c, result.id),
+              ...(await createdNodePayload(c, result.id)),
               url: result.url,
               spec: result.spec,
             }, null, 2),
@@ -1759,6 +1815,8 @@ export async function startMcpServer(): Promise<void> {
     {
       limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
       query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
+      before: z.string().optional().describe('Only return snapshots created at or before this ISO timestamp'),
+      after: z.string().optional().describe('Only return snapshots created at or after this ISO timestamp'),
       all: z.boolean().optional().describe('Return all snapshots instead of the default limit'),
     },
     async (input) => {

package/src/server/agent-context.ts

@@ -155,6 +155,17 @@ function summarizeWebArtifactData(data: Record<string, unknown>, maxLength: numb
   return parts.length > 0 ? truncateContextText(parts.join('\n'), maxLength) : 'Web artifact node';
 }
 
+function summarizeHtmlPrimitiveData(data: Record<string, unknown>, maxLength: number): string {
+  const parts: string[] = [];
+  const primitive = typeof data.htmlPrimitive === 'string' ? data.htmlPrimitive : '';
+  const description = typeof data.description === 'string' ? data.description : '';
+  const primitiveData = data.primitiveData;
+  if (primitive) parts.push(`HTML primitive: ${primitive}`);
+  if (description) parts.push(description);
+  if (primitiveData !== undefined) parts.push(`Data: ${stringifyContextValue(primitiveData, maxLength)}`);
+  return truncateContextText(parts.join('\n'), maxLength);
+}
+
 function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undefined {
   switch (node.type) {
     case 'webpage': {
@@ -233,6 +244,12 @@ export function summarizeNodeForAgentContext(
       if (graphCfg) return truncateContextText(`Graph: ${JSON.stringify(graphCfg)}`, defaultTextLength);
       return stringifyContextValue(node.data.spec ?? {}, defaultTextLength);
     }
+    case 'html': {
+      if (typeof node.data.htmlPrimitive === 'string') {
+        return summarizeHtmlPrimitiveData(node.data, defaultTextLength);
+      }
+      return stringifyContextValue({ title: node.data.title, description: node.data.description }, defaultTextLength);
+    }
     case 'prompt':
     case 'response': {
       const text = (node.data.text as string) || (node.data.content as string) || '';

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,