pmx-canvas 0.1.16 → 0.1.17

package/src/client/canvas/CanvasViewport.tsx

@@ -20,16 +20,20 @@ import {
   draggingEdge,
   edges,
   expandedNodeId,
+  annotations,
   nodes,
   selectNodes,
   setViewport,
   viewport,
+  createAnnotationFromClient,
+  removeAnnotationFromClient,
 } from '../state/canvas-store';
 import { createEdgeFromClient, createNodeFromClient } from '../state/intent-bridge';
-import type { CanvasNodeState } from '../types';
+import type { CanvasAnnotation, CanvasNodeState } from '../types';
 import { FocusFieldLayer } from './FocusFieldLayer';
 import { CanvasNode } from './CanvasNode';
 import { EdgeLayer } from './EdgeLayer';
+import { AnnotationLayer } from './AnnotationLayer';
 import { activeGuides } from './snap-guides';
 import { usePanZoom } from './use-pan-zoom';
 
@@ -70,6 +74,45 @@ function renderNodeContent(node: CanvasNodeState) {
   }
 }
 
+function distanceToSegment(
+  point: { x: number; y: number },
+  start: { x: number; y: number },
+  end: { x: number; y: number },
+): number {
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const lengthSquared = dx * dx + dy * dy;
+  if (lengthSquared === 0) return Math.hypot(point.x - start.x, point.y - start.y);
+  const t = Math.max(0, Math.min(1, ((point.x - start.x) * dx + (point.y - start.y) * dy) / lengthSquared));
+  return Math.hypot(point.x - (start.x + t * dx), point.y - (start.y + t * dy));
+}
+
+function findAnnotationAtPoint(
+  annotationList: CanvasAnnotation[],
+  point: { x: number; y: number },
+  hitRadius: number,
+): CanvasAnnotation | null {
+  for (let i = annotationList.length - 1; i >= 0; i--) {
+    const annotation = annotationList[i];
+    if (!annotation) continue;
+    const pad = hitRadius + annotation.width;
+    if (
+      point.x < annotation.bounds.x - pad ||
+      point.x > annotation.bounds.x + annotation.bounds.width + pad ||
+      point.y < annotation.bounds.y - pad ||
+      point.y > annotation.bounds.y + annotation.bounds.height + pad
+    ) continue;
+    for (let index = 1; index < annotation.points.length; index++) {
+      const start = annotation.points[index - 1];
+      const end = annotation.points[index];
+      if (start && end && distanceToSegment(point, start, end) <= hitRadius + annotation.width / 2) {
+        return annotation;
+      }
+    }
+  }
+  return null;
+}
+
 interface LassoRect {
   startX: number;
   startY: number;
@@ -77,9 +120,27 @@ interface LassoRect {
   currentY: number;
 }
 
+interface AnnotationDraft {
+  id: string;
+  type: 'freehand';
+  points: Array<{ x: number; y: number }>;
+  bounds: { x: number; y: number; width: number; height: number };
+  color: string;
+  width: number;
+  createdAt: string;
+}
+
+const ANNOTATION_COLOR = 'currentColor';
+const ANNOTATION_WIDTH = 4;
+const ERASER_HIT_RADIUS = 14;
+
+type AnnotationTool = 'pen' | 'eraser' | null;
+
 interface CanvasViewportProps {
   onNodeContextMenu?: (e: MouseEvent, nodeId: string) => void;
   onCanvasContextMenu?: (e: MouseEvent, canvasX: number, canvasY: number) => void;
+  annotationMode?: boolean;
+  annotationTool?: AnnotationTool;
 }
 
 const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'bmp', 'ico', 'avif']);
@@ -165,10 +226,13 @@ export function getRenderableWorldNodes(
   return worldNodes;
 }
 
-export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: CanvasViewportProps) {
+export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotationMode = false, annotationTool = null }: CanvasViewportProps) {
   const v = viewport.value;
   const isLassoing = useRef(false);
+  const isAnnotating = useRef(false);
+  const annotationPoints = useRef<Array<{ x: number; y: number }>>([]);
   const [lasso, setLasso] = useState<LassoRect | null>(null);
+  const [draftAnnotation, setDraftAnnotation] = useState<AnnotationDraft | null>(null);
   const [dropActive, setDropActive] = useState(false);
   const dropCounter = useRef(0);
   // Ref mirrors lasso state so pointer handlers always read the latest value
@@ -177,15 +241,16 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
 
   const containerRef = usePanZoom({
     viewport,
+    disabled: annotationMode,
     onViewportChange: (next) => {
       // Don't pan while lassoing — usePanZoom's pointerdown still fires
       // (native listener) before our Preact handler can stopPropagation.
-      if (isLassoing.current) return;
+      if (isLassoing.current || annotationMode) return;
       cancelViewportAnimation();
       setViewport(next);
     },
     onViewportCommit: (next) => {
-      if (isLassoing.current) return;
+      if (isLassoing.current || annotationMode) return;
       cancelViewportAnimation();
       commitViewport(next);
     },
@@ -222,7 +287,53 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
   const handlePointerDown = useCallback(
     (e: PointerEvent) => {
       const container = containerRef.current;
-      if (!container || e.target !== container) return;
+      if (!container) return;
+
+      if (annotationTool === 'eraser') {
+        const target = e.target instanceof Element ? e.target : null;
+        if (target?.closest('.hud-layer, .snapshot-panel, .context-menu, .command-palette')) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const rect = container.getBoundingClientRect();
+        const vp = viewport.value;
+        const point = {
+          x: (e.clientX - rect.left - vp.x) / vp.scale,
+          y: (e.clientY - rect.top - vp.y) / vp.scale,
+        };
+        const hit = findAnnotationAtPoint(Array.from(annotations.value.values()), point, ERASER_HIT_RADIUS / vp.scale);
+        if (hit) void removeAnnotationFromClient(hit.id);
+        return;
+      }
+
+      if (annotationTool === 'pen') {
+        const target = e.target instanceof Element ? e.target : null;
+        if (target?.closest('.hud-layer, .snapshot-panel, .context-menu, .command-palette')) return;
+        e.preventDefault();
+        e.stopPropagation();
+        activeNodeId.value = null;
+        clearSelection();
+        isAnnotating.current = true;
+        const rect = container.getBoundingClientRect();
+        const vp = viewport.value;
+        const point = {
+          x: (e.clientX - rect.left - vp.x) / vp.scale,
+          y: (e.clientY - rect.top - vp.y) / vp.scale,
+        };
+        annotationPoints.current = [point];
+        setDraftAnnotation({
+          id: 'draft-annotation',
+          type: 'freehand',
+          points: [point],
+          bounds: { x: 0, y: 0, width: 0, height: 0 },
+          color: ANNOTATION_COLOR,
+          width: ANNOTATION_WIDTH,
+          createdAt: '',
+        });
+        container.setPointerCapture(e.pointerId);
+        return;
+      }
+
+      if (e.target !== container) return;
 
       if (!e.shiftKey) {
         if (!lassoRef.current) {
@@ -243,11 +354,27 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
       setLasso(initial);
       container.setPointerCapture(e.pointerId);
     },
-    [containerRef],
+    [annotationTool, containerRef],
   );
 
   const handlePointerMove = useCallback(
     (e: PointerEvent) => {
+      if (isAnnotating.current) {
+        const container = containerRef.current;
+        if (!container) return;
+        const rect = container.getBoundingClientRect();
+        const vp = viewport.value;
+        const point = {
+          x: (e.clientX - rect.left - vp.x) / vp.scale,
+          y: (e.clientY - rect.top - vp.y) / vp.scale,
+        };
+        const previous = annotationPoints.current.at(-1);
+        if (previous && Math.hypot(point.x - previous.x, point.y - previous.y) < 2) return;
+        annotationPoints.current = [...annotationPoints.current, point];
+        setDraftAnnotation((draft) => draft ? { ...draft, points: annotationPoints.current } : null);
+        return;
+      }
+
       if (!isLassoing.current || !lassoRef.current) return;
       const rect = containerRef.current?.getBoundingClientRect();
       if (!rect) return;
@@ -262,7 +389,22 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
     [containerRef],
   );
 
-  const handlePointerUp = useCallback(() => {
+  const handlePointerUp = useCallback((e: PointerEvent) => {
+    if (isAnnotating.current) {
+      isAnnotating.current = false;
+      const points = annotationPoints.current;
+      annotationPoints.current = [];
+      setDraftAnnotation(null);
+      if (points.length >= 2) {
+        void createAnnotationFromClient({ points, color: ANNOTATION_COLOR, width: ANNOTATION_WIDTH });
+      }
+      const container = containerRef.current;
+      if (container?.hasPointerCapture(e.pointerId)) {
+        container.releasePointerCapture(e.pointerId);
+      }
+      return;
+    }
+
     const current = lassoRef.current;
     if (!isLassoing.current || !current) return;
     isLassoing.current = false;
@@ -306,6 +448,14 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
     setLasso(null);
   }, []);
 
+  useEffect(() => {
+    if (annotationMode) return;
+    if (!isAnnotating.current && !draftAnnotation) return;
+    isAnnotating.current = false;
+    annotationPoints.current = [];
+    setDraftAnnotation(null);
+  }, [annotationMode, draftAnnotation]);
+
   // ── Drag-to-connect: track cursor in world space, hit-test on drop ──
   useEffect(() => {
     function handleMove(e: PointerEvent) {
@@ -359,6 +509,7 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
   // ── Double-click on background → create new markdown node ──
   const handleDblClick = useCallback(
     (e: MouseEvent) => {
+      if (annotationMode) return;
       const container = containerRef.current;
       if (!container || e.target !== container) return;
       const rect = container.getBoundingClientRect();
@@ -377,11 +528,12 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
         height: nodeH,
       });
     },
-    [containerRef],
+    [annotationMode, containerRef],
   );
 
   const handleContextMenu = useCallback(
     (e: MouseEvent) => {
+      if (annotationMode) return;
       if (!onCanvasContextMenu) return;
 
       const container = containerRef.current;
@@ -396,7 +548,7 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
       const canvasY = (e.clientY - rect.top - v.y) / v.scale;
       onCanvasContextMenu(e, canvasX, canvasY);
     },
-    [containerRef, onCanvasContextMenu],
+    [annotationMode, containerRef, onCanvasContextMenu],
   );
 
   // ── Drag-and-drop files from filesystem ──
@@ -543,7 +695,11 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
         height: '100%',
         position: 'relative',
         overflow: 'hidden',
-        cursor: draggingEdge.value ? 'crosshair' : isLassoing.current ? 'crosshair' : 'grab',
+        cursor: annotationTool === 'eraser'
+          ? 'cell'
+          : annotationMode || draggingEdge.value || isLassoing.current
+            ? 'crosshair'
+            : 'grab',
       }}
     >
       {/* D4: CSS matrix(a,b,c,d,tx,ty) — scale uniformly (a=d=scale, b=c=0)
@@ -561,6 +717,8 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
       >
         <FocusFieldLayer />
         <EdgeLayer nodes={nodes} edges={edges} />
+        <AnnotationLayer annotations={Array.from(annotations.value.values())} />
+        {draftAnnotation && draftAnnotation.points.length >= 2 && <AnnotationLayer annotations={[draftAnnotation]} />}
         {worldNodes.map((node) => (
           <CanvasNode key={node.id} node={node} onContextMenu={onNodeContextMenu}>
             {renderNodeContent(node)}
@@ -579,6 +737,7 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: Canva
           </svg>
         )}
       </div>
+      {annotationMode && <div class={`annotation-capture-layer${annotationTool === 'eraser' ? ' erasing' : ''}`} aria-hidden="true" />}
       {lassoStyle && <div class="lasso-rect" style={lassoStyle} />}
       {dropActive && (
         <div class="drop-zone-overlay">

package/src/client/canvas/ContextPinBar.tsx

@@ -1,12 +1,13 @@
 import {
   clearContextPins,
   contextPinnedNodeIds,
+  hasOpenDockedContextPanel,
 } from '../state/canvas-store';
 import { attentionHistoryOpen } from '../state/attention-store';
 
 export function ContextPinBar() {
   const count = contextPinnedNodeIds.value.size;
-  if (count === 0 || attentionHistoryOpen.value) return null;
+  if (count === 0 || attentionHistoryOpen.value || hasOpenDockedContextPanel.value) return null;
 
   return (
     <div class="context-pin-bar">

package/src/client/canvas/use-pan-zoom.ts

@@ -14,6 +14,7 @@ interface PanZoomOptions {
   viewport: Signal<ViewportState>;
   onViewportChange: (v: ViewportState) => void;
   onViewportCommit: (v: ViewportState) => void;
+  disabled?: boolean;
 }
 
 /**
@@ -23,7 +24,7 @@ interface PanZoomOptions {
  * - Pointer drag on background: pan
  * - Pinch (touch): zoom
  */
-export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: PanZoomOptions) {
+export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disabled = false }: PanZoomOptions) {
   const containerRef = useRef<HTMLDivElement>(null);
   const isPanning = useRef(false);
   const lastPointer = useRef({ x: 0, y: 0 });
@@ -42,6 +43,7 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: Pan
 
   const handleWheel = useCallback(
     (e: WheelEvent) => {
+      if (disabled) return;
       e.preventDefault();
       const v = viewport.value;
 
@@ -74,21 +76,23 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: Pan
         scheduleViewportCommit(next);
       }
     },
-    [viewport, onViewportChange, scheduleViewportCommit],
+    [disabled, viewport, onViewportChange, scheduleViewportCommit],
   );
 
   const handlePointerDown = useCallback((e: PointerEvent) => {
+    if (disabled) return;
     // Only pan when clicking the canvas background (not nodes)
     const container = containerRef.current;
     if (!container || e.target !== container) return;
     isPanning.current = true;
     lastPointer.current = { x: e.clientX, y: e.clientY };
     container.setPointerCapture(e.pointerId);
-  }, []);
+  }, [disabled]);
 
   const handlePointerMove = useCallback(
     (e: PointerEvent) => {
       if (!isPanning.current) return;
+      if (disabled) return;
       const dx = e.clientX - lastPointer.current.x;
       const dy = e.clientY - lastPointer.current.y;
       lastPointer.current = { x: e.clientX, y: e.clientY };
@@ -96,7 +100,7 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: Pan
       const v = viewport.value;
       onViewportChange({ x: v.x + dx, y: v.y + dy, scale: v.scale });
     },
-    [viewport, onViewportChange],
+    [disabled, viewport, onViewportChange],
   );
 
   const handlePointerUp = useCallback(() => {
@@ -109,6 +113,7 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: Pan
   // Touch pinch
   const handleTouchMove = useCallback(
     (e: TouchEvent) => {
+      if (disabled) return;
       if (e.touches.length !== 2) {
         lastPinchDist.current = 0;
         return;
@@ -142,7 +147,7 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit }: Pan
       }
       lastPinchDist.current = dist;
     },
-    [viewport, onViewportChange, scheduleViewportCommit],
+    [disabled, viewport, onViewportChange, scheduleViewportCommit],
   );
 
   const handleTouchEnd = useCallback(() => {

package/src/client/icons.tsx

@@ -117,6 +117,28 @@ export function IconMoon(p: IconProps): JSX.Element {
   );
 }
 
+/** Pen stroke — canvas annotation mode */
+export function IconPen(p: IconProps): JSX.Element {
+  return (
+    <Icon {...p}>
+      <path d="M3 13l2.8-.7L13 5.1 10.9 3 3.7 10.2 3 13Z" />
+      <path d="M9.8 4.1l2.1 2.1" />
+      <path d="M2.5 14h11" />
+    </Icon>
+  );
+}
+
+/** Eraser — remove canvas annotations */
+export function IconEraser(p: IconProps): JSX.Element {
+  return (
+    <Icon {...p}>
+      <path d="M3 10.5 8.5 5a2 2 0 0 1 2.8 0l1.7 1.7a2 2 0 0 1 0 2.8L8.5 14H5.8L3 11.2Z" />
+      <path d="M7.5 6 12 10.5" />
+      <path d="M8.5 14H14" />
+    </Icon>
+  );
+}
+
 /** Camera — snapshots */
 export function IconSnapshot(p: IconProps): JSX.Element {
   return (

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[];
 }