pmx-canvas 0.1.15 → 0.1.17

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'

package/src/server/server.ts

@@ -46,7 +46,7 @@ import type {
   ListResourceTemplatesResult,
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
-import { type CanvasEdge, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { type CanvasAnnotation, type CanvasEdge, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
@@ -71,6 +71,7 @@ import {
   serializeCanvasLayoutWithBlobSummaries,
   serializeCanvasNode,
   serializeCanvasNodeWithBlobSummaries,
+  summarizeCanvasAnnotation,
 } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
@@ -1216,11 +1217,83 @@ async function handleCanvasViewport(req: Request): Promise<Response> {
     y: typeof body.y === 'number' ? body.y : canvasState.viewport.y,
     scale: typeof body.scale === 'number' ? body.scale : canvasState.viewport.scale,
   };
-  canvasState.setViewport(next);
+  if (body.recordHistory === false) {
+    canvasState.withSuppressedRecording(() => {
+      canvasState.setViewport(next);
+    });
+  } else {
+    canvasState.setViewport(next);
+  }
   emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
   return responseJson({ ok: true });
 }
 
+function annotationBounds(points: CanvasAnnotation['points']): CanvasAnnotation['bounds'] {
+  const xs = points.map((point) => point.x);
+  const ys = points.map((point) => point.y);
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  const maxX = Math.max(...xs);
+  const maxY = Math.max(...ys);
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+function parseAnnotationPoints(value: unknown): CanvasAnnotation['points'] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((point) => {
+      if (!point || typeof point !== 'object' || Array.isArray(point)) return null;
+      const record = point as Record<string, unknown>;
+      if (typeof record.x !== 'number' || typeof record.y !== 'number') return null;
+      if (!Number.isFinite(record.x) || !Number.isFinite(record.y)) return null;
+      return { x: record.x, y: record.y };
+    })
+    .filter((point): point is CanvasAnnotation['points'][number] => point !== null);
+}
+
+async function handleCanvasAddAnnotation(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const points = parseAnnotationPoints(body.points);
+  if (points.length < 2) {
+    return responseJson({ ok: false, error: 'Annotation requires at least two valid points.' }, 400);
+  }
+
+  const width = typeof body.width === 'number' && Number.isFinite(body.width)
+    ? Math.min(24, Math.max(1, body.width))
+    : 4;
+  const color = typeof body.color === 'string' && (body.color === 'currentColor' || /^#[0-9a-fA-F]{6}$/.test(body.color))
+    ? body.color
+    : 'currentColor';
+  const label = typeof body.label === 'string' && body.label.trim().length > 0
+    ? body.label.trim().slice(0, 160)
+    : undefined;
+  const id = typeof body.id === 'string' && body.id.trim().length > 0
+    ? body.id.trim().slice(0, 120)
+    : `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const annotation: CanvasAnnotation = {
+    id,
+    type: 'freehand',
+    points,
+    bounds: annotationBounds(points),
+    color,
+    width,
+    ...(label ? { label } : {}),
+    createdAt: new Date().toISOString(),
+  };
+
+  canvasState.addAnnotation(annotation);
+  emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  return responseJson({ ok: true, annotation: summarizeCanvasAnnotation(annotation) });
+}
+
+function handleCanvasRemoveAnnotation(id: string): Response {
+  const decodedId = decodeURIComponent(id);
+  const removed = canvasState.removeAnnotation(decodedId);
+  if (!removed) return responseJson({ ok: false, error: `Annotation "${decodedId}" not found.` }, 404);
+  emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  return responseJson({ ok: true, removed: decodedId });
+}
+
 // ── Serve image file for image nodes ─────────────────────────
 async function handleCanvasImage(pathname: string): Promise<Response> {
   const nodeId = pathname.replace('/api/canvas/image/', '');
@@ -1338,6 +1411,14 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
+  if (type === 'html') {
+    if ('html' in body && typeof body.html !== 'string') {
+      return responseJson({ ok: false, error: 'HTML node field "html" must be a string.' }, 400);
+    }
+    if (extraData && 'html' in extraData && typeof extraData.html !== 'string') {
+      return responseJson({ ok: false, error: 'HTML node field "data.html" must be a string.' }, 400);
+    }
+  }
   const content = type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string'
     ? body.path
     : body.content;
@@ -1395,6 +1476,15 @@ async function handleCanvasCreateGroup(req: Request): Promise<Response> {
     body.childLayout === 'grid' || body.childLayout === 'column' || body.childLayout === 'flow'
       ? body.childLayout
       : undefined;
+  if (childIds.length > 0) {
+    const missingChildIds = childIds.filter((id) => !canvasState.getNode(id));
+    if (missingChildIds.length > 0) {
+      return responseJson({
+        ok: false,
+        error: `Cannot create group: missing child node ID${missingChildIds.length === 1 ? '' : 's'}: ${missingChildIds.join(', ')}.`,
+      }, 400);
+    }
+  }
 
   const { node } = createCanvasGroup({ title, childIds, color, x, y, width, height, ...(childLayout ? { childLayout } : {}) });
 
@@ -3979,6 +4069,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleCanvasViewport(req);
           }
 
+          if (url.pathname === '/api/canvas/annotation' && req.method === 'POST') {
+            return handleCanvasAddAnnotation(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/annotation/') && req.method === 'DELETE') {
+            return handleCanvasRemoveAnnotation(url.pathname.slice('/api/canvas/annotation/'.length));
+          }
+
           if (url.pathname === '/api/canvas/node' && req.method === 'POST') {
             return handleCanvasAddNode(req);
           }
@@ -4094,7 +4192,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           // Spatial context API
           if (url.pathname === '/api/canvas/spatial-context' && req.method === 'GET') {
             const layout = canvasState.getLayout();
-            const spatial = buildSpatialContext(layout.nodes, layout.edges, canvasState.contextPinnedNodeIds);
+            const spatial = buildSpatialContext(layout.nodes, layout.edges, canvasState.contextPinnedNodeIds, layout.annotations);
             return responseJson(spatial);
           }
 

package/src/server/spatial-analysis.ts

@@ -10,7 +10,7 @@
  * semantic clusters, ordered context, and implicit human intent.
  */
 
-import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge } from './canvas-state.js';
 import { summarizeNodeForAgentContext } from './agent-context.js';
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -45,6 +45,15 @@ export interface NodeSpatialInfo {
   readingOrder: number;
 }
 
+export interface SpatialAnnotationContext {
+  id: string;
+  label: string | null;
+  bounds: CanvasAnnotation['bounds'];
+  targetNodeIds: string[];
+  targetNodeTitles: string[];
+  target: string;
+}
+
 export interface SpatialContext {
   /** Total nodes on canvas */
   totalNodes: number;
@@ -58,6 +67,7 @@ export interface SpatialContext {
     pinnedNodeTitle: string | null;
     neighbors: SpatialNeighbor[];
   }[];
+  annotations: SpatialAnnotationContext[];
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -125,6 +135,39 @@ function deriveClusterLabel(nodes: CanvasNodeState[]): string {
   return parts.join(', ');
 }
 
+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;
+}
+
+function summarizeAnnotationForSpatialContext(
+  annotation: CanvasAnnotation,
+  nodes: CanvasNodeState[],
+): SpatialAnnotationContext {
+  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) =>
+    typeof node.data.title === 'string' && node.data.title.length > 0 ? node.data.title : 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',
+  };
+}
+
 // ── Core Analysis ────────────────────────────────────────────────────
 
 /**
@@ -320,6 +363,7 @@ export function buildSpatialContext(
   nodes: CanvasNodeState[],
   _edges: CanvasEdge[],
   pinnedIds: Set<string>,
+  annotations: CanvasAnnotation[] = [],
 ): SpatialContext {
   const clusters = detectClusters(nodes);
 
@@ -352,5 +396,6 @@ export function buildSpatialContext(
     clusters,
     nodesInReadingOrder,
     pinnedNeighborhoods,
+    annotations: annotations.map((annotation) => summarizeAnnotationForSpatialContext(annotation, nodes)),
   };
 }

package/src/shared/semantic-attention.ts

@@ -371,6 +371,7 @@ export class SemanticWatchReducer {
       this.currentLayout.nodes,
       this.currentLayout.edges,
       this.currentPins,
+      this.currentLayout.annotations ?? [],
     );
 
     if (previousEventPins.added.length === 0 && previousEventPins.removed.length === 0) {
@@ -394,7 +395,7 @@ export class SemanticWatchReducer {
     const meta = normalizeEventMeta(payload);
     if (!this.currentLayout) {
       this.currentLayout = layout;
-      this.previousSpatial = buildSpatialContext(layout.nodes, layout.edges, this.currentPins);
+      this.previousSpatial = buildSpatialContext(layout.nodes, layout.edges, this.currentPins, layout.annotations ?? []);
       return [];
     }
 
@@ -403,8 +404,9 @@ export class SemanticWatchReducer {
       prevLayout.nodes,
       prevLayout.edges,
       this.currentPins,
+      prevLayout.annotations ?? [],
     );
-    const nextSpatial = buildSpatialContext(layout.nodes, layout.edges, this.currentPins);
+    const nextSpatial = buildSpatialContext(layout.nodes, layout.edges, this.currentPins, layout.annotations ?? []);
     const events: SemanticWatchEvent[] = [];
 
     const prevNodeMap = toNodeMap(prevLayout.nodes);