pmx-canvas 0.1.1 → 0.1.2

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

@@ -14,5 +14,5 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
 export declare function ExtAppFrame({ node }: {
     node: CanvasNodeState;
-}): import("preact/src").JSX.Element;
+}): import("preact/jsx-runtime").JSX.Element;
 export {};

package/dist/types/server/bundled-skills.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bundled-skill discovery for the PMX Canvas MCP server.
+ *
+ * Skill files ship inside the npm package under `skills/<name>/SKILL.md`
+ * but until 0.1.2 they were not discoverable to the agent — an agent
+ * calling `canvas_build_web_artifact` had no way to find the companion
+ * `skills/web-artifacts-builder/SKILL.md` prompt that documents the
+ * workflow, stack choices, and gotchas.
+ *
+ * This module locates the bundled `skills/` directory relative to the
+ * package root (works for both repo-local development and global npm
+ * installs), parses the YAML frontmatter of each `SKILL.md` to produce
+ * a compact index, and reads individual skill content on demand.
+ *
+ * Exposed via MCP as:
+ *   - `canvas://skills`          → JSON index
+ *   - `canvas://skills/<name>`   → full markdown content
+ */
+export interface BundledSkill {
+    name: string;
+    description: string;
+    uri: string;
+    filePath: string;
+}
+/**
+ * Resolve the packaged `skills/` directory. Walks parents from this module
+ * looking for a sibling `skills/` that contains at least one `<name>/SKILL.md`,
+ * so it works whether the code runs from source (`src/server/…`), from a
+ * compiled bundle (`dist/…`), or from a global npm install
+ * (`/opt/homebrew/lib/node_modules/pmx-canvas/src/server/…`).
+ */
+export declare function findBundledSkillsRoot(): string | null;
+/**
+ * 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.
+ */
+export declare function listBundledSkills(): BundledSkill[];
+export declare function readBundledSkill(name: string): string | null;

package/dist/types/shared/ext-app-tool-result.d.ts

@@ -7,3 +7,15 @@ export interface NormalizeExtAppToolResultInput {
     detailedContent?: string;
 }
 export declare function normalizeExtAppToolResult(input: NormalizeExtAppToolResultInput): CallToolResult;
+/**
+ * Structural equality between two `CallToolResult` values, used by the host
+ * ExtAppFrame to suppress echo-back re-renders when an SSE layout update
+ * mints a new object reference for an otherwise-unchanged tool result.
+ *
+ * JSON-stringify is adequate here: tool results are strictly JSON (no
+ * functions, symbols, or cycles), typically small, and on the hot path we
+ * only hit this when references already differ. For very large payloads
+ * (> ~2MB) an early length check skips the stringify to avoid a user-visible
+ * stall — such results are treated as "changed" and forwarded to the widget.
+ */
+export declare function extAppToolResultsMatch(a: CallToolResult, b: CallToolResult): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/src/cli/index.ts

@@ -1,13 +1,31 @@
 #!/usr/bin/env bun
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAgentCli } from './agent.js';
 import { createCanvas } from '../server/index.js';
 
 const args = process.argv.slice(2);
 
+// ── --version / -v ─────────────────────────────────────────────
+// Print the installed package version and exit. Resolved from the
+// sibling package.json so it stays accurate through bunx, global npm
+// installs, and repo-local runs (no hard-coded string, no build step
+// required).
+if (args.includes('--version') || args.includes('-v')) {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
+    console.log(pkg.version ?? 'unknown');
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`pmx-canvas: failed to read package.json (${message})`);
+    process.exit(1);
+  }
+}
+
 // ── Agent CLI subcommands ────────────────────────────────────
 // If first arg is a known subcommand (not a --flag), route to the agent CLI.
 const AGENT_COMMANDS = new Set([

package/src/client/nodes/ExtAppFrame.tsx

@@ -2,6 +2,7 @@ import type { CallToolResult, ListToolsResult, RequestId, Tool } from '@modelcon
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { AppBridge, PostMessageTransport, buildAllowAttribute } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { useEffect, useRef, useState } from 'preact/hooks';
+import { extAppToolResultsMatch } from '../../shared/ext-app-tool-result.js';
 import {
   canvasTheme,
   collapseExpandedNode,
@@ -103,6 +104,7 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
   const latestToolInputRef = useRef<Record<string, unknown>>({});
   const latestToolResultRef = useRef<CallToolResult | undefined>(undefined);
   const toolResultSentRef = useRef(false);
+  const lastSentToolResultRef = useRef<CallToolResult | undefined>(undefined);
   const toolResultSendingRef = useRef<Promise<void> | null>(null);
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
@@ -140,13 +142,33 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
 
   const flushToolResult = (bridge: AppBridge | null): Promise<void> | null => {
     const pendingToolResult = latestToolResultRef.current;
-    if (!bridge || !bridgeReadyRef.current || !pendingToolResult || toolResultSentRef.current) {
+    if (!bridge || !bridgeReadyRef.current || !pendingToolResult) {
+      return null;
+    }
+    // Skip when the content is unchanged. Updates from callServerTool
+    // (e.g. Excalidraw saving edits) produce a new reference via SSE and
+    // must be forwarded to keep other clients in sync — but SSE layout
+    // updates *also* mint new references when nothing in the tool result
+    // has actually changed (e.g. after the widget's own updateModelContext
+    // call), which would echo the result back and cause the widget to
+    // re-render mid-interaction (see: Counter fixture click instability).
+    // Deep-equality via structural compare handles both cases: new content
+    // is forwarded, unchanged content is suppressed.
+    if (lastSentToolResultRef.current === pendingToolResult) {
+      return null;
+    }
+    if (
+      lastSentToolResultRef.current &&
+      extAppToolResultsMatch(lastSentToolResultRef.current, pendingToolResult)
+    ) {
+      lastSentToolResultRef.current = pendingToolResult;
       return null;
     }
     if (toolResultSendingRef.current) return toolResultSendingRef.current;
     const sendPromise = bridge
       .sendToolResult(pendingToolResult)
       .then(() => {
+        lastSentToolResultRef.current = pendingToolResult;
         toolResultSentRef.current = true;
         setStatus('done');
       })
@@ -170,6 +192,7 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
     let disposed = false;
     let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
     toolResultSentRef.current = false;
+    lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
     bridgeReadyRef.current = false;
 
@@ -323,10 +346,14 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
       // handshake timing differs across SDK versions.
       fallbackTimer = setTimeout(() => {
         if (disposed || bridgeReadyRef.current) return;
-        void sendExtAppBootstrapState(bridge, latestToolInputRef.current, latestToolResultRef.current)
+        const bootstrapToolResult = latestToolResultRef.current;
+        void sendExtAppBootstrapState(bridge, latestToolInputRef.current, bootstrapToolResult)
           .then(() => {
-            toolResultSentRef.current = Boolean(latestToolResultRef.current);
-            setStatus(latestToolResultRef.current ? 'done' : 'ready');
+            toolResultSentRef.current = Boolean(bootstrapToolResult);
+            if (bootstrapToolResult) {
+              lastSentToolResultRef.current = bootstrapToolResult;
+            }
+            setStatus(bootstrapToolResult ? 'done' : 'ready');
             setError(null);
           })
           .catch((err) => {
@@ -344,7 +371,8 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
       bridgeRef.current = bridge;
       transportRef.current = transport;
 
-      // Propagate theme changes to ext-app iframe
+      // Propagate theme changes to ext-app iframe. Read current expanded state
+      // at fire time so the widget keeps its fullscreen/inline context accurate.
       let firstFire = true;
       themeUnsubRef.current = canvasTheme.subscribe((newTheme) => {
         if (firstFire) { firstFire = false; return; }
@@ -353,7 +381,7 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
           theme: toMcpTheme(newTheme),
           platform: 'web',
           containerDimensions: { maxHeight },
-          displayMode: 'inline',
+          displayMode: expandedNodeId.value === nodeId ? 'fullscreen' : 'inline',
           locale: navigator.language,
           timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
         });
@@ -392,6 +420,24 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
     }
   }, [toolResult, status]);
 
+  // Keep the widget's displayMode in sync when the host expands or collapses
+  // the node. Without this, a widget that opened in inline mode would never
+  // learn that it is now fullscreen (and vice versa), so features gated on
+  // fullscreen (like Excalidraw's edit mode) would not activate on the same
+  // click that triggered the expansion.
+  useEffect(() => {
+    const bridge = bridgeRef.current;
+    if (!bridge || !bridgeReadyRef.current) return;
+    bridge.setHostContext?.({
+      theme: toMcpTheme(canvasTheme.value),
+      platform: 'web',
+      containerDimensions: { maxHeight },
+      displayMode: isExpanded ? 'fullscreen' : 'inline',
+      locale: navigator.language,
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    });
+  }, [isExpanded, maxHeight]);
+
   // Loading state — HTML not yet fetched
   if (!html) {
     return (
@@ -493,17 +539,45 @@ export function ExtAppFrame({ node }: { node: CanvasNodeState }) {
           Connecting to ext-app viewer...
         </div>
       )}
-      {/* allow-scripts only (no allow-same-origin) — srcdoc gets opaque origin,
-          cannot access host cookies/storage/DOM. Communication via postMessage only. */}
-      <iframe
-        key={frameKey}
-        ref={iframeRef}
-        srcdoc={html}
-        sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox"
-        allow={buildAllowAttribute(resourceMeta?.permissions)}
-        style={{ flex: 1, border: 'none', background: 'var(--c-panel)' }}
-        title={`Ext App: ${toolName}`}
-      />
+      {/* Iframe stack: the widget renders a preview; when not expanded, a
+          transparent click-catcher sits on top so the first click always
+          expands the node. Without this, widgets like Excalidraw show their
+          own "Edit" button inline, which triggers a fullscreen request and
+          remounts the iframe in the overlay — forcing the user to click Edit
+          a second time to actually enter edit mode. Routing all inline clicks
+          to "expand" makes the flow "open → edit" instead of "edit → expand → edit". */}
+      <div style={{ flex: 1, position: 'relative', display: 'flex', minHeight: 0 }}>
+        <iframe
+          key={frameKey}
+          ref={iframeRef}
+          srcdoc={html}
+          sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox"
+          allow={buildAllowAttribute(resourceMeta?.permissions)}
+          style={{ flex: 1, border: 'none', background: 'var(--c-panel)' }}
+          title={`Ext App: ${toolName}`}
+        />
+        {!isExpanded && (
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              expandNode(nodeId);
+            }}
+            class="ext-app-preview-catcher"
+            title="Click to open"
+            style={{
+              position: 'absolute',
+              inset: 0,
+              background: 'transparent',
+              border: 'none',
+              padding: 0,
+              margin: 0,
+              cursor: 'zoom-in',
+            }}
+            aria-label="Open full view to edit"
+          />
+        )}
+      </div>
     </div>
   );
 }

package/src/mcp/server.ts

@@ -37,6 +37,7 @@ import { searchNodes, buildSpatialContext, findNeighborhoods } from '../server/s
 import { mutationHistory, diffLayouts, formatDiff } from '../server/mutation-history.js';
 import { buildCodeGraphSummary, formatCodeGraph } from '../server/code-graph.js';
 import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from '../server/canvas-serialization.js';
+import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 
 let canvas: PmxCanvas | null = null;
 
@@ -339,7 +340,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_build_web_artifact ───────────────────────────────
   server.tool(
     'canvas_build_web_artifact',
-    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. Optionally opens the generated artifact as an embedded node on the canvas.',
+    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
     {
       title: z.string().describe('Artifact title used for default project and output paths'),
       appTsx: z.string().describe('Contents for src/App.tsx'),
@@ -1158,6 +1159,68 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  // ── canvas://skills ────────────────────────────────────────
+  // Discoverability for the skill prompts bundled with the npm package
+  // (skills/<name>/SKILL.md). Before 0.1.2 these files shipped but were
+  // invisible to agents — calling canvas_build_web_artifact without the
+  // companion `web-artifacts-builder` skill led to predictable misuse.
+  // The index lists every bundled skill with its frontmatter description;
+  // individual skills are served verbatim at canvas://skills/<name>.
+  server.resource(
+    'bundled-skills',
+    'canvas://skills',
+    {
+      description:
+        'Index of agent skills bundled with this PMX Canvas install. Lists name, ' +
+        'description, and per-skill URI (canvas://skills/<name>). Read a specific ' +
+        'skill for workflow guidance — notably web-artifacts-builder for ' +
+        'canvas_build_web_artifact, and pmx-canvas for the broader workbench.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const skills = listBundledSkills();
+      const index = {
+        count: skills.length,
+        skills: skills.map((s) => ({ name: s.name, description: s.description, uri: s.uri })),
+      };
+      return {
+        contents: [
+          {
+            uri: 'canvas://skills',
+            mimeType: 'application/json',
+            text: JSON.stringify(index, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  // Register each bundled skill as its own resource so agents can address
+  // them individually (canvas://skills/web-artifacts-builder, etc.) and
+  // MCP clients can display them with per-skill descriptions.
+  for (const skill of listBundledSkills()) {
+    server.resource(
+      `skill-${skill.name}`,
+      skill.uri,
+      {
+        description: skill.description || `Bundled PMX Canvas skill: ${skill.name}`,
+        mimeType: 'text/markdown',
+      },
+      async () => {
+        const markdown = readBundledSkill(skill.name);
+        return {
+          contents: [
+            {
+              uri: skill.uri,
+              mimeType: 'text/markdown',
+              text: markdown ?? `# ${skill.name}\n\n_Skill file not found on disk._\n`,
+            },
+          ],
+        };
+      },
+    );
+  }
+
   // ── canvas_create_group ──────────────────────────────────────
   server.tool(
     'canvas_create_group',

package/src/server/bundled-skills.ts

@@ -0,0 +1,143 @@
+/**
+ * Bundled-skill discovery for the PMX Canvas MCP server.
+ *
+ * Skill files ship inside the npm package under `skills/<name>/SKILL.md`
+ * but until 0.1.2 they were not discoverable to the agent — an agent
+ * calling `canvas_build_web_artifact` had no way to find the companion
+ * `skills/web-artifacts-builder/SKILL.md` prompt that documents the
+ * workflow, stack choices, and gotchas.
+ *
+ * This module locates the bundled `skills/` directory relative to the
+ * package root (works for both repo-local development and global npm
+ * installs), parses the YAML frontmatter of each `SKILL.md` to produce
+ * a compact index, and reads individual skill content on demand.
+ *
+ * Exposed via MCP as:
+ *   - `canvas://skills`          → JSON index
+ *   - `canvas://skills/<name>`   → full markdown content
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface BundledSkill {
+  name: string;
+  description: string;
+  uri: string;
+  filePath: string;
+}
+
+const MAX_DESCRIPTION_LENGTH = 400;
+
+/**
+ * Resolve the packaged `skills/` directory. Walks parents from this module
+ * looking for a sibling `skills/` that contains at least one `<name>/SKILL.md`,
+ * so it works whether the code runs from source (`src/server/…`), from a
+ * compiled bundle (`dist/…`), or from a global npm install
+ * (`/opt/homebrew/lib/node_modules/pmx-canvas/src/server/…`).
+ */
+export function findBundledSkillsRoot(): string | null {
+  let current = dirname(fileURLToPath(import.meta.url));
+  const seen = new Set<string>();
+  while (!seen.has(current)) {
+    seen.add(current);
+    const candidate = join(current, 'skills');
+    if (existsSync(candidate)) {
+      try {
+        if (statSync(candidate).isDirectory()) {
+          const entries = readdirSync(candidate);
+          for (const entry of entries) {
+            if (existsSync(join(candidate, entry, 'SKILL.md'))) {
+              return resolve(candidate);
+            }
+          }
+        }
+      } catch {
+        // swallow and keep walking up — a permissions/transient error on this
+        // candidate shouldn't prevent finding a valid skills root higher up.
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function parseFrontmatterDescription(markdown: string): string {
+  // 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 '';
+}
+
+/**
+ * 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.
+ */
+export function listBundledSkills(): BundledSkill[] {
+  const root = findBundledSkillsRoot();
+  if (!root) return [];
+  const entries = readdirSync(root);
+  const skills: BundledSkill[] = [];
+  for (const entry of entries) {
+    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
+    }
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return skills;
+}
+
+export function readBundledSkill(name: string): string | null {
+  const skills = listBundledSkills();
+  const match = skills.find((s) => s.name === name);
+  if (!match) return null;
+  try {
+    return readFileSync(match.filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}

package/src/server/canvas-operations.ts

@@ -392,17 +392,36 @@ function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown>
   const src = input.content ?? '';
   const isDataUri = src.startsWith('data:');
   const isUrl = src.startsWith('http://') || src.startsWith('https://');
+
+  if (isDataUri) {
+    // Basic data-URI sanity: must be an image/* mediatype.
+    const header = src.slice(5, src.indexOf(',') >= 0 ? src.indexOf(',') : src.length);
+    if (!/^image\//i.test(header)) {
+      throw new Error(
+        `Invalid image node: data URI must be an image/* media type (got "${header.slice(0, 40)}"). ` +
+          `Accepted: png, jpeg, gif, svg+xml, webp, bmp, avif, x-icon.`,
+      );
+    }
+  }
+
   if (!isDataUri && !isUrl && src) {
     const resolved = resolve(src);
+    const ext = resolved.split('.').pop()?.toLowerCase() ?? '';
     const fileName = resolved.split('/').pop() ?? src;
+    const mime = IMAGE_MIME_MAP[ext];
+    if (!mime) {
+      throw new Error(
+        `Invalid image node: "${fileName}" has unsupported extension ".${ext}". ` +
+          `Accepted: ${Object.keys(IMAGE_MIME_MAP).join(', ')}. ` +
+          `For non-image files use type="file" (live viewer) or type="webpage" (URL) instead.`,
+      );
+    }
     return {
       ...(input.data ?? {}),
       src: resolved,
       title: input.title ?? fileName,
       path: resolved,
-      ...(IMAGE_MIME_MAP[resolved.split('.').pop()?.toLowerCase() ?? '']
-        ? { mimeType: IMAGE_MIME_MAP[resolved.split('.').pop()?.toLowerCase() ?? ''] }
-        : {}),
+      mimeType: mime,
     };
   }
 

package/src/server/server.ts

@@ -1105,19 +1105,26 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
-  const { id, node, needsCodeGraphRecompute } = addCanvasNode({
-    type: type as CanvasNodeState['type'],
-    ...(typeof body.title === 'string' ? { title: body.title } : {}),
-    ...(typeof body.content === 'string' ? { content: body.content } : {}),
-    ...(extraData ? { data: extraData } : {}),
-    ...(typeof body.x === 'number' ? { x: body.x } : {}),
-    ...(typeof body.y === 'number' ? { y: body.y } : {}),
-    ...(typeof body.width === 'number' ? { width: body.width } : {}),
-    ...(typeof body.height === 'number' ? { height: body.height } : {}),
-    defaultWidth: 360,
-    defaultHeight: 200,
-    fileMode: 'auto',
-  });
+  let added: ReturnType<typeof addCanvasNode>;
+  try {
+    added = addCanvasNode({
+      type: type as CanvasNodeState['type'],
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(typeof body.content === 'string' ? { content: body.content } : {}),
+      ...(extraData ? { data: extraData } : {}),
+      ...(typeof body.x === 'number' ? { x: body.x } : {}),
+      ...(typeof body.y === 'number' ? { y: body.y } : {}),
+      ...(typeof body.width === 'number' ? { width: body.width } : {}),
+      ...(typeof body.height === 'number' ? { height: body.height } : {}),
+      defaultWidth: 360,
+      defaultHeight: 200,
+      fileMode: 'auto',
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return responseJson({ ok: false, error: message }, 400);
+  }
+  const { node, needsCodeGraphRecompute } = added;
 
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   if (needsCodeGraphRecompute) {