pmx-canvas 0.1.16 → 0.1.17

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';
@@ -1227,6 +1228,72 @@ async function handleCanvasViewport(req: Request): Promise<Response> {
   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/', '');
@@ -4002,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);
           }
@@ -4117,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);