pmx-canvas 0.1.16 → 0.1.17

package/dist/types/client/canvas/AnnotationLayer.d.ts

@@ -0,0 +1,4 @@
+import type { CanvasAnnotation } from '../types';
+export declare function AnnotationLayer({ annotations }: {
+    annotations: CanvasAnnotation[];
+}): import("preact/src").JSX.Element | null;

package/dist/types/client/canvas/CanvasViewport.d.ts

@@ -1,8 +1,11 @@
 import type { CanvasNodeState } from '../types';
+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;
 }
 export declare function getRenderableWorldNodes(allNodes: Iterable<CanvasNodeState>, focusedNodeId: string | null): CanvasNodeState[];
-export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: CanvasViewportProps): import("preact/src").JSX.Element;
+export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotationMode, annotationTool }: CanvasViewportProps): import("preact/src").JSX.Element;
 export {};

package/dist/types/client/canvas/use-pan-zoom.d.ts

@@ -4,6 +4,7 @@ interface PanZoomOptions {
     viewport: Signal<ViewportState>;
     onViewportChange: (v: ViewportState) => void;
     onViewportCommit: (v: ViewportState) => void;
+    disabled?: boolean;
 }
 /**
  * Hook that wires up pan/zoom interactions on a container element.
@@ -12,5 +13,5 @@ interface PanZoomOptions {
  * - Pointer drag on background: pan
  * - Pinch (touch): zoom
  */
-export declare function usePanZoom({ viewport, onViewportChange, onViewportCommit }: PanZoomOptions): import("preact/src").RefObject<HTMLDivElement>;
+export declare function usePanZoom({ viewport, onViewportChange, onViewportCommit, disabled }: PanZoomOptions): import("preact/src").RefObject<HTMLDivElement>;
 export {};

package/dist/types/client/icons.d.ts

@@ -19,6 +19,10 @@ export declare function IconMinimap(p: IconProps): JSX.Element;
 export declare function IconSun(p: IconProps): JSX.Element;
 /** Crescent moon */
 export declare function IconMoon(p: IconProps): JSX.Element;
+/** Pen stroke — canvas annotation mode */
+export declare function IconPen(p: IconProps): JSX.Element;
+/** Eraser — remove canvas annotations */
+export declare function IconEraser(p: IconProps): JSX.Element;
 /** Camera — snapshots */
 export declare function IconSnapshot(p: IconProps): JSX.Element;
 /** Bullseye — trace toggle */

package/dist/types/client/state/canvas-store.d.ts

@@ -1,7 +1,8 @@
-import { type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
+import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
 export declare const viewport: import("@preact/signals-core").Signal<ViewportState>;
 export declare const nodes: import("@preact/signals-core").Signal<Map<string, CanvasNodeState>>;
 export declare const edges: import("@preact/signals-core").Signal<Map<string, CanvasEdge>>;
+export declare const annotations: import("@preact/signals-core").Signal<Map<string, CanvasAnnotation>>;
 export declare const activeNodeId: import("@preact/signals-core").Signal<string | null>;
 export declare const connectionStatus: import("@preact/signals-core").Signal<ConnectionStatus>;
 export declare const sessionId: import("@preact/signals-core").Signal<string>;
@@ -41,6 +42,19 @@ export declare function removeNode(id: string): void;
 export declare function addEdge(edge: CanvasEdge): void;
 export declare function removeEdge(id: string): void;
 export declare function removeEdgesForNode(nodeId: string): void;
+export declare function addAnnotation(annotation: CanvasAnnotation): void;
+export declare function removeAnnotation(id: string): void;
+export declare function createAnnotationFromClient(input: {
+    points: CanvasAnnotation['points'];
+    color: string;
+    width: number;
+    label?: string;
+}): Promise<{
+    ok: boolean;
+}>;
+export declare function removeAnnotationFromClient(id: string): Promise<{
+    ok: boolean;
+}>;
 export declare function resizeNode(id: string, size: {
     width: number;
     height: number;
@@ -56,6 +70,7 @@ export declare function replaceViewport(next: ViewportState): void;
 export declare function commitViewport(next: ViewportState): void;
 export declare function applyServerCanvasLayout(layout: Pick<CanvasLayout, 'nodes' | 'edges'> & {
     viewport?: ViewportState;
+    annotations?: CanvasAnnotation[];
 }, options?: {
     applyViewport?: boolean;
 }): void;

package/dist/types/client/types.d.ts

@@ -29,6 +29,25 @@ export interface CanvasEdge {
     style?: 'solid' | 'dashed' | 'dotted';
     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';
 export declare const TYPE_LABELS: Record<CanvasNodeState['type'], string>;
 /** Node types that support the full-viewport expand/focus overlay. */
@@ -40,4 +59,5 @@ export interface CanvasLayout {
     viewport: ViewportState;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
 }

package/dist/types/mcp/canvas-access.d.ts

@@ -54,6 +54,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>;

package/dist/types/server/canvas-serialization.d.ts

@@ -1,4 +1,4 @@
-import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import { type CanvasNodeProvenance } from './canvas-provenance.js';
 export interface SerializedCanvasNode extends CanvasNodeState {
     kind: string;
@@ -11,6 +11,24 @@ export interface SerializedCanvasNode extends CanvasNodeState {
 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;
+}
 export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string;
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
@@ -18,9 +36,13 @@ export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCa
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasAnnotationSummary;
+export declare function summarizeCanvasAnnotationForContext(annotation: CanvasAnnotation, nodes: CanvasNodeState[]): CanvasAnnotationContextSummary;
 export interface CanvasSummary {
     totalNodes: number;
     totalEdges: number;
+    totalAnnotations: number;
+    annotations: CanvasAnnotationContextSummary[];
     nodesByType: Record<string, number>;
     pinnedCount: number;
     pinnedTitles: string[];

package/dist/types/server/canvas-state.d.ts

@@ -22,6 +22,7 @@ interface PersistedCanvasState {
     viewport: ViewportState;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
     contextPins: string[];
 }
 interface LoadFromDiskOptions {
@@ -81,10 +82,30 @@ export interface CanvasEdge {
     style?: 'solid' | 'dashed' | 'dotted';
     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 {
     id: string;
@@ -101,7 +122,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;
@@ -114,6 +135,7 @@ interface GroupNodesOptions {
 declare class CanvasStateManager {
     private nodes;
     private edges;
+    private annotations;
     private _viewport;
     private _contextPinnedNodeIds;
     private _workspaceRoot;
@@ -185,6 +207,7 @@ declare class CanvasStateManager {
         name: string;
         nodes: CanvasNodeState[];
         edges: CanvasEdge[];
+        annotations: CanvasAnnotation[];
     } | null;
     /** Delete a snapshot. */
     deleteSnapshot(id: string): boolean;
@@ -200,6 +223,9 @@ declare class CanvasStateManager {
     removeEdge(id: string): boolean;
     getEdges(): CanvasEdge[];
     getEdgesForNode(nodeId: string): CanvasEdge[];
+    addAnnotation(annotation: CanvasAnnotation): void;
+    removeAnnotation(id: string): boolean;
+    getAnnotations(): CanvasAnnotation[];
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;

package/dist/types/server/index.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
@@ -69,6 +69,11 @@ export declare class PmxCanvas extends EventEmitter {
         style?: CanvasEdge['style'];
         animated?: boolean;
     }): string;
+    addAnnotation(input: Omit<CanvasAnnotation, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): string;
+    removeAnnotation(id: string): boolean;
     removeEdge(id: string): void;
     /**
      * Create a group node and optionally add child nodes to it.
@@ -263,7 +268,7 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, 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/dist/types/server/mutation-history.d.ts

@@ -12,7 +12,7 @@
  * - _replaying flag prevents undo/redo from recording new entries
  */
 import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
-export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
+export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
 export interface MutationEntry {
     id: string;
     timestamp: string;

package/dist/types/server/spatial-analysis.d.ts

@@ -9,7 +9,7 @@
  * actually real for agents. Instead of raw x/y coordinates, agents get
  * 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';
 export interface SpatialCluster {
     /** Auto-generated cluster ID */
     id: string;
@@ -45,6 +45,14 @@ export interface NodeSpatialInfo {
     /** Reading order index (top-left to bottom-right) */
     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 +66,7 @@ export interface SpatialContext {
         pinnedNodeTitle: string | null;
         neighbors: SpatialNeighbor[];
     }[];
+    annotations: SpatialAnnotationContext[];
 }
 /**
  * Detect proximity clusters using single-linkage clustering.
@@ -84,4 +93,4 @@ export declare function searchNodes(nodes: CanvasNodeState[], query: string): {
 /**
  * Build the complete spatial context for the canvas.
  */
-export declare function buildSpatialContext(nodes: CanvasNodeState[], _edges: CanvasEdge[], pinnedIds: Set<string>): SpatialContext;
+export declare function buildSpatialContext(nodes: CanvasNodeState[], _edges: CanvasEdge[], pinnedIds: Set<string>, annotations?: CanvasAnnotation[]): SpatialContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -302,6 +302,10 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - `id` (required): node to remove
 - Clean up nodes that are no longer relevant
 
+**`canvas_remove_annotation`** — Remove a human-drawn annotation
+- `id` (required): annotation to remove
+- Use when context gives you the annotation ID; use WebView first if you need to identify a mark by shape or location.
+
 **`canvas_get_node`** — Get a single node's full data
 - `id` (required): node to retrieve
 
@@ -564,6 +568,11 @@ tools below operate on the live canvas state.
 Useful workbench selectors:
 - Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
 - Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
+- Annotations: `.annotation-layer path` renders human-drawn freehand ink. Use WebView
+  to inspect or screenshot annotation shapes; MCP/context resources only expose compact
+  annotation target summaries, not the raw visual shape. Humans can remove marks with
+  the eraser toolbar button; agents can remove a known annotation ID with
+  `canvas_remove_annotation`.
 - Canvas chrome: `.hud-layer`, `.canvas-toolbar`, `.connection-dot`, `.canvas-bootstrap-card`
 - Nodes do not expose stable `data-node-id` attributes. Use `canvas_get_layout`, `canvas_search`, or MCP resource data for exact node IDs.
 
@@ -610,6 +619,9 @@ canvas_webview_stop();
   geometric `graph` node would feel too rigid
 - Prefer labeled shapes (`"label": { "text": "..." }` on rectangle/ellipse/diamond) over
   separate text elements — fewer tokens and auto-centered
+- Do not use separate `text` elements with `containerId`/`boundElements` to place centered text
+  inside shapes. The hosted SVG preview does not auto-position those; PMX normalizes imported
+  canonical bound text back into shape labels for hosted app calls.
 - Prefer the pastel fill palette in the Excalidraw `read_me` (light blue/green/orange/...) for
   a consistent look across diagrams
 
@@ -691,6 +703,11 @@ The `canvas://spatial-context` resource reveals how the human has organized info
   This implies sequence or priority.
 - **Pinned neighborhoods** — For each pinned node, nearby unpinned nodes are listed. These
   are the human's implicit context — things they consider related to what they pinned.
+- **Annotations** — Human-drawn markup is summarized by target/bounds only, e.g. an
+  annotation over a node or empty canvas region. Use WebView (`canvas_webview_start` +
+  `canvas_evaluate`/`canvas_screenshot`) when you need to see whether the mark is an
+  arrow, line, circle, or other drawn shape. Remove known annotations with
+  `canvas_remove_annotation`; otherwise use WebView to identify the mark first.
 - **Board density matters** — On a dense board, spatial context can still read like one large
   gallery unless groups and spacing separate the major regions clearly.
 

package/src/cli/agent.ts

@@ -1027,6 +1027,7 @@ cmd('node add', 'Add a node to the canvas', [
   'pmx-canvas node add --type status --title "Build" --content "passing"',
   'pmx-canvas node add --type file --content "src/index.ts"',
   'pmx-canvas node add --type webpage --url "https://example.com/docs"',
+  'pmx-canvas node add --type html --title "Widget" --content "<main>Hello</main>"',
   'pmx-canvas node add --type markdown --title "Note" --x 100 --y 200',
   'pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json',
   'pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
@@ -1069,6 +1070,9 @@ cmd('node add', 'Add a node to the canvas', [
     body.url = webpageUrl;
   } else if (type === 'image' && imagePath && !flags.content) {
     body.content = imagePath;
+  } else if (type === 'html') {
+    const html = getStringFlag(flags, 'html') ?? getStringFlag(flags, 'content');
+    if (html !== undefined) body.html = html;
   } else if (flags.content) {
     body.content = flags.content;
   }
@@ -1090,6 +1094,8 @@ cmd('node add', 'Add a node to the canvas', [
   if (flags.stdin) {
     if (type === 'webpage') {
       body.url = await readStdin();
+    } else if (type === 'html') {
+      body.html = await readStdin();
     } else {
       body.content = await readStdin();
     }

package/src/client/App.tsx

@@ -41,10 +41,12 @@ import { connectSSE } from './state/sse-bridge';
 import {
   IconArrange,
   IconClearTrace,
+  IconEraser,
   IconFitAll,
   IconLogo,
   IconMinimap,
   IconMoon,
+  IconPen,
   IconResetView,
   IconSearch,
   IconShortcuts,
@@ -71,6 +73,8 @@ function sendIntent(type: string, payload: Record<string, unknown> = {}): void {
   });
 }
 
+type AnnotationTool = 'pen' | 'eraser' | null;
+
 function ToolbarHint({
   label,
   detail,
@@ -108,6 +112,9 @@ function Toolbar({
   snapshotBtnRef,
   onOpenPalette,
   onOpenShortcuts,
+  annotationTool,
+  onToggleAnnotationMode,
+  onToggleAnnotationEraser,
 }: {
   minimapVisible: boolean;
   onToggleMinimap: () => void;
@@ -116,6 +123,9 @@ function Toolbar({
   snapshotBtnRef: { current: HTMLButtonElement | null };
   onOpenPalette: () => void;
   onOpenShortcuts: () => void;
+  annotationTool: AnnotationTool;
+  onToggleAnnotationMode: () => void;
+  onToggleAnnotationEraser: () => void;
 }) {
   const status = connectionStatus.value;
   const hasSynced = hasInitialServerLayout.value;
@@ -278,6 +288,37 @@ function Toolbar({
 
         <div class="separator" />
 
+        <ToolbarHint
+          label={annotationTool === 'pen' ? 'Stop annotating' : 'Annotate canvas'}
+          detail="Draw directly on the canvas for human-visible markup"
+        >
+          <button
+            type="button"
+            onClick={onToggleAnnotationMode}
+            aria-label={annotationTool === 'pen' ? 'Stop annotating' : 'Annotate canvas'}
+            aria-pressed={annotationTool === 'pen'}
+            style={{ color: annotationTool === 'pen' ? 'var(--c-accent)' : undefined }}
+          >
+            <IconPen />
+          </button>
+        </ToolbarHint>
+        <ToolbarHint
+          label={annotationTool === 'eraser' ? 'Stop erasing' : 'Erase annotations'}
+          detail="Click a drawn annotation to remove it"
+        >
+          <button
+            type="button"
+            onClick={onToggleAnnotationEraser}
+            aria-label={annotationTool === 'eraser' ? 'Stop erasing' : 'Erase annotations'}
+            aria-pressed={annotationTool === 'eraser'}
+            style={{ color: annotationTool === 'eraser' ? 'var(--c-accent)' : undefined }}
+          >
+            <IconEraser />
+          </button>
+        </ToolbarHint>
+
+        <div class="separator" />
+
         <ToolbarHint label="Search nodes and actions" shortcut={`${MOD_KEY}+K`}>
           <button
             type="button"
@@ -341,6 +382,7 @@ export function App() {
   const [snapshotOpen, setSnapshotOpen] = useState(false);
   const [paletteOpen, setPaletteOpen] = useState(false);
   const [shortcutsOpen, setShortcutsOpen] = useState(false);
+  const [annotationTool, setAnnotationTool] = useState<AnnotationTool>(null);
   const snapshotBtnRef = useRef<HTMLButtonElement>(null);
   const { menu, openNodeMenu, openCanvasMenu, closeMenu } = useContextMenu();
   const hasInitialLayout = hasInitialServerLayout.value;
@@ -348,14 +390,18 @@ export function App() {
   const handleToggleMinimap = useCallback(() => setMinimapVisible((v) => !v), []);
   const handleToggleSnapshot = useCallback(() => setSnapshotOpen((v) => !v), []);
   const handleCloseSnapshot = useCallback(() => setSnapshotOpen(false), []);
+  const handleToggleAnnotationMode = useCallback(() => setAnnotationTool((tool) => tool === 'pen' ? null : 'pen'), []);
+  const handleToggleAnnotationEraser = useCallback(() => setAnnotationTool((tool) => tool === 'eraser' ? null : 'eraser'), []);
 
   const handleMinimapNavigate = useCallback((x: number, y: number) => {
     animateViewport({ x, y, scale: viewport.value.scale }, 200);
   }, []);
 
   useEffect(() => {
-    const disconnect = connectSSE();
+    return connectSSE();
+  }, []);
 
+  useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       const mod = e.metaKey || e.ctrlKey;
 
@@ -366,6 +412,13 @@ export function App() {
         return;
       }
 
+      // Esc exits annotation tools before handling overlays or selection.
+      if (e.key === 'Escape' && annotationTool) {
+        e.preventDefault();
+        setAnnotationTool(null);
+        return;
+      }
+
       // Esc always collapses expanded node first (even from inside inputs)
       if (e.key === 'Escape' && expandedNodeId.value && !pendingExpandedNodeCloseId.value) {
         e.preventDefault();
@@ -428,10 +481,9 @@ export function App() {
 
     document.addEventListener('keydown', handleKeyDown);
     return () => {
-      disconnect();
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [closeMenu, paletteOpen, shortcutsOpen]);
+  }, [annotationTool, closeMenu, paletteOpen, shortcutsOpen]);
 
   useEffect(() => {
     if (!hasInitialLayout) return;
@@ -465,6 +517,9 @@ export function App() {
           snapshotBtnRef={snapshotBtnRef}
           onOpenPalette={() => setPaletteOpen(true)}
           onOpenShortcuts={() => setShortcutsOpen((v) => !v)}
+          annotationTool={annotationTool}
+          onToggleAnnotationMode={handleToggleAnnotationMode}
+          onToggleAnnotationEraser={handleToggleAnnotationEraser}
         />
         <div class="hud-right">
           {dockedRight.map((n) => (
@@ -477,6 +532,8 @@ export function App() {
       <CanvasViewport
         onNodeContextMenu={openNodeMenu}
         onCanvasContextMenu={openCanvasMenu}
+        annotationMode={annotationTool !== null}
+        annotationTool={annotationTool}
       />
       {hasInitialLayout && allNodes.filter((n) => !n.dockPosition).length === 0 && (
         <WelcomeCard onOpenPalette={() => setPaletteOpen(true)} />

package/src/client/canvas/AnnotationLayer.tsx

@@ -0,0 +1,28 @@
+import type { CanvasAnnotation, CanvasAnnotationPoint } from '../types';
+
+function pointsToPath(points: CanvasAnnotationPoint[]): string {
+  const [first, ...rest] = points;
+  if (!first) return '';
+  return rest.reduce((path, point) => `${path} L ${point.x} ${point.y}`, `M ${first.x} ${first.y}`);
+}
+
+export function AnnotationLayer({ annotations }: { annotations: CanvasAnnotation[] }) {
+  if (annotations.length === 0) return null;
+
+  return (
+    <svg class="annotation-layer" aria-hidden="true">
+      {annotations.map((annotation) => (
+        <path
+          key={annotation.id}
+          d={pointsToPath(annotation.points)}
+          fill="none"
+          stroke={annotation.color === 'currentColor' ? 'var(--c-annotation)' : annotation.color}
+          stroke-width={annotation.width}
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          opacity="0.9"
+        />
+      ))}
+    </svg>
+  );
+}