pmx-canvas 0.6.1 → 0.6.3

package/src/client/nodes/ExtAppFrame.tsx

@@ -1467,7 +1467,13 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
               minHeight: 0,
               border: 'none',
               background: 'var(--c-panel)',
-              pointerEvents: isExpanded && status !== 'loading' ? 'auto' : 'none',
+              // Keep the expanded frame in Chromium's pointer hit-test tree from
+              // its first paint. Toggling none → auto when boot completes can
+              // leave the compositor routing the first click to the parent even
+              // though DOM hit testing and Playwright both resolve the button.
+              // The loading sibling is non-interactive; inline frames remain
+              // guarded by the preview catcher below.
+              pointerEvents: isExpanded ? 'auto' : 'none',
             }}
             title={`Ext App: ${toolName}`}
           />

package/src/client/nodes/use-iframe-content-height.ts

@@ -1,6 +1,9 @@
-import { useEffect, useRef } from 'preact/hooks';
-import { persistLayout, resizeNode } from '../state/canvas-store';
-import { computeContentGrowHeight } from '../canvas/auto-fit';
+import { effect } from '@preact/signals';
+import { useEffect } from 'preact/hooks';
+import { nodes, updateNode } from '../state/canvas-store';
+import { grabbingNodeId, otherHumans } from '../state/human-store';
+import { pushCanvasUpdate } from '../state/intent-bridge';
+import { computeContentGrowHeight, contentFitPosition } from '../canvas/auto-fit';
 import type { CanvasNodeState } from '../types';
 
 /**
@@ -11,43 +14,60 @@ import type { CanvasNodeState } from '../types';
  * because growth is monotonic with a dead-band — cannot oscillate. This is the
  * fix for iframe nodes whose body scrollHeight the parent can't measure.
  *
- * The latest node is read through a ref so the effect stays mounted across the
- * grow (its deps are only id + token). Putting node.size in the deps would re-run
- * the effect on each grow and its cleanup would cancel the pending persist.
+ * Debounce before changing geometry, retaining the latest measurement during a
+ * human grab. Read current geometry at application time; persist only this node.
+ * Relocations are undoable, height-only adjustments do not fill the undo stack.
  */
 export function useIframeContentHeight(
   node: CanvasNodeState,
   iframeRef: { current: HTMLIFrameElement | null },
   frameToken: string,
 ): void {
-  const nodeRef = useRef(node);
-  nodeRef.current = node;
-  const persistTimer = useRef<number | null>(null);
-
   useEffect(() => {
     if (!frameToken) return undefined;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let pendingHeight: number | null = null;
+    const held = () =>
+      grabbingNodeId.value === node.id || otherHumans.value.some((human) => human.grabbingNodeId === node.id);
+    function apply() {
+      timer = null;
+      if (held() || pendingHeight === null) return;
+      const reported = pendingHeight;
+      pendingHeight = null;
+      const current = nodes.value.get(node.id);
+      if (!current) return;
+      const target = computeContentGrowHeight(current, reported);
+      if (target === null) return;
+      const position = contentFitPosition(current, target, Array.from(nodes.value.values()));
+      const moved = position.x !== current.position.x || position.y !== current.position.y;
+      const patch = {
+        size: { width: current.size.width, height: target },
+        ...(moved ? { position } : {}),
+      };
+      updateNode(current.id, patch);
+      void pushCanvasUpdate([{ id: current.id, ...patch }], { recordHistory: moved });
+    }
+    function schedule() {
+      if (timer !== null) clearTimeout(timer);
+      timer = pendingHeight !== null && !held() ? setTimeout(apply, 300) : null;
+    }
+    const dispose = effect(() => {
+      held();
+      schedule();
+    });
     function onMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const d = event.data as { source?: string; type?: string; token?: string; height?: unknown } | null;
       if (!d || d.source !== 'pmx-canvas-frame' || d.type !== 'content-height' || d.token !== frameToken) return;
-      const current = nodeRef.current;
-      const reported = typeof d.height === 'number' ? d.height : 0;
-      const target = computeContentGrowHeight(current, reported);
-      if (target === null) return;
-      resizeNode(current.id, { width: current.size.width, height: target });
-      if (persistTimer.current !== null) window.clearTimeout(persistTimer.current);
-      persistTimer.current = window.setTimeout(() => {
-        persistLayout({ recordHistory: false });
-        persistTimer.current = null;
-      }, 300);
+      if (typeof d.height !== 'number' || !Number.isFinite(d.height) || d.height <= 0) return;
+      pendingHeight = d.height;
+      schedule();
     }
     window.addEventListener('message', onMessage);
     return () => {
       window.removeEventListener('message', onMessage);
-      if (persistTimer.current !== null) {
-        window.clearTimeout(persistTimer.current);
-        persistTimer.current = null;
-      }
+      dispose();
+      if (timer !== null) clearTimeout(timer);
     };
   }, [node.id, frameToken]);
 }

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

@@ -58,7 +58,7 @@ export function applyHumanSnapshot(snapshot: Partial<HumanPresenceSnapshot> | nu
   humans.value = snapshot.humans;
 }
 
-let grabbing: string | null = null;
+export const grabbingNodeId = signal<string | null>(null);
 let lastCursor: { x: number; y: number } | null = null;
 let lastSentAt = 0;
 let pending: ReturnType<typeof setTimeout> | null = null;
@@ -74,7 +74,7 @@ function post(body: Record<string, unknown>): void {
 function flushCursor(): void {
   pending = null;
   lastSentAt = Date.now();
-  post({ cursor: lastCursor, grabbingNodeId: grabbing });
+  post({ cursor: lastCursor, grabbingNodeId: grabbingNodeId.value });
 }
 
 /** Report the pointer in world coordinates (throttled); null when it leaves the canvas. */
@@ -91,7 +91,7 @@ export function reportHumanCursor(cursor: { x: number; y: number } | null): void
 
 /** Hold / release a node (drag, rename): the edit lock agents must respect. */
 export function reportHumanGrab(nodeId: string | null): void {
-  grabbing = nodeId;
+  grabbingNodeId.value = nodeId;
   post({ cursor: lastCursor, grabbingNodeId: nodeId });
 }
 
@@ -147,8 +147,8 @@ let heartbeat: ReturnType<typeof setInterval> | null = null;
 
 /** Announce this tab and keep it alive; renews a held grab. Call once per connection. */
 export function startHumanPresence(): () => void {
-  post({ cursor: lastCursor, grabbingNodeId: grabbing });
-  heartbeat = setInterval(() => post({ grabbingNodeId: grabbing }), 3000);
+  post({ cursor: lastCursor, grabbingNodeId: grabbingNodeId.value });
+  heartbeat = setInterval(() => post({ grabbingNodeId: grabbingNodeId.value }), 3000);
   const leave = () => {
     try {
       navigator.sendBeacon?.(
@@ -170,6 +170,6 @@ export function startHumanPresence(): () => void {
 export function resetHumanPresence(): void {
   humans.value = [];
   yieldedNodes.value = new Map();
-  grabbing = null;
+  grabbingNodeId.value = null;
   lastCursor = null;
 }

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

@@ -922,7 +922,9 @@ function handleCanvasLayoutUpdate(data: Record<string, unknown>): void {
       }
     : undefined;
 
-  cancelViewportAnimation();
+  // Routine node/layout broadcasts do not replace the camera, so must not
+  // interrupt a focus animation either (view.focus also emits a layout).
+  if (shouldApplyViewport) cancelViewportAnimation();
   applyServerCanvasLayout(
     {
       ...(nextViewport ? { viewport: nextViewport } : {}),

package/src/client/theme/global.css

@@ -1377,7 +1377,7 @@ body,
   animation: session-panel-in 180ms ease;
 }
 .session-panel.is-collapsed {
-  width: 28px;
+  width: 40px;
   align-items: center;
   padding-top: 10px;
   gap: 10px;
@@ -1390,6 +1390,17 @@ body,
   text-transform: uppercase;
   color: var(--c-dim);
 }
+.session-collapsed-live {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  font: 9px var(--mono);
+  color: var(--c-dim);
+}
+.session-collapsed-live .session-live-dot {
+  background: var(--c-ok);
+}
 
 .session-panel-header {
   height: var(--hud-bar-height);
@@ -1717,7 +1728,7 @@ body,
 }
 .session-timeline-filters .activity-filter {
   flex-shrink: 0;
-  padding: 2px 4px;
+  padding: 2px 3px;
 }
 
 .session-timeline-row {
@@ -3745,6 +3756,12 @@ body,
 }
 
 /* Node resize handle */
+.canvas-node:has(.node-resize-handle) {
+  /* Keep the four-pixel corner grab inside the shell's inner clip, not on
+     its rounded border. The other corners retain the standard card radius. */
+  border-bottom-right-radius: 8px;
+}
+
 .canvas-node .node-resize-handle {
   position: absolute;
   bottom: 0;
@@ -3789,7 +3806,9 @@ html.is-node-dragging .attention-field-layer {
 }
 
 html.is-node-dragging,
-html.is-node-dragging * {
+html.is-node-dragging *,
+html.is-canvas-panning,
+html.is-canvas-panning * {
   cursor: grabbing !important;
   user-select: none !important;
   -webkit-user-select: none !important;

package/src/json-render/catalog.ts

@@ -20,6 +20,12 @@ const buttonDefinition = shadcnComponentDefinitions.Button;
 
 export const allComponentDefinitions = {
   ...shadcnComponentDefinitions,
+  Card: {
+    ...shadcnComponentDefinitions.Card,
+    slots: ['default', 'header', 'footer'],
+    description:
+      'Card container. Use children for its body and optional header/footer slots for custom headings or actions. A header slot replaces the title and description props.',
+  },
   Badge: {
     ...badgeDefinition,
     props: badgeDefinition.props.extend({

package/src/json-render/renderer/index.tsx

@@ -69,9 +69,26 @@ function Button({ props, emit }: { props: ButtonProps; emit: (event: string) =>
   );
 }
 
+function Card({ props, children, slots, ...rest }: Parameters<typeof shadcnComponents.Card>[0]) {
+  const header = slots?.header;
+  const footer = slots?.footer;
+  return (
+    <shadcnComponents.Card {...rest} props={header ? { ...props, title: null, description: null } : props}>
+      {header && <header data-pmx-card-slot="header">{header}</header>}
+      {children}
+      {footer && (
+        <footer data-pmx-card-slot="footer" className="flex flex-wrap items-center gap-3">
+          {footer}
+        </footer>
+      )}
+    </shadcnComponents.Card>
+  );
+}
+
 const { registry } = defineRegistry(catalog as never, {
   components: {
     ...shadcnComponents,
+    Card,
     Badge,
     Button,
     ...chartComponents,

package/src/json-render/schema.ts

@@ -4,12 +4,16 @@ export const schema = defineSchema(
   (s) => ({
     spec: s.object({
       root: s.string(),
+      state: { ...s.record(s.any()), ...s.optional() },
       elements: s.record(
         s.object({
           type: s.ref('catalog.components'),
           props: s.propsOf('catalog.components'),
           children: s.array(s.string()),
           visible: s.any(),
+          repeat: { ...s.any(), ...s.optional() },
+          watch: { ...s.record(s.any()), ...s.optional() },
+          slots: { ...s.record(s.array(s.string())), ...s.optional() },
           // Event→action bindings (on.press, on.change, …). Preserved through
           // validation so spec authors can wire actions — including the ax.*
           // handlers the viewer forwards to the canvas AX bridge.

package/src/mcp/server.ts

@@ -41,6 +41,7 @@ import {
   summarizeCanvasAnnotationForContext,
 } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
+import { registerSkillExtension } from './skills.js';
 
 let canvas: CanvasAccess | null = null;
 let resourceNotificationServer: McpServer | null = null;
@@ -212,11 +213,15 @@ function buildSummaryFromLayout(
 }
 
 export async function startMcpServer(): Promise<void> {
-  const server = new McpServer({
-    name: 'pmx-canvas',
-    version: readPackageVersion(),
-  });
+  const server = new McpServer(
+    { name: 'pmx-canvas', version: readPackageVersion() },
+    {
+      instructions:
+        'Bundled workbench guidance: skill://pmx-canvas/SKILL.md. Discover skills via skills/list when supported, or canvas://skills; read files through resources/read. Skill delivery does not grant permission to execute bundled scripts.',
+    },
+  );
   resourceNotificationServer = server;
+  registerSkillExtension(server);
 
   // ── Operation-registry tools (plan-005) ────────────────────────
   // Standalone tools are registered from the shared operation registry for

package/src/mcp/skills.ts

@@ -0,0 +1,47 @@
+import { type McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { createBundledSkillCatalog } from '../server/bundled-skills.js';
+
+/** SEP-2640 methods are protocol requests, not model-facing canvas tools. */
+export function registerSkillExtension(server: McpServer, catalog = createBundledSkillCatalog()): void {
+  // The v1 SDK accepts custom methods and transmits capabilities unchanged,
+  // but its ServerCapabilities type predates the extensions field.
+  const capabilities = { resources: {}, extensions: { 'io.modelcontextprotocol/skills': {} } };
+  server.server.registerCapabilities(capabilities);
+  server.server.setRequestHandler(
+    z.object({ method: z.literal('skills/list'), params: z.object({ cursor: z.string().optional() }).optional() }),
+    async ({ params }) => {
+      // The bounded package catalog is a single page, so no cursor is issued.
+      if (params?.cursor !== undefined) throw new McpError(ErrorCode.InvalidParams, 'Unknown skills cursor');
+      return { resultType: 'complete', skills: catalog.skills };
+    },
+  );
+  server.server.setRequestHandler(
+    z.object({ method: z.literal('skills/get'), params: z.object({ uri: z.string() }) }),
+    async ({ params }) => {
+      const skill = catalog.skills.find((entry) => entry.uri === params.uri);
+      if (!skill) throw new McpError(ErrorCode.InvalidParams, `No skill is served at ${params.uri}`);
+      return { resultType: 'complete', skill };
+    },
+  );
+  server.registerResource(
+    'skill-files',
+    new ResourceTemplate('skill://{name}/{+path}', { list: undefined }),
+    { description: 'Packaged skill files. Discover complete manifests through skills/list or skills/get.' },
+    async (uri) => {
+      // Exact catalog lookup: a URI never becomes a filesystem path.
+      const content = catalog.files.get(uri.href);
+      if (!content) throw new McpError(ErrorCode.InvalidParams, `No skill file is served at ${uri.href}`);
+      return { contents: [content] };
+    },
+  );
+  for (const skill of catalog.skills) {
+    server.registerResource(
+      skill.frontmatter.name,
+      skill.uri,
+      { mimeType: 'text/markdown', description: skill.frontmatter.description },
+      async () => ({ contents: [catalog.files.get(skill.uri)!] }),
+    );
+  }
+}

package/src/server/bundled-skills.ts

@@ -17,15 +17,29 @@
  *   - `canvas://skills/<name>`   → full markdown content
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+const skillFrontmatterSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    description: z.string().min(1).max(1024),
+  })
+  .passthrough();
 
 export interface BundledSkill {
   name: string;
   description: string;
   uri: string;
   filePath: string;
+  frontmatter: z.infer<typeof skillFrontmatterSchema>;
 }
 
 const MAX_DESCRIPTION_LENGTH = 400;
@@ -65,52 +79,18 @@ export function findBundledSkillsRoot(): string | null {
   return null;
 }
 
-function parseFrontmatterDescription(rawMarkdown: string): string {
-  // Normalize CRLF first: a git checkout with autocrlf (the Windows default)
-  // puts a trailing \r on every line, which `(.*)$` cannot match (JS `.` and
-  // `$` both exclude \r), silently emptying every description.
-  const markdown = rawMarkdown.replace(/\r\n/g, '\n');
-  // YAML frontmatter lives between two `---` fences at the very top.
-  if (!markdown.startsWith('---')) return '';
-  const end = markdown.indexOf('\n---', 3);
-  if (end === -1) return '';
-  const frontmatter = markdown.slice(3, end);
-  const lines = frontmatter.split('\n');
-
-  // Support both single-line `description: ...` and block-scalar `description: >` /
-  // `description: |` forms (indented continuation lines).
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? '';
-    const match = /^description:\s*(.*)$/.exec(line);
-    if (!match) continue;
-    const first = (match[1] ?? '').trim();
-    if (first && first !== '>' && first !== '|' && first !== '>-' && first !== '|-') {
-      return first.slice(0, MAX_DESCRIPTION_LENGTH);
-    }
-    // Block scalar — concatenate indented follow-on lines.
-    const parts: string[] = [];
-    for (let j = i + 1; j < lines.length; j++) {
-      const follow = lines[j] ?? '';
-      if (follow.length === 0) {
-        parts.push('');
-        continue;
-      }
-      if (!/^\s/.test(follow)) break;
-      parts.push(follow.trim());
-    }
-    return parts.join(' ').replace(/\s+/g, ' ').trim().slice(0, MAX_DESCRIPTION_LENGTH);
-  }
-  return '';
+function parseFrontmatter(markdown: string): BundledSkill['frontmatter'] {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!match) throw new Error('Bundled skill is missing YAML frontmatter');
+  return skillFrontmatterSchema.parse(Bun.YAML.parse(match[1]!));
 }
 
 /**
  * Enumerate every `<name>/SKILL.md` under the bundled skills root and return
- * a compact index. Hidden directories (dotfolders) and files that don't parse
- * are skipped silently rather than throwing — missing metadata should never
- * break the MCP server's resource listing.
+ * a compact index. Invalid packaged skills fail explicitly rather than being
+ * silently omitted from the Skills extension's integrity manifest.
  */
-export function listBundledSkills(): BundledSkill[] {
-  const root = findBundledSkillsRoot();
+export function listBundledSkills(root = findBundledSkillsRoot()): BundledSkill[] {
   if (!root) return [];
   const entries = readdirSync(root);
   const skills: BundledSkill[] = [];
@@ -118,18 +98,19 @@ export function listBundledSkills(): BundledSkill[] {
     if (entry.startsWith('.')) continue;
     const skillFile = join(root, entry, 'SKILL.md');
     if (!existsSync(skillFile)) continue;
-    try {
-      const markdown = readFileSync(skillFile, 'utf-8');
-      const description = parseFrontmatterDescription(markdown);
-      skills.push({
-        name: entry,
-        description,
-        uri: `canvas://skills/${entry}`,
-        filePath: skillFile,
-      });
-    } catch {
-      // skip unreadable files
+    if (lstatSync(join(root, entry)).isSymbolicLink() || lstatSync(skillFile).isSymbolicLink()) {
+      throw new Error(`Bundled skill contains a symbolic link: ${entry}`);
     }
+    if (!lstatSync(skillFile).isFile()) throw new Error(`Bundled skill contains a non-regular file: ${skillFile}`);
+    const frontmatter = parseFrontmatter(readFileSync(skillFile, 'utf-8'));
+    if (frontmatter.name !== entry) throw new Error(`Bundled skill name does not match directory: ${entry}`);
+    skills.push({
+      name: entry,
+      description: frontmatter.description.slice(0, MAX_DESCRIPTION_LENGTH),
+      uri: `canvas://skills/${entry}`,
+      filePath: skillFile,
+      frontmatter,
+    });
   }
   skills.sort((a, b) => a.name.localeCompare(b.name));
   return skills;
@@ -145,3 +126,61 @@ export function readBundledSkill(name: string): string | null {
     return null;
   }
 }
+
+export interface SkillEntry {
+  uri: string;
+  frontmatter: BundledSkill['frontmatter'];
+  resources: Array<{ uri: string; digest: string; size: number }>;
+}
+
+type SkillContent = { uri: string; mimeType: string } & ({ text: string } | { blob: string });
+
+/** Capture immutable package bytes once per MCP process, never read caller-supplied paths. */
+export function createBundledSkillCatalog(root = findBundledSkillsRoot()) {
+  const skills: SkillEntry[] = [];
+  const files = new Map<string, SkillContent>();
+  for (const skill of listBundledSkills(root)) {
+    const entry: SkillEntry = { uri: `skill://${skill.name}/SKILL.md`, frontmatter: skill.frontmatter, resources: [] };
+    let totalBytes = 0;
+    function walk(directory: string, prefix = ''): void {
+      for (const child of readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
+        a.name.localeCompare(b.name),
+      )) {
+        const filePath = join(directory, child.name);
+        const relativePath = prefix + encodeURIComponent(child.name);
+        if (child.isSymbolicLink()) throw new Error(`Bundled skill contains a symbolic link: ${filePath}`);
+        if (child.isDirectory()) {
+          walk(filePath, `${relativePath}/`);
+          continue;
+        }
+        if (!child.isFile()) throw new Error(`Bundled skill contains a non-regular file: ${filePath}`);
+        totalBytes += lstatSync(filePath).size;
+        if (entry.resources.length >= 512 || totalBytes > 16 * 1024 * 1024) {
+          throw new Error(`Bundled skill exceeds SEP-2640 file/byte limits: ${skill.name}`);
+        }
+        const bytes = readFileSync(filePath);
+        const uri = `skill://${skill.name}/${relativePath}`;
+        const mimeType = child.name.endsWith('.md') ? 'text/markdown' : Bun.file(filePath).type;
+        // Round-trip detection preserves invalid UTF-8 and binary assets as blobs.
+        const text = bytes.toString('utf8');
+        const content =
+          !bytes.includes(0) && Buffer.from(text).equals(bytes)
+            ? { uri, mimeType, text }
+            : { uri, mimeType, blob: bytes.toString('base64') };
+        files.set(uri, content);
+        entry.resources.push({
+          uri,
+          size: bytes.length,
+          digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+        });
+        if (uri === entry.uri) entry.frontmatter = parseFrontmatter(text);
+      }
+    }
+    walk(dirname(skill.filePath));
+    if (entry.frontmatter.name !== skill.name)
+      throw new Error(`Bundled skill name changed during loading: ${skill.name}`);
+    entry.resources.sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+    skills.push(entry);
+  }
+  return { skills, files };
+}

package/src/server/canvas-operations.ts

@@ -726,7 +726,7 @@ function shouldTreatFileContentAsPath(input: CanvasAddNodeInput): boolean {
   const content = input.content?.trim() ?? '';
   if (!content || content.includes('\n') || content.includes('\r')) return false;
   if (typeof input.data?.path === 'string' && input.data.path.length > 0) return true;
-  if (existsSync(resolve(content))) return true;
+  if (existsSync(resolve(canvasState.getWorkspaceRoot(), content))) return true;
   if (!input.title) return true;
   return content.startsWith('/') || content.startsWith('./') || content.startsWith('../') || content.includes('/');
 }
@@ -748,7 +748,7 @@ function buildFileNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
 
   const rawPath =
     typeof input.data?.path === 'string' && input.data.path.length > 0 ? input.data.path : (input.content ?? '');
-  const resolved = resolve(rawPath);
+  const resolved = resolve(canvasState.getWorkspaceRoot(), rawPath);
   const fileName = basename(resolved) || rawPath;
   const data: Record<string, unknown> = {
     ...(input.data ?? {}),

package/src/server/operations/ops/nodes.ts

@@ -8,6 +8,7 @@
  *
  * This module must never import server.ts or index.ts.
  */
+import { resolve } from 'node:path';
 import { z } from 'zod';
 import { canvasState, type CanvasAnnotation, type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
 import {
@@ -1145,7 +1146,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
     },
   },
   handler: async (input, ctx) => {
-    const body: Record<string, unknown> = input;
+    let body: Record<string, unknown> = input;
     const id = input.id;
     const existing = canvasState.getNode(id);
     if (!existing) throw new OperationError(`Node "${id}" not found.`, 404);
@@ -1162,7 +1163,48 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       const result = await refreshCanvasWebpageNode(id, { ...(url ? { url } : {}) });
       return result as unknown as Record<string, unknown>;
     }
+
+    let nextFilePath: string | null = null;
+    let nextFileContent: ReturnType<typeof readFileNodeContent> | null = null;
+    if (existing.type === 'file') {
+      const nestedData = isRecord(body.data) ? body.data : undefined;
+      const hasTopLevelPath = body.path !== undefined;
+      const hasNestedPath = nestedData?.path !== undefined;
+      if (hasTopLevelPath || hasNestedPath) {
+        const normalizePath = (value: unknown): string => {
+          if (typeof value !== 'string' || !value.trim()) {
+            throw new OperationError('File node "path" must be a non-empty string.');
+          }
+          return resolve(canvasState.getWorkspaceRoot(), value.trim());
+        };
+        const normalizedTopLevelPath = hasTopLevelPath ? normalizePath(body.path) : undefined;
+        const normalizedNestedPath = hasNestedPath ? normalizePath(nestedData?.path) : undefined;
+        body = {
+          ...body,
+          ...(normalizedTopLevelPath ? { path: normalizedTopLevelPath } : {}),
+          ...(nestedData
+            ? { data: { ...nestedData, ...(normalizedNestedPath ? { path: normalizedNestedPath } : {}) } }
+            : {}),
+        };
+        nextFilePath = normalizedNestedPath ?? normalizedTopLevelPath ?? null;
+        nextFileContent = nextFilePath ? readFileNodeContent(nextFilePath) : null;
+        if (!nextFileContent || nextFileContent.kind === 'unavailable') {
+          throw new OperationError(`File node target "${nextFilePath}" is missing or unreadable.`);
+        }
+      }
+    }
+
     const { patch, groupChildIds } = buildNodePatch(existing, body);
+    const prevPath = existing.type === 'file' && typeof existing.data.path === 'string' ? existing.data.path : null;
+    if (nextFilePath && nextFileContent && patch.data) {
+      const data = { ...patch.data };
+      const prevBase = prevPath?.split(/[\\/]/).pop();
+      if (typeof body.title !== 'string' && (!data.title || data.title === prevBase)) {
+        data.title = nextFilePath.split(/[\\/]/).pop();
+      }
+      applyFileContentToNodeData(data, nextFileContent);
+      patch.data = data;
+    }
     canvasState.updateNode(id, patch);
     if (groupChildIds !== undefined && !setGroupChildrenFromApi(id, groupChildIds)) {
       throw new OperationError(`Group "${id}" not found.`, 404);
@@ -1171,20 +1213,10 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
     // watcher IN PLACE — before this, pointing a file node elsewhere meant
     // recreating it, which lost its edges, pins, and position.
     if (existing.type === 'file') {
-      const prevPath = typeof existing.data.path === 'string' ? existing.data.path : null;
       const repointed = canvasState.getNode(id);
       const nextPath = repointed && typeof repointed.data.path === 'string' ? repointed.data.path : null;
       if (nextPath && nextPath !== prevPath) {
         if (prevPath) unwatchFileForNode(id, prevPath);
-        const data = { ...repointed!.data };
-        // The title follows the file unless the caller pinned one in this
-        // patch or had renamed the node away from the old filename.
-        const prevBase = prevPath?.split(/[\\/]/).pop();
-        if (typeof body.title !== 'string' && (!data.title || data.title === prevBase)) {
-          data.title = nextPath.split(/[\\/]/).pop();
-        }
-        applyFileContentToNodeData(data, readFileNodeContent(nextPath));
-        canvasState.updateNode(id, { data });
         watchFileForNode(id, nextPath);
         scheduleCodeGraphRecompute(() => {
           ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });