pmx-canvas 0.1.16 → 0.1.18

package/src/client/state/canvas-store.ts

@@ -1,5 +1,5 @@
 import { batch, computed, signal } from '@preact/signals';
-import { isExcalidrawNode, type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
+import { isExcalidrawNode, type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
 import { computeAutoArrange } from '../../shared/auto-arrange';
 import { pushCanvasUpdate, updateViewportFromClient } from './intent-bridge';
 
@@ -11,6 +11,7 @@ function logCanvasStoreError(action: string, error: unknown): void {
 export const viewport = signal<ViewportState>({ x: 0, y: 0, scale: 1 });
 export const nodes = signal<Map<string, CanvasNodeState>>(new Map());
 export const edges = signal<Map<string, CanvasEdge>>(new Map());
+export const annotations = signal<Map<string, CanvasAnnotation>>(new Map());
 export const activeNodeId = signal<string | null>(null);
 export const connectionStatus = signal<ConnectionStatus>('connecting');
 export const sessionId = signal<string>('');
@@ -258,6 +259,50 @@ export function removeEdgesForNode(nodeId: string): void {
   if (changed) edges.value = next;
 }
 
+export function addAnnotation(annotation: CanvasAnnotation): void {
+  const next = new Map(annotations.value);
+  next.set(annotation.id, annotation);
+  annotations.value = next;
+}
+
+export function removeAnnotation(id: string): void {
+  const next = new Map(annotations.value);
+  if (!next.delete(id)) return;
+  annotations.value = next;
+}
+
+export async function createAnnotationFromClient(input: {
+  points: CanvasAnnotation['points'];
+  color: string;
+  width: number;
+  label?: string;
+}): Promise<{ ok: boolean }> {
+  try {
+    const res = await fetch('/api/canvas/annotation', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input),
+    });
+    return { ok: res.ok };
+  } catch (error) {
+    logCanvasStoreError('createAnnotationFromClient', error);
+    return { ok: false };
+  }
+}
+
+export async function removeAnnotationFromClient(id: string): Promise<{ ok: boolean }> {
+  try {
+    const res = await fetch(`/api/canvas/annotation/${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+    });
+    if (res.ok) removeAnnotation(id);
+    return { ok: res.ok };
+  } catch (error) {
+    logCanvasStoreError('removeAnnotationFromClient', error);
+    return { ok: false };
+  }
+}
+
 export function resizeNode(id: string, size: { width: number; height: number }): void {
   const existing = nodes.value.get(id);
   if (!existing) return;
@@ -343,7 +388,7 @@ function commitViewportWithOptions(
 }
 
 export function applyServerCanvasLayout(
-  layout: Pick<CanvasLayout, 'nodes' | 'edges'> & { viewport?: ViewportState },
+  layout: Pick<CanvasLayout, 'nodes' | 'edges'> & { viewport?: ViewportState; annotations?: CanvasAnnotation[] },
   options: { applyViewport?: boolean } = {},
 ): void {
   const nextNodes = new Map<string, CanvasNodeState>();
@@ -360,6 +405,10 @@ export function applyServerCanvasLayout(
   for (const edge of edgeSource) {
     nextEdges.set(edge.id, edge);
   }
+  const nextAnnotations = new Map<string, CanvasAnnotation>();
+  for (const annotation of layout.annotations ?? []) {
+    nextAnnotations.set(annotation.id, annotation);
+  }
 
   const nextActiveNodeId =
     activeNodeId.value !== null && nextNodes.has(activeNodeId.value) ? activeNodeId.value : null;
@@ -375,6 +424,7 @@ export function applyServerCanvasLayout(
     maxZ = nextMaxZ;
     nodes.value = nextNodes;
     edges.value = nextEdges;
+    annotations.value = nextAnnotations;
     activeNodeId.value = nextActiveNodeId;
     expandedNodeId.value = nextExpandedNodeId;
     if (!sameSetValues(selectedNodeIds.value, nextSelectedNodeIds)) {

package/src/client/state/sse-bridge.ts

@@ -1,6 +1,6 @@
 import { findOpenCanvasPosition } from '../utils/placement.js';
 import { normalizeExtAppToolResult } from '../utils/ext-app-tool-result.js';
-import type { CanvasEdge, CanvasNodeState } from '../types';
+import type { CanvasAnnotation, CanvasEdge, CanvasNodeState } from '../types';
 import {
   activeNodeId,
   addEdge,
@@ -310,6 +310,7 @@ function isCanvasNodeType(value: unknown): value is CanvasNodeState['type'] {
     || value === 'trace'
     || value === 'file'
     || value === 'image'
+    || value === 'html'
     || value === 'group';
 }
 
@@ -334,6 +335,12 @@ function parseCanvasSize(value: unknown): { width: number; height: number } | nu
   return { width: size.width, height: size.height };
 }
 
+function parseCanvasRect(value: unknown): { x: number; y: number; width: number; height: number } | null {
+  const position = parseCanvasPosition(value);
+  const size = parseCanvasSize(value);
+  return position && size ? { ...position, ...size } : null;
+}
+
 function parseCanvasNode(raw: Record<string, unknown>): CanvasNodeState | null {
   if (typeof raw.id !== 'string' || !raw.id) return null;
   if (!isCanvasNodeType(raw.type)) return null;
@@ -379,6 +386,28 @@ function parseCanvasEdge(raw: Record<string, unknown>): CanvasEdge | null {
   };
 }
 
+function parseCanvasAnnotation(raw: Record<string, unknown>): CanvasAnnotation | null {
+  if (typeof raw.id !== 'string' || !raw.id) return null;
+  if (raw.type !== 'freehand') return null;
+  if (!Array.isArray(raw.points)) return null;
+  const points = raw.points
+    .map((point) => parseCanvasPosition(point))
+    .filter((point): point is { x: number; y: number } => point !== null);
+  const bounds = parseCanvasRect(raw.bounds);
+  if (points.length < 2 || !bounds) return null;
+
+  return {
+    id: raw.id,
+    type: 'freehand',
+    points,
+    bounds,
+    color: typeof raw.color === 'string' ? raw.color : '#f97316',
+    width: typeof raw.width === 'number' ? raw.width : 4,
+    ...(typeof raw.label === 'string' ? { label: raw.label } : {}),
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : '',
+  };
+}
+
 // ── SSE event handlers ───────────────────────────────────────
 function handleConnected(data: Record<string, unknown>): void {
   sessionId.value = (data.sessionId as string) || '';
@@ -801,6 +830,7 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
     | {
         nodes?: Array<Record<string, unknown>>;
         edges?: Array<Record<string, unknown>>;
+        annotations?: Array<Record<string, unknown>>;
         viewport?: Record<string, unknown>;
       }
     | undefined;
@@ -814,6 +844,9 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
   const serverEdges = Array.isArray(layout.edges)
     ? layout.edges.map(parseCanvasEdge).filter((edge): edge is CanvasEdge => edge !== null)
     : Array.from(edges.value.values());
+  const serverAnnotations = Array.isArray(layout.annotations)
+    ? layout.annotations.map(parseCanvasAnnotation).filter((annotation): annotation is CanvasAnnotation => annotation !== null)
+    : undefined;
   const nextViewport = layout.viewport
     ? {
         x: typeof layout.viewport.x === 'number' ? layout.viewport.x : 0,
@@ -827,6 +860,7 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
     ...(nextViewport ? { viewport: nextViewport } : {}),
     nodes: serverNodes,
     edges: serverEdges,
+    ...(serverAnnotations ? { annotations: serverAnnotations } : {}),
   }, { applyViewport: shouldApplyViewport });
 
   syncAttentionFromSse({ event: 'canvas-layout-update', data });

package/src/client/theme/global.css

@@ -50,6 +50,7 @@
   --c-accent-hover: #6ECAFF;
   --c-warn-hover: #f5d06b;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.02), rgba(0, 0, 0, 0));
+  --c-annotation: #F4EFE6;
   /* ── Non-color tokens ────────────────────────────────────── */
   --font: "IBM Plex Sans", "SF Pro Text", "Avenir Next", system-ui, sans-serif;
   --mono: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
@@ -109,6 +110,7 @@
   --c-accent-hover: #1588CE;
   --c-warn-hover: #dab040;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.12), rgba(8, 21, 36, 0.02));
+  --c-annotation: #081524;
 }
 
 :root[data-theme="high-contrast"] {
@@ -162,6 +164,7 @@
   --c-accent-hover: #33ffff;
   --c-warn-hover: #ffff33;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.03), rgba(255, 255, 255, 0));
+  --c-annotation: #ffff00;
 }
 
 * {
@@ -1471,6 +1474,28 @@ body,
   z-index: 9998;
 }
 
+.annotation-layer {
+  position: absolute;
+  inset: 0;
+  width: 1px;
+  height: 1px;
+  overflow: visible;
+  pointer-events: none;
+  z-index: 45;
+}
+
+.annotation-capture-layer {
+  position: absolute;
+  inset: 0;
+  z-index: 9996;
+  pointer-events: none;
+  background: color-mix(in srgb, var(--c-accent) 5%, transparent);
+}
+
+.annotation-capture-layer.erasing {
+  background: color-mix(in srgb, var(--c-danger) 6%, transparent);
+}
+
 /* ── Drop Zone (file drag-and-drop) ─────────────────────────── */
 .drop-zone-overlay {
   position: absolute;

package/src/client/types.ts

@@ -41,6 +41,22 @@ 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 type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 
 // ── Shared constants for node type display ──────────────────
@@ -93,4 +109,5 @@ export interface CanvasLayout {
   viewport: ViewportState;
   nodes: CanvasNodeState[];
   edges: CanvasEdge[];
+  annotations?: CanvasAnnotation[];
 }

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,13 @@ 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,
+  serializeCanvasLayoutForAgent,
+  serializeCanvasNode,
+  serializeCanvasNodeForAgent,
+  summarizeCanvasAnnotationForContext,
+} from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 
 let canvas: CanvasAccess | null = null;
@@ -191,6 +197,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 +211,13 @@ function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout
   };
 }
 
+function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
+  return {
+    ...serializeCanvasLayoutForAgent(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>;
@@ -232,7 +246,7 @@ async function createdNodePayload(c: CanvasAccess, id: string, options: { full?:
   if (!wantsFullPayload(options)) {
     return { ok: true, node: compactNodePayload(node), id };
   }
-  const serialized = serializeCanvasNode(node);
+  const serialized = serializeCanvasNodeForAgent(node);
   return { ok: true, node: serialized, ...serialized };
 }
 
@@ -248,6 +262,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 +279,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 +304,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) }],
@@ -313,7 +330,7 @@ export async function startMcpServer(): Promise<void> {
           isError: true,
         };
       }
-      const payload = wantsFullPayload(input) ? serializeCanvasNode(node) : compactNodePayload(node);
+      const payload = wantsFullPayload(input) ? serializeCanvasNodeForAgent(node) : compactNodePayload(node);
       return {
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };
@@ -902,6 +919,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 +1438,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 +1489,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,6 @@
+import { createHash } from 'node:crypto';
 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 +20,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;
@@ -27,6 +48,13 @@ interface BlobSummary {
   sha256: string;
 }
 
+interface ExternalMcpAppHtmlSummary {
+  omitted: 'external-mcp-app-html';
+  resourceUri: string;
+  bytes: number;
+  sha256: string;
+}
+
 function pickString(value: unknown): string | null {
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -70,6 +98,39 @@ export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode
   };
 }
 
+function summarizeExternalMcpAppHtml(node: SerializedCanvasNode): Record<string, unknown> {
+  const html = node.data.html;
+  const resourceUri = node.data.resourceUri;
+  if (
+    node.type !== 'mcp-app' ||
+    node.data.mode !== 'ext-app' ||
+    typeof html !== 'string' ||
+    html.length === 0 ||
+    typeof resourceUri !== 'string' ||
+    resourceUri.length === 0
+  ) {
+    return node.data;
+  }
+
+  return {
+    ...node.data,
+    html: {
+      omitted: 'external-mcp-app-html',
+      resourceUri,
+      bytes: Buffer.byteLength(html, 'utf-8'),
+      sha256: createHash('sha256').update(html).digest('hex'),
+    } satisfies ExternalMcpAppHtmlSummary,
+  };
+}
+
+export function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode {
+  const serialized = serializeCanvasNode(node);
+  return {
+    ...serialized,
+    data: summarizeExternalMcpAppHtml(serialized),
+  };
+}
+
 function summarizeBlobValue(value: unknown): unknown {
   if (!canvasState.isBlobReference(value)) return value;
   return {
@@ -97,6 +158,13 @@ export function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLay
   };
 }
 
+export function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout {
+  return {
+    ...layout,
+    nodes: layout.nodes.map(serializeCanvasNodeForAgent),
+  };
+}
+
 export function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout {
   return {
     ...layout,
@@ -104,9 +172,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 +244,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,