pmx-canvas 0.1.0

package/src/server/code-graph.ts

@@ -0,0 +1,370 @@
+/**
+ * Code Graph — Auto-dependency detection between file nodes.
+ *
+ * Parses imports from file node content and auto-creates `depends-on` edges
+ * between file nodes that reference each other. Updates live when files change.
+ *
+ * Supported import patterns:
+ * - JS/TS: import ... from '...', import('...'), require('...')
+ * - Python: import ..., from ... import ...
+ * - Go: import "...", import ( "..." )
+ * - Rust: mod ..., use crate::...
+ *
+ * Auto-edges are tagged with `_autoCodeGraph: true` in their metadata so they
+ * can be distinguished from manually created edges and cleaned up properly.
+ */
+
+import { resolve, dirname, basename, extname, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { canvasState } from './canvas-state.js';
+import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface CodeGraphEdge {
+  fromNodeId: string;
+  toNodeId: string;
+  fromPath: string;
+  toPath: string;
+  importSpecifier: string;
+}
+
+export interface CodeGraphSummary {
+  totalFileNodes: number;
+  totalAutoEdges: number;
+  nodes: {
+    id: string;
+    path: string;
+    title: string | null;
+    imports: string[];
+    importedBy: string[];
+    /** Number of files this node depends on */
+    outDegree: number;
+    /** Number of files that depend on this node */
+    inDegree: number;
+  }[];
+  /** Most-depended-on files (highest inDegree) */
+  centralFiles: { path: string; title: string | null; inDegree: number }[];
+  /** Files with no dependencies in or out (isolated) */
+  isolatedFiles: { path: string; title: string | null }[];
+}
+
+// ── Import Parser ────────────────────────────────────────────────────
+
+// JS/TS patterns
+const JS_IMPORT_FROM = /(?:import|export)\s+(?:[\s\S]*?)\s+from\s+['"]([^'"]+)['"]/g;
+const JS_IMPORT_BARE = /import\s+['"]([^'"]+)['"]/g;
+const JS_DYNAMIC_IMPORT = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
+const JS_REQUIRE = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+// Python patterns
+const PY_IMPORT = /^import\s+([\w.]+)/gm;
+const PY_FROM_IMPORT = /^from\s+([\w.]+)\s+import/gm;
+
+// Go patterns
+const GO_IMPORT_SINGLE = /import\s+"([^"]+)"/g;
+const GO_IMPORT_BLOCK = /import\s*\(\s*([\s\S]*?)\)/g;
+const GO_IMPORT_LINE = /"([^"]+)"/g;
+
+// Rust patterns
+const RUST_MOD = /^mod\s+(\w+)\s*;/gm;
+const RUST_USE_CRATE = /^use\s+crate::(\S+)/gm;
+
+/**
+ * Extract import specifiers from file content based on file extension.
+ */
+export function parseImports(content: string, filePath: string): string[] {
+  const ext = extname(filePath).toLowerCase();
+  const specifiers: string[] = [];
+
+  if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts', '.cjs', '.cts'].includes(ext)) {
+    for (const match of content.matchAll(JS_IMPORT_FROM)) specifiers.push(match[1]);
+    for (const match of content.matchAll(JS_IMPORT_BARE)) specifiers.push(match[1]);
+    for (const match of content.matchAll(JS_DYNAMIC_IMPORT)) specifiers.push(match[1]);
+    for (const match of content.matchAll(JS_REQUIRE)) specifiers.push(match[1]);
+  } else if (['.py', '.pyw'].includes(ext)) {
+    for (const match of content.matchAll(PY_IMPORT)) specifiers.push(match[1]);
+    for (const match of content.matchAll(PY_FROM_IMPORT)) specifiers.push(match[1]);
+  } else if (ext === '.go') {
+    for (const match of content.matchAll(GO_IMPORT_SINGLE)) specifiers.push(match[1]);
+    for (const match of content.matchAll(GO_IMPORT_BLOCK)) {
+      const block = match[1];
+      for (const line of block.matchAll(GO_IMPORT_LINE)) specifiers.push(line[1]);
+    }
+  } else if (ext === '.rs') {
+    for (const match of content.matchAll(RUST_MOD)) specifiers.push(match[1]);
+    for (const match of content.matchAll(RUST_USE_CRATE)) specifiers.push(match[1]);
+  }
+
+  // Deduplicate
+  return [...new Set(specifiers)];
+}
+
+// ── Path Resolution ──────────────────────────────────────────────────
+
+/**
+ * Resolve an import specifier to a file path, checking common extensions.
+ * Returns null if the import can't be resolved to a file on disk.
+ */
+function resolveImportPath(specifier: string, fromFilePath: string): string | null {
+  // Skip bare module specifiers (npm packages, node builtins)
+  if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
+    // Could be a project-relative path or a package — skip packages
+    // Check if it looks like a relative project path (contains / and no @)
+    if (!specifier.includes('/') || specifier.startsWith('@')) return null;
+    // For non-relative paths, try workspace-relative resolution
+    const wsRoot = process.cwd();
+    return tryResolveWithExtensions(resolve(wsRoot, specifier));
+  }
+
+  const dir = dirname(fromFilePath);
+  const candidate = resolve(dir, specifier);
+  return tryResolveWithExtensions(candidate);
+}
+
+const RESOLVE_EXTENSIONS = [
+  '', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts',
+  '/index.ts', '/index.tsx', '/index.js', '/index.jsx',
+  '.py', '.go', '.rs',
+];
+
+function tryResolveWithExtensions(basePath: string): string | null {
+  // Try exact path + extensions
+  for (const ext of RESOLVE_EXTENSIONS) {
+    const full = basePath + ext;
+    if (existsSync(full)) return full;
+  }
+
+  // Handle TS/JS extension mapping: import './foo.js' → actual file is './foo.ts'
+  const ext = extname(basePath);
+  if (['.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+    const withoutExt = basePath.slice(0, -ext.length);
+    const tsExtMap: Record<string, string[]> = {
+      '.js': ['.ts', '.tsx'],
+      '.jsx': ['.tsx'],
+      '.mjs': ['.mts'],
+      '.cjs': ['.cts'],
+    };
+    for (const tsExt of tsExtMap[ext] ?? []) {
+      const candidate = withoutExt + tsExt;
+      if (existsSync(candidate)) return candidate;
+    }
+    // Also try index files: import './foo.js' → './foo/index.ts'
+    for (const idxExt of ['/index.ts', '/index.tsx', '/index.js']) {
+      const candidate = withoutExt + idxExt;
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+// ── Auto-Edge Manager ────────────────────────────────────────────────
+
+/** Prefix for auto-generated code graph edge IDs */
+const AUTO_EDGE_PREFIX = 'codegraph-';
+
+/** Cache of last recomputed edges for buildCodeGraphSummary() to reuse. */
+let _lastDiscoveredEdges: CodeGraphEdge[] = [];
+
+/**
+ * Get all file nodes currently on the canvas.
+ */
+function getFileNodes(): CanvasNodeState[] {
+  return canvasState.getLayout().nodes.filter((n) => n.type === 'file' && typeof n.data.path === 'string');
+}
+
+/**
+ * Build a map of absolute file path → node ID for the given file nodes.
+ */
+function buildPathIndex(fileNodes?: CanvasNodeState[]): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const node of (fileNodes ?? getFileNodes())) {
+    index.set(node.data.path as string, node.id);
+  }
+  return index;
+}
+
+/**
+ * Recompute all auto-edges for the code graph.
+ * Called when file nodes are added/removed or file content changes.
+ *
+ * Returns the list of edges that were created/maintained.
+ */
+export function recomputeCodeGraph(): CodeGraphEdge[] {
+  const fileNodes = getFileNodes();
+  const pathIndex = buildPathIndex(fileNodes);
+  const discoveredEdges: CodeGraphEdge[] = [];
+
+  // Parse imports for each file node and resolve to other file nodes
+  for (const node of fileNodes) {
+    const filePath = node.data.path as string;
+    const content = (node.data.fileContent as string) ?? '';
+    if (!content) continue;
+
+    const specifiers = parseImports(content, filePath);
+
+    for (const spec of specifiers) {
+      const resolvedPath = resolveImportPath(spec, filePath);
+      if (!resolvedPath) continue;
+
+      const targetNodeId = pathIndex.get(resolvedPath);
+      if (!targetNodeId || targetNodeId === node.id) continue;
+
+      discoveredEdges.push({
+        fromNodeId: node.id,
+        toNodeId: targetNodeId,
+        fromPath: filePath,
+        toPath: resolvedPath,
+        importSpecifier: spec,
+      });
+    }
+  }
+
+  // Remove old auto-edges that no longer exist
+  const existingAutoEdges = canvasState.getEdges().filter((e) => e.id.startsWith(AUTO_EDGE_PREFIX));
+  const discoveredKeys = new Set(discoveredEdges.map((e) => `${e.fromNodeId}->${e.toNodeId}`));
+
+  // Suppress mutation recording for auto-edge management (these are computed, not user actions)
+  canvasState.withSuppressedRecording(() => {
+    for (const edge of existingAutoEdges) {
+      const key = `${edge.from}->${edge.to}`;
+      if (!discoveredKeys.has(key)) {
+        canvasState.removeEdge(edge.id);
+      }
+    }
+
+    // Add new auto-edges that don't exist yet
+    const existingKeys = new Set(existingAutoEdges.map((e) => `${e.from}->${e.to}`));
+    for (const edge of discoveredEdges) {
+      const key = `${edge.fromNodeId}->${edge.toNodeId}`;
+      if (existingKeys.has(key)) continue;
+
+      const edgeId = `${AUTO_EDGE_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+      canvasState.addEdge({
+        id: edgeId,
+        from: edge.fromNodeId,
+        to: edge.toNodeId,
+        type: 'depends-on',
+        label: 'imports',
+        style: 'dashed',
+      });
+    }
+  });
+
+  _lastDiscoveredEdges = discoveredEdges;
+  return discoveredEdges;
+}
+
+/**
+ * Build a summary of the code graph for the MCP resource.
+ */
+export function buildCodeGraphSummary(): CodeGraphSummary {
+  const fileNodes = getFileNodes();
+  const autoEdges = canvasState.getEdges().filter((e) => e.id.startsWith(AUTO_EDGE_PREFIX));
+
+  // Build adjacency data
+  const outgoing = new Map<string, Set<string>>(); // nodeId → set of target nodeIds
+  const incoming = new Map<string, Set<string>>(); // nodeId → set of source nodeIds
+  const importSpecs = new Map<string, string[]>(); // nodeId → import specifiers
+
+  for (const node of fileNodes) {
+    outgoing.set(node.id, new Set());
+    incoming.set(node.id, new Set());
+    importSpecs.set(node.id, []);
+  }
+
+  for (const edge of autoEdges) {
+    outgoing.get(edge.from)?.add(edge.to);
+    incoming.get(edge.to)?.add(edge.from);
+  }
+
+  // Use cached discovered edges from last recomputeCodeGraph() to avoid re-parsing
+  const idToPath = new Map<string, string>();
+  for (const node of fileNodes) idToPath.set(node.id, node.data.path as string);
+
+  // Group import specifiers by source node from cached edges
+  for (const edge of _lastDiscoveredEdges) {
+    const specs = importSpecs.get(edge.fromNodeId);
+    if (specs && !specs.includes(edge.importSpecifier)) {
+      specs.push(edge.importSpecifier);
+    }
+  }
+
+  const nodes = fileNodes.map((node) => {
+    const out = outgoing.get(node.id) ?? new Set();
+    const inc = incoming.get(node.id) ?? new Set();
+    return {
+      id: node.id,
+      path: relative(process.cwd(), node.data.path as string) || (node.data.path as string),
+      title: (node.data.title as string) ?? null,
+      imports: importSpecs.get(node.id) ?? [],
+      importedBy: [...(inc)].map((id) => {
+        const path = idToPath.get(id);
+        return path ? relative(process.cwd(), path) : id;
+      }),
+      outDegree: out.size,
+      inDegree: inc.size,
+    };
+  });
+
+  // Sort by inDegree descending for central files
+  const centralFiles = nodes
+    .filter((n) => n.inDegree > 0)
+    .sort((a, b) => b.inDegree - a.inDegree)
+    .slice(0, 10)
+    .map((n) => ({ path: n.path, title: n.title, inDegree: n.inDegree }));
+
+  const isolatedFiles = nodes
+    .filter((n) => n.inDegree === 0 && n.outDegree === 0)
+    .map((n) => ({ path: n.path, title: n.title }));
+
+  return {
+    totalFileNodes: fileNodes.length,
+    totalAutoEdges: autoEdges.length,
+    nodes,
+    centralFiles,
+    isolatedFiles,
+  };
+}
+
+/**
+ * Format code graph summary as human-readable text for MCP.
+ */
+export function formatCodeGraph(summary: CodeGraphSummary): string {
+  if (summary.totalFileNodes === 0) {
+    return 'Code Graph: no file nodes on canvas. Add file nodes to see auto-detected dependencies.';
+  }
+
+  const lines: string[] = [
+    `Code Graph: ${summary.totalFileNodes} files, ${summary.totalAutoEdges} dependency edges`,
+    '',
+  ];
+
+  if (summary.centralFiles.length > 0) {
+    lines.push('Central files (most depended on):');
+    for (const f of summary.centralFiles) {
+      lines.push(`  ${f.title ?? f.path} — imported by ${f.inDegree} file(s)`);
+    }
+    lines.push('');
+  }
+
+  if (summary.isolatedFiles.length > 0) {
+    lines.push(`Isolated files (${summary.isolatedFiles.length}): ${summary.isolatedFiles.map((f) => f.title ?? f.path).join(', ')}`);
+    lines.push('');
+  }
+
+  lines.push('Dependencies:');
+  for (const node of summary.nodes) {
+    if (node.outDegree === 0 && node.inDegree === 0) continue;
+    lines.push(`  ${node.title ?? node.path}`);
+    if (node.imports.length > 0) {
+      lines.push(`    imports: ${node.imports.join(', ')}`);
+    }
+    if (node.importedBy.length > 0) {
+      lines.push(`    imported by: ${node.importedBy.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/server/context-cards.ts

@@ -0,0 +1,31 @@
+/**
+ * Context cards — standalone version.
+ *
+ * In the full PMX project this reads project memory and context doc definitions.
+ * In the standalone canvas, we expose the types and a simplified builder that
+ * returns an empty card list (the host application can populate cards via the API).
+ */
+
+export type WorkbenchContextCardCategory = 'profile' | 'planning' | 'tooling' | 'memory';
+
+export interface WorkbenchContextCard {
+  key: string;
+  label: string;
+  summary: string;
+  path: string;
+  exists: boolean;
+  required: boolean;
+  staleDays: number;
+  mtimeMs: number | null;
+  state: 'loaded' | 'missing' | 'stale' | 'invalid';
+  sourceKind: 'workspace' | 'global';
+  note: string | null;
+  injectMode: 'startup';
+  category: WorkbenchContextCardCategory;
+}
+
+export function buildWorkbenchContextCards(_workspaceRoot = process.cwd()): WorkbenchContextCard[] {
+  // Standalone canvas does not have access to PMX context doc definitions.
+  // Return empty — the host application populates cards via the event API.
+  return [];
+}

package/src/server/diagram-presets.ts

@@ -0,0 +1,71 @@
+import type { ExternalMcpTransportConfig } from './mcp-app-runtime.js';
+
+export const EXCALIDRAW_MCP_URL = 'https://mcp.excalidraw.com/mcp';
+export const EXCALIDRAW_SERVER_NAME = 'Excalidraw';
+export const EXCALIDRAW_CREATE_VIEW_TOOL = 'create_view';
+
+export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
+  type: 'http',
+  url: EXCALIDRAW_MCP_URL,
+};
+
+export interface DiagramPresetOpenInput {
+  elements: unknown;
+  title?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface ExcalidrawOpenMcpAppInput {
+  transport: ExternalMcpTransportConfig;
+  toolName: string;
+  serverName: string;
+  toolArguments: { elements: string };
+  title?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}
+
+export function normalizeExcalidrawElements(elements: unknown): string {
+  if (typeof elements === 'string') {
+    const trimmed = elements.trim();
+    if (!trimmed) {
+      throw new Error('diagram.elements must be a non-empty JSON array string or an array of Excalidraw elements.');
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(`diagram.elements string is not valid JSON: ${reason}`);
+    }
+    if (!Array.isArray(parsed)) {
+      throw new Error('diagram.elements string must encode a JSON array.');
+    }
+    return JSON.stringify(parsed);
+  }
+  if (Array.isArray(elements)) {
+    return JSON.stringify(elements);
+  }
+  throw new Error('diagram.elements must be a JSON array string or an array of Excalidraw elements.');
+}
+
+export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput {
+  const elements = normalizeExcalidrawElements(input.elements);
+  const out: ExcalidrawOpenMcpAppInput = {
+    transport: EXCALIDRAW_MCP_TRANSPORT,
+    toolName: EXCALIDRAW_CREATE_VIEW_TOOL,
+    serverName: EXCALIDRAW_SERVER_NAME,
+    toolArguments: { elements },
+  };
+  if (typeof input.title === 'string' && input.title.trim().length > 0) out.title = input.title.trim();
+  if (typeof input.x === 'number' && Number.isFinite(input.x)) out.x = input.x;
+  if (typeof input.y === 'number' && Number.isFinite(input.y)) out.y = input.y;
+  if (typeof input.width === 'number' && Number.isFinite(input.width)) out.width = input.width;
+  if (typeof input.height === 'number' && Number.isFinite(input.height)) out.height = input.height;
+  return out;
+}

package/src/server/ext-app-call-registry.ts

@@ -0,0 +1,77 @@
+export interface ExtAppCallIdentity {
+  toolCallId?: string;
+  serverName?: string;
+  toolName?: string;
+}
+
+function normalizeKeyPart(value: string | undefined): string {
+  return value?.trim().toLowerCase() ?? '';
+}
+
+export function getExtAppCallKey(serverName?: string, toolName?: string): string | null {
+  const normalizedServerName = normalizeKeyPart(serverName);
+  const normalizedToolName = normalizeKeyPart(toolName);
+  if (!normalizedServerName || !normalizedToolName) return null;
+  return `${normalizedServerName}::${normalizedToolName}`;
+}
+
+export class ExtAppCallRegistry {
+  private activeIds = new Set<string>();
+  private keyById = new Map<string, string>();
+  private idsByKey = new Map<string, string[]>();
+
+  register(identity: ExtAppCallIdentity): string | null {
+    const toolCallId = String(identity.toolCallId || '').trim();
+    if (!toolCallId) return null;
+    this.activeIds.add(toolCallId);
+    const key = getExtAppCallKey(identity.serverName, identity.toolName);
+    if (key) {
+      this.keyById.set(toolCallId, key);
+      const existing = this.idsByKey.get(key)?.filter((id) => this.activeIds.has(id)) ?? [];
+      if (!existing.includes(toolCallId)) {
+        existing.push(toolCallId);
+      }
+      this.idsByKey.set(key, existing);
+    }
+    return toolCallId;
+  }
+
+  has(toolCallId?: string): boolean {
+    const id = String(toolCallId || '').trim();
+    return id.length > 0 && this.activeIds.has(id);
+  }
+
+  resolve(identity: ExtAppCallIdentity): string | null {
+    const directId = String(identity.toolCallId || '').trim();
+    if (directId && this.activeIds.has(directId)) {
+      return directId;
+    }
+    const key = getExtAppCallKey(identity.serverName, identity.toolName);
+    if (!key) return null;
+    const ids = this.idsByKey.get(key)?.filter((id) => this.activeIds.has(id)) ?? [];
+    return ids.length === 1 ? ids[0] : null;
+  }
+
+  complete(identity: ExtAppCallIdentity): string | null {
+    const resolvedId = this.resolve(identity);
+    if (!resolvedId) return null;
+    this.activeIds.delete(resolvedId);
+    const key = this.keyById.get(resolvedId);
+    this.keyById.delete(resolvedId);
+    if (key) {
+      const remaining = this.idsByKey.get(key)?.filter((id) => id !== resolvedId && this.activeIds.has(id)) ?? [];
+      if (remaining.length > 0) {
+        this.idsByKey.set(key, remaining);
+      } else {
+        this.idsByKey.delete(key);
+      }
+    }
+    return resolvedId;
+  }
+
+  clear(): void {
+    this.activeIds.clear();
+    this.keyById.clear();
+    this.idsByKey.clear();
+  }
+}

package/src/server/ext-app-tool-result.ts

@@ -0,0 +1,4 @@
+export {
+  normalizeExtAppToolResult,
+  type NormalizeExtAppToolResultInput,
+} from '../shared/ext-app-tool-result.js';

package/src/server/file-watcher.ts

@@ -0,0 +1,121 @@
+/**
+ * File watcher for file-type canvas nodes.
+ *
+ * Monitors files on disk and pushes content updates to the canvas
+ * when they change. This enables real-time file viewing: the agent
+ * edits a file, the canvas node updates automatically.
+ */
+
+import { watch, existsSync, readFileSync, statSync } from 'node:fs';
+import type { FSWatcher } from 'node:fs';
+import { canvasState } from './canvas-state.js';
+
+function logFileWatcherWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
+  console.warn(`[file-watcher] ${action}`, { error, ...(details ?? {}) });
+}
+
+interface WatchedFile {
+  path: string;
+  nodeIds: Set<string>;
+  watcher: FSWatcher;
+  lastMtime: number;
+}
+
+const watched = new Map<string, WatchedFile>();
+let onFileChanged: ((nodeId: string) => void) | null = null;
+
+/** Register a callback for when a watched file changes. */
+export function onFileNodeChanged(cb: (nodeId: string) => void): void {
+  onFileChanged = cb;
+}
+
+/** Start watching a file for a given node. */
+export function watchFileForNode(nodeId: string, filePath: string): void {
+  if (!filePath || !existsSync(filePath)) return;
+
+  const existing = watched.get(filePath);
+  if (existing) {
+    existing.nodeIds.add(nodeId);
+    return;
+  }
+
+  try {
+    const stat = statSync(filePath);
+    const watcher = watch(filePath, { persistent: false }, (eventType) => {
+      if (eventType !== 'change') return;
+      handleFileChange(filePath);
+    });
+
+    watched.set(filePath, {
+      path: filePath,
+      nodeIds: new Set([nodeId]),
+      watcher,
+      lastMtime: stat.mtimeMs,
+    });
+  } catch (error) {
+    logFileWatcherWarning('watch setup failed', error, { nodeId, filePath });
+  }
+}
+
+/** Stop watching a file for a given node. */
+export function unwatchFileForNode(nodeId: string, filePath?: string): void {
+  for (const [path, entry] of watched) {
+    if (filePath && path !== filePath) continue;
+    entry.nodeIds.delete(nodeId);
+    if (entry.nodeIds.size === 0) {
+      entry.watcher.close();
+      watched.delete(path);
+    }
+  }
+}
+
+/** Stop all watchers. */
+export function unwatchAll(): void {
+  for (const entry of watched.values()) {
+    entry.watcher.close();
+  }
+  watched.clear();
+}
+
+export function rewatchAllFileNodes(): void {
+  unwatchAll();
+  for (const node of canvasState.getLayout().nodes) {
+    if (node.type === 'file' && typeof node.data.path === 'string') {
+      watchFileForNode(node.id, node.data.path);
+    }
+  }
+}
+
+function handleFileChange(filePath: string): void {
+  const entry = watched.get(filePath);
+  if (!entry) return;
+
+  // Debounce: check mtime to avoid duplicate events
+  try {
+    if (!existsSync(filePath)) return;
+    const stat = statSync(filePath);
+    if (stat.mtimeMs === entry.lastMtime) return;
+    entry.lastMtime = stat.mtimeMs;
+
+    const content = readFileSync(filePath, 'utf-8');
+    const lineCount = content.split('\n').length;
+    const updatedAt = new Date(stat.mtimeMs).toISOString();
+
+    // Update all nodes watching this file
+    for (const nodeId of entry.nodeIds) {
+      const node = canvasState.getNode(nodeId);
+      if (!node) continue;
+      canvasState.updateNode(nodeId, {
+        data: {
+          ...node.data,
+          fileContent: content,
+          lineCount,
+          updatedAt,
+        },
+      });
+      onFileChanged?.(nodeId);
+    }
+  } catch (error) {
+    logFileWatcherWarning('handle file change failed', error, { filePath });
+  }
+}