pmx-canvas 0.1.16 → 0.1.17

package/src/mcp/canvas-access.ts

@@ -106,6 +106,7 @@ export interface CanvasAccess {
   buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
   updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
   removeNode(id: string): Promise<void>;
+  removeAnnotation(id: string): Promise<boolean>;
   addEdge(input: AddEdgeInput): Promise<string>;
   removeEdge(id: string): Promise<void>;
   createGroup(input: CreateGroupInput): Promise<string>;
@@ -203,6 +204,10 @@ class LocalCanvasAccess implements CanvasAccess {
     this.canvas.removeNode(id);
   }
 
+  async removeAnnotation(id: string): Promise<boolean> {
+    return this.canvas.removeAnnotation(id);
+  }
+
   async addEdge(input: AddEdgeInput): Promise<string> {
     return this.canvas.addEdge(input);
   }
@@ -455,6 +460,11 @@ class RemoteCanvasAccess implements CanvasAccess {
     await this.requestJson<unknown>('DELETE', `/api/canvas/node/${encodeURIComponent(id)}`);
   }
 
+  async removeAnnotation(id: string): Promise<boolean> {
+    const response = await this.requestJson<{ ok?: boolean }>('DELETE', `/api/canvas/annotation/${encodeURIComponent(id)}`);
+    return response.ok === true;
+  }
+
   async addEdge(input: AddEdgeInput): Promise<string> {
     const response = await this.requestJson<{ id?: string }>('POST', '/api/canvas/edge', input);
     if (!response.id) throw new Error('Canvas edge response did not include an edge id.');

package/src/mcp/server.ts

@@ -29,7 +29,7 @@ import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './ca
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
 import { wrapCanvasAutomationScript } from '../server/server.js';
 import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
-import { getCanvasNodeTitle, serializeCanvasLayout, serializeCanvasNode } from '../server/canvas-serialization.js';
+import { getCanvasNodeTitle, serializeCanvasLayout, serializeCanvasNode, summarizeCanvasAnnotationForContext } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 
 let canvas: CanvasAccess | null = null;
@@ -191,6 +191,7 @@ function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout
   return {
     summary: buildSummaryFromLayout(layout, pinnedIds),
     viewport: layout.viewport,
+    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
     nodes: layout.nodes.map((node) => compactNodePayload(node)).filter((node): node is Record<string, unknown> => node !== null),
     edges: layout.edges.map((edge) => ({
       id: edge.id,
@@ -204,6 +205,13 @@ function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout
   };
 }
 
+function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
+  return {
+    ...serializeCanvasLayout(layout),
+    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
+  };
+}
+
 function compactBatchValue(value: unknown): unknown {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
   const record = value as Record<string, unknown>;
@@ -248,6 +256,8 @@ function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayo
   return {
     totalNodes: layout.nodes.length,
     totalEdges: layout.edges.length,
+    totalAnnotations: (layout.annotations ?? []).length,
+    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
     nodesByType,
     pinnedCount: pinned.size,
     pinnedTitles,
@@ -263,6 +273,7 @@ function buildSnapshotRestoreSummary(layout: Awaited<ReturnType<CanvasAccess['ge
   return {
     nodeCount: layout.nodes.length,
     edgeCount: layout.edges.length,
+    annotationCount: (layout.annotations ?? []).length,
     nodesByType,
     viewport: layout.viewport,
   };
@@ -287,7 +298,7 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       const layout = await c.getLayout();
       const payload = wantsFullPayload(input)
-        ? serializeCanvasLayout(layout)
+        ? agentSafeFullLayoutPayload(layout)
         : compactLayoutPayload(layout, await c.getPinnedNodeIds());
       return {
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
@@ -902,6 +913,26 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  // ── canvas_remove_annotation ─────────────────────────────────────
+  server.tool(
+    'canvas_remove_annotation',
+    'Remove a human-drawn canvas annotation by ID.',
+    { id: z.string().describe('Annotation ID to remove') },
+    async ({ id }) => {
+      const c = await ensureCanvas();
+      const removed = await c.removeAnnotation(id);
+      if (!removed) {
+        return {
+          content: [{ type: 'text', text: `Annotation "${id}" not found.` }],
+          isError: true,
+        };
+      }
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, removed: id }) }],
+      };
+    },
+  );
+
   // ── canvas_add_edge ────────────────────────────────────────────
   server.tool(
     'canvas_add_edge',
@@ -1401,7 +1432,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const layout = serializeCanvasLayout(await c.getLayout());
+      const layout = agentSafeFullLayoutPayload(await c.getLayout());
       return {
         contents: [
           {
@@ -1452,7 +1483,7 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       const layout = await c.getLayout();
-      const spatial = buildSpatialContext(layout.nodes, layout.edges, new Set(await c.getPinnedNodeIds()));
+      const spatial = buildSpatialContext(layout.nodes, layout.edges, new Set(await c.getPinnedNodeIds()), layout.annotations ?? []);
       return {
         contents: [
           {

package/src/server/canvas-schema.ts

@@ -223,6 +223,31 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Webpage nodes persist `data.provenance` with the source URL and refresh strategy so reopened snapshots can be re-fetched.',
     ],
   },
+  {
+    type: 'html',
+    kind: 'node',
+    description: 'Sandboxed iframe node rendered from inline HTML.',
+    endpoint: '/api/canvas/node',
+    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: '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.' },
+      { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
+      { 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',
+      title: 'HTML Widget',
+      html: '<main><h1>Hello from PMX Canvas</h1></main>',
+    },
+    notes: [
+      'The CLI accepts --content as an alias and stores it as data.html so the renderer can load it.',
+      'HTML runs in a sandboxed iframe without same-origin access to the canvas host.',
+    ],
+  },
   {
     type: 'mcp-app',
     kind: 'node',

package/src/server/canvas-serialization.ts

@@ -1,5 +1,5 @@
 import { canvasState } from './canvas-state.js';
-import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import {
   normalizeCanvasNodeData,
   type CanvasNodeProvenance,
@@ -19,6 +19,26 @@ export interface SerializedCanvasLayout extends Omit<CanvasLayout, 'nodes'> {
   nodes: SerializedCanvasNode[];
 }
 
+export interface CanvasAnnotationSummary {
+  id: string;
+  type: CanvasAnnotation['type'];
+  bounds: CanvasAnnotation['bounds'];
+  color: string;
+  width: number;
+  pointCount: number;
+  label: string | null;
+  createdAt: string;
+}
+
+export interface CanvasAnnotationContextSummary {
+  id: string;
+  label: string | null;
+  bounds: CanvasAnnotation['bounds'];
+  targetNodeIds: string[];
+  targetNodeTitles: string[];
+  target: string;
+}
+
 interface BlobSummary {
   stored: 'sidecar';
   path: string;
@@ -104,9 +124,55 @@ export function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): Se
   };
 }
 
+export function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasAnnotationSummary {
+  return {
+    id: annotation.id,
+    type: annotation.type,
+    bounds: annotation.bounds,
+    color: annotation.color,
+    width: annotation.width,
+    pointCount: annotation.points.length,
+    label: annotation.label ?? null,
+    createdAt: annotation.createdAt,
+  };
+}
+
+function rectsOverlap(
+  a: { x: number; y: number; width: number; height: number },
+  b: { x: number; y: number; width: number; height: number },
+): boolean {
+  return a.x <= b.x + b.width &&
+    a.x + a.width >= b.x &&
+    a.y <= b.y + b.height &&
+    a.y + a.height >= b.y;
+}
+
+export function summarizeCanvasAnnotationForContext(
+  annotation: CanvasAnnotation,
+  nodes: CanvasNodeState[],
+): CanvasAnnotationContextSummary {
+  const targetNodes = nodes.filter((node) => rectsOverlap(annotation.bounds, {
+    x: node.position.x,
+    y: node.position.y,
+    width: node.size.width,
+    height: node.size.height,
+  }));
+  const targetNodeTitles = targetNodes.map((node) => getCanvasNodeTitle(node) ?? node.id);
+  return {
+    id: annotation.id,
+    label: annotation.label ?? null,
+    bounds: annotation.bounds,
+    targetNodeIds: targetNodes.map((node) => node.id),
+    targetNodeTitles,
+    target: targetNodeTitles.length > 0 ? targetNodeTitles.join(', ') : 'empty canvas region',
+  };
+}
+
 export interface CanvasSummary {
   totalNodes: number;
   totalEdges: number;
+  totalAnnotations: number;
+  annotations: CanvasAnnotationContextSummary[];
   nodesByType: Record<string, number>;
   pinnedCount: number;
   pinnedTitles: string[];
@@ -130,6 +196,8 @@ export function buildCanvasSummary(): CanvasSummary {
   return {
     totalNodes: layout.nodes.length,
     totalEdges: layout.edges.length,
+    totalAnnotations: layout.annotations.length,
+    annotations: layout.annotations.map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
     nodesByType: typeCounts,
     pinnedCount: pinnedIds.size,
     pinnedTitles,

package/src/server/canvas-state.ts

@@ -64,6 +64,7 @@ interface PersistedCanvasState {
   viewport: ViewportState;
   nodes: CanvasNodeState[];
   edges: CanvasEdge[];
+  annotations?: CanvasAnnotation[];
   contextPins: string[];
 }
 
@@ -146,10 +147,27 @@ export interface CanvasEdge {
   animated?: boolean;
 }
 
+export interface CanvasAnnotationPoint {
+  x: number;
+  y: number;
+}
+
+export interface CanvasAnnotation {
+  id: string;
+  type: 'freehand';
+  points: CanvasAnnotationPoint[];
+  bounds: { x: number; y: number; width: number; height: number };
+  color: string;
+  width: number;
+  label?: string;
+  createdAt: string;
+}
+
 export interface CanvasLayout {
   viewport: ViewportState;
   nodes: CanvasNodeState[];
   edges: CanvasEdge[];
+  annotations: CanvasAnnotation[];
 }
 
 export interface CanvasNodeUpdate {
@@ -163,7 +181,7 @@ export interface CanvasNodeUpdate {
 export type CanvasChangeType = 'pins' | 'nodes';
 
 export interface MutationRecordInfo {
-  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
   description: string;
   forward: () => void;
   inverse: () => void;
@@ -215,6 +233,7 @@ function isPersistedBlobRef(value: unknown): value is PersistedBlobRef {
 class CanvasStateManager {
   private nodes = new Map<string, CanvasNodeState>();
   private edges = new Map<string, CanvasEdge>();
+  private annotations = new Map<string, CanvasAnnotation>();
   private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
   private _contextPinnedNodeIds = new Set<string>();
   private _workspaceRoot = process.cwd();
@@ -607,6 +626,7 @@ class CanvasStateManager {
       viewport: { x: 0, y: 0, scale: 1 },
       nodes: [],
       edges: [],
+      annotations: [],
       contextPins: [],
     };
   }
@@ -663,6 +683,7 @@ class CanvasStateManager {
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
+        annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
       });
       writeFileSync(this._stateFilePath, JSON.stringify(payload, null, 2), 'utf-8');
@@ -683,6 +704,7 @@ class CanvasStateManager {
   private applyPersistedState(state: PersistedCanvasState): void {
     this.nodes.clear();
     this.edges.clear();
+    this.annotations.clear();
     this._contextPinnedNodeIds.clear();
 
     this._viewport = {
@@ -703,6 +725,11 @@ class CanvasStateManager {
         if (edge?.id) this.edges.set(edge.id, structuredClone(edge));
       }
     }
+    if (Array.isArray(state.annotations)) {
+      for (const annotation of state.annotations) {
+        if (annotation?.id) this.annotations.set(annotation.id, structuredClone(annotation));
+      }
+    }
     if (Array.isArray(state.contextPins)) {
       for (const pinId of state.contextPins) {
         if (this.nodes.has(pinId)) this._contextPinnedNodeIds.add(pinId);
@@ -798,9 +825,12 @@ class CanvasStateManager {
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
+        annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
       });
       writeFileSync(join(dir, `${id}.json`), JSON.stringify(payload, null, 2), 'utf-8');
+      snapshot.nodeCount = payload.nodes.length;
+      snapshot.edgeCount = payload.edges.length;
       return snapshot;
     } catch (error) {
       logCanvasStateWarning('save snapshot failed', error, { id, name });
@@ -870,6 +900,7 @@ class CanvasStateManager {
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
+      annotations: Array.from(this.annotations.values(), (annotation) => structuredClone(annotation)),
       contextPins: Array.from(this._contextPinnedNodeIds),
     });
     const nextState: PersistedCanvasState = {
@@ -877,6 +908,7 @@ class CanvasStateManager {
       viewport: structuredClone(resolved.state.viewport),
       nodes: Array.isArray(resolved.state.nodes) ? resolved.state.nodes.map((node) => structuredClone(node)) : [],
       edges: Array.isArray(resolved.state.edges) ? resolved.state.edges.map((edge) => structuredClone(edge)) : [],
+      annotations: Array.isArray(resolved.state.annotations) ? resolved.state.annotations.map((annotation) => structuredClone(annotation)) : [],
       contextPins: Array.isArray(resolved.state.contextPins) ? [...resolved.state.contextPins] : [],
     };
 
@@ -913,7 +945,7 @@ 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[] } | null {
+  getSnapshotData(idOrName: string): { name: string; nodes: CanvasNodeState[]; edges: CanvasEdge[]; annotations: CanvasAnnotation[] } | null {
     const resolved = this.readResolvedSnapshot(idOrName);
     if (!resolved) return null;
     const state = {
@@ -926,6 +958,7 @@ class CanvasStateManager {
       name: resolved.snapshot.name,
       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) ? state.annotations.map((annotation) => structuredClone(annotation)) : [],
     };
   }
 
@@ -1110,6 +1143,40 @@ class CanvasStateManager {
       .map((edge) => structuredClone(edge));
   }
 
+  addAnnotation(annotation: CanvasAnnotation): void {
+    const cloned = structuredClone(annotation);
+    this.annotations.set(annotation.id, cloned);
+    this.scheduleSave();
+    this.notifyChange('nodes');
+    this.recordMutation({
+      operationType: 'addAnnotation',
+      description: `Added annotation ${annotation.id}`,
+      forward: this.suppressed(() => this.addAnnotation(structuredClone(cloned))),
+      inverse: this.suppressed(() => this.removeAnnotation(annotation.id)),
+    });
+  }
+
+  removeAnnotation(id: string): boolean {
+    const existing = this.annotations.get(id);
+    const removed = this.annotations.delete(id);
+    if (removed && existing) {
+      const cloned = structuredClone(existing);
+      this.scheduleSave();
+      this.notifyChange('nodes');
+      this.recordMutation({
+        operationType: 'removeAnnotation',
+        description: `Removed annotation ${id}`,
+        forward: this.suppressed(() => this.removeAnnotation(id)),
+        inverse: this.suppressed(() => this.addAnnotation(structuredClone(cloned))),
+      });
+    }
+    return removed;
+  }
+
+  getAnnotations(): CanvasAnnotation[] {
+    return Array.from(this.annotations.values(), (annotation) => structuredClone(annotation));
+  }
+
   private removeEdgesForNode(nodeId: string): void {
     for (const [id, edge] of this.edges) {
       if (edge.from === nodeId || edge.to === nodeId) {
@@ -1123,6 +1190,7 @@ class CanvasStateManager {
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
+      annotations: this.getAnnotations(),
     };
   }
 
@@ -1131,6 +1199,7 @@ class CanvasStateManager {
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.externalizeNodeDataBlobs(node))),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
+      annotations: this.getAnnotations(),
     };
   }
 
@@ -1376,10 +1445,12 @@ class CanvasStateManager {
   clear(): void {
     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));
     const oldPins = Array.from(this._contextPinnedNodeIds);
     const oldViewport = { ...this._viewport };
     this.nodes.clear();
     this.edges.clear();
+    this.annotations.clear();
     this._contextPinnedNodeIds.clear();
     this._viewport = { x: 0, y: 0, scale: 1 };
     this.scheduleSave();
@@ -1392,6 +1463,7 @@ class CanvasStateManager {
       inverse: this.suppressed(() => {
         for (const n of oldNodes) this.addNode(structuredClone(n));
         for (const e of oldEdges) this.addEdge(structuredClone(e));
+        for (const annotation of oldAnnotations) this.addAnnotation(structuredClone(annotation));
         this.setContextPins(oldPins);
         this.setViewport(oldViewport);
       }),

package/src/server/diagram-presets.ts

@@ -120,18 +120,33 @@ function positiveFiniteNumber(value: unknown): number | null {
   return num !== null && num > 0 ? num : null;
 }
 
+function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boolean {
+  return elements.some((element) => element.type === 'cameraUpdate');
+}
+
+function isTextBindableContainer(element: Record<string, unknown>): boolean {
+  return element.type === 'rectangle' || element.type === 'ellipse' || element.type === 'diamond';
+}
+
 function labelFromBoundText(element: Record<string, unknown>): Record<string, unknown> | null {
   const text = typeof element.text === 'string' ? element.text : '';
   if (text.trim().length === 0) return null;
   const fontSize = positiveFiniteNumber(element.fontSize);
+  const textAlign = typeof element.textAlign === 'string' ? element.textAlign : null;
+  const verticalAlign = typeof element.verticalAlign === 'string' ? element.verticalAlign : null;
   return {
     text,
     ...(fontSize ? { fontSize } : {}),
+    ...(textAlign ? { textAlign } : {}),
+    ...(verticalAlign ? { verticalAlign } : {}),
   };
 }
 
-function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boolean {
-  return elements.some((element) => element.type === 'cameraUpdate');
+function boundTextRefId(value: unknown): string | null {
+  if (!isRecord(value) || value.type !== 'text' || typeof value.id !== 'string' || value.id.length === 0) {
+    return null;
+  }
+  return value.id;
 }
 
 function hasRenderableExcalidrawElement(elements: Array<Record<string, unknown>>): boolean {
@@ -153,37 +168,57 @@ function normalizeExcalidrawBoundText(elements: Array<Record<string, unknown>>):
   }
 
   let changed = false;
+  const containerIdByTextId = new Map<string, string>();
   const labelsByContainer = new Map<string, Record<string, unknown>>();
+  const collapsedTextIds = new Set<string>();
+
+  for (const container of elements) {
+    if (!isTextBindableContainer(container) || typeof container.id !== 'string' || !Array.isArray(container.boundElements)) continue;
+    for (const rawBoundElement of container.boundElements) {
+      const textId = boundTextRefId(rawBoundElement);
+      if (!textId) continue;
+      const textElement = elementsById.get(textId);
+      if (textElement?.type !== 'text') continue;
+      if (typeof textElement.containerId !== 'string') {
+        containerIdByTextId.set(textId, container.id);
+      }
+    }
+  }
 
   for (const element of elements) {
-    if (element.type !== 'text' || typeof element.id !== 'string' || typeof element.containerId !== 'string') continue;
-    const container = elementsById.get(element.containerId);
-    if (!container || (container.type !== 'rectangle' && container.type !== 'ellipse' && container.type !== 'diamond')) continue;
+    if (element.type !== 'text' || typeof element.id !== 'string') continue;
+    const containerId = typeof element.containerId === 'string'
+      ? element.containerId
+      : containerIdByTextId.get(element.id);
+    if (!containerId) continue;
+    const container = elementsById.get(containerId);
+    if (!container || !isTextBindableContainer(container)) continue;
     const label = labelFromBoundText(element);
     if (!label) continue;
-    labelsByContainer.set(element.containerId, label);
+    labelsByContainer.set(containerId, label);
+    collapsedTextIds.add(element.id);
   }
 
+  if (labelsByContainer.size === 0) return elements;
+
   const normalized: Array<Record<string, unknown>> = [];
   for (const element of elements) {
-    if (element.type === 'text' && typeof element.containerId === 'string') {
-      if (labelsByContainer.has(element.containerId)) {
-        changed = true;
-        continue;
-      }
+    if (typeof element.id === 'string' && collapsedTextIds.has(element.id)) {
+      changed = true;
+      continue;
     }
 
-    if (typeof element.id !== 'string' || !labelsByContainer.has(element.id)) {
-      normalized.push(element);
+    if (typeof element.id === 'string' && labelsByContainer.has(element.id)) {
+      changed = true;
+      const { boundElements: _boundElements, ...container } = element;
+      normalized.push({
+        ...container,
+        label: labelsByContainer.get(element.id),
+      });
       continue;
     }
 
-    changed = true;
-    const { boundElements: _boundElements, ...container } = element;
-    normalized.push({
-      ...container,
-      label: labelsByContainer.get(element.id),
-    });
+    normalized.push(element);
   }
 
   return changed ? normalized : elements;

package/src/server/index.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
-import type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
 import { findCanvasExtAppNodeId } from './ext-app-lookup.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
@@ -314,6 +314,23 @@ export class PmxCanvas extends EventEmitter {
     return id;
   }
 
+  addAnnotation(input: Omit<CanvasAnnotation, 'id' | 'createdAt'> & { id?: string; createdAt?: string }): string {
+    const id = input.id ?? `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    canvasState.addAnnotation({
+      ...input,
+      id,
+      createdAt: input.createdAt ?? new Date().toISOString(),
+    });
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return id;
+  }
+
+  removeAnnotation(id: string): boolean {
+    const removed = canvasState.removeAnnotation(id);
+    if (removed) emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return removed;
+  }
+
   removeEdge(id: string): void {
     removeCanvasEdge(id);
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -416,7 +433,7 @@ export class PmxCanvas extends EventEmitter {
 
   getSpatialContext() {
     const layout = canvasState.getLayout();
-    return buildSpatialContext(layout.nodes, layout.edges, canvasState.contextPinnedNodeIds);
+    return buildSpatialContext(layout.nodes, layout.edges, canvasState.contextPinnedNodeIds, layout.annotations);
   }
 
   async undo(): Promise<{ ok: boolean; description?: string }> {
@@ -723,7 +740,7 @@ export {
   screenshotCanvasAutomationWebView,
 } from './server.js';
 export { canvasState } from './canvas-state.js';
-export type { CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
+export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';
 export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo } from './spatial-analysis.js';

package/src/server/mutation-history.ts

@@ -22,6 +22,8 @@ export type MutationOp =
   | 'removeNode'
   | 'addEdge'
   | 'removeEdge'
+  | 'addAnnotation'
+  | 'removeAnnotation'
   | 'clear'
   | 'arrange'
   | 'restoreSnapshot'