pmx-canvas 0.1.4 → 0.1.6

package/src/server/canvas-schema.ts

@@ -22,6 +22,7 @@ export interface CanvasCreateTypeSchema {
   kind: 'node' | 'virtual-node';
   description: string;
   endpoint: string;
+  mcpTool?: string;
   fields: CanvasCreateField[];
   example: Record<string, unknown>;
   notes?: string[];
@@ -63,6 +64,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Freeform markdown note.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'content', type: 'string', required: false, description: 'Markdown body.' },
@@ -85,6 +87,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Compact status indicator.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Status label.' },
       { name: 'content', type: 'string', required: false, description: 'Rendered status text.' },
@@ -100,6 +103,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Agent context card container.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'content', type: 'string', required: false, description: 'Optional context body.' },
@@ -115,6 +119,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Structured ledger/log node.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Ledger body text.' },
@@ -130,6 +135,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Execution trace viewer.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
@@ -145,6 +151,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Workspace file viewer.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Workspace-relative or absolute file path.' },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -162,6 +169,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Image node backed by a path, URL, or data URI.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.' },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -187,6 +195,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Persisted webpage snapshot with server-side fetch and refresh.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'url', type: 'string', required: true, description: 'HTTP(S) URL to fetch and cache.', aliases: ['content'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -210,6 +219,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Hosted iframe/app node.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_open_mcp_app',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'App title.' },
       { name: 'content', type: 'string', required: false, description: 'Optional inline content.' },
@@ -223,11 +233,35 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Tool-backed MCP app nodes and hosted artifact nodes persist `data.provenance` when the server can infer a reopen or rehydrate path.',
     ],
   },
+  {
+    type: 'external-app',
+    kind: 'virtual-node',
+    description: 'Tool-backed hosted app opened from an external MCP server, such as Excalidraw.',
+    endpoint: '/api/canvas/mcp-app/open',
+    mcpTool: 'canvas_open_mcp_app',
+    fields: [
+      { name: 'toolName', type: 'string', required: true, description: 'Tool name on the external MCP server.' },
+      { name: 'transport', type: '{ type: "stdio", command, args? } | { type: "http", url, headers? }', required: true, description: 'External MCP transport definition.' },
+      { name: 'toolArguments', type: 'record<string, unknown>', required: false, description: 'Arguments passed to the external MCP tool.' },
+      { name: 'title', type: 'string', required: false, description: 'Optional canvas node title override.' },
+    ],
+    example: {
+      toolName: 'create_view',
+      transport: { type: 'http', url: 'https://mcp.excalidraw.com/mcp' },
+      toolArguments: { elements: '[]' },
+      title: 'Excalidraw Diagram',
+    },
+    notes: [
+      'For Excalidraw specifically, prefer canvas_add_diagram because it fills in the built-in transport, toolName, and checkpoint wiring.',
+      'The CLI convenience command `external-app add --kind excalidraw` maps to this built-in Excalidraw preset; MCP canvas_open_mcp_app is the lower-level transport form.',
+    ],
+  },
   {
     type: 'group',
     kind: 'node',
     description: 'Canvas group frame.',
     endpoint: '/api/canvas/group',
+    mcpTool: 'canvas_create_group',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Group title.' },
       { name: 'childIds', type: 'string[]', required: false, description: 'Initial child node IDs.' },
@@ -244,6 +278,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native structured UI panel rendered from a validated json-render spec.',
     endpoint: '/api/canvas/json-render',
+    mcpTool: 'canvas_add_json_render_node',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Rendered node title.' },
       { name: 'spec', type: 'JsonRenderSpec', required: true, description: 'Complete json-render spec.' },
@@ -276,6 +311,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native chart node backed by the json-render chart catalog.',
     endpoint: '/api/canvas/graph',
+    mcpTool: 'canvas_add_graph_node',
     fields: [
       {
         name: 'graphType',
@@ -325,6 +361,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Bundled single-file HTML artifact that can open as an embedded canvas node.',
     endpoint: '/api/canvas/web-artifact',
+    mcpTool: 'canvas_build_web_artifact',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Artifact title used for default paths.' },
       { name: 'appTsx', type: 'string', required: true, description: 'Contents for src/App.tsx. The CLI also accepts piped contents via --stdin.', aliases: ['app-file', 'app-tsx'] },
@@ -349,6 +386,16 @@ function clone<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+function buildMcpNodeTypeRouting(nodeTypes: CanvasCreateTypeSchema[]): Record<string, string> {
+  const routing: Record<string, string> = {};
+  for (const entry of nodeTypes) {
+    if (typeof entry.mcpTool === 'string') {
+      routing[entry.type] = entry.mcpTool;
+    }
+  }
+  return routing;
+}
+
 export function describeCanvasSchema(): {
   ok: true;
   source: 'running-server';
@@ -364,13 +411,15 @@ export function describeCanvasSchema(): {
   mcp: {
     tools: string[];
     resources: string[];
+    nodeTypeRouting: Record<string, string>;
   };
 } {
+  const nodeTypes = clone(CANVAS_CREATE_TYPES);
   return {
     ok: true,
     source: 'running-server',
     version: readPackageVersion(),
-    nodeTypes: clone(CANVAS_CREATE_TYPES),
+    nodeTypes,
     jsonRender: {
       rootShape: {
         root: 'string',
@@ -388,10 +437,13 @@ export function describeCanvasSchema(): {
         'canvas_add_json_render_node',
         'canvas_add_graph_node',
         'canvas_build_web_artifact',
+        'canvas_open_mcp_app',
+        'canvas_create_group',
         'canvas_describe_schema',
         'canvas_validate_spec',
       ],
       resources: ['canvas://schema'],
+      nodeTypeRouting: buildMcpNodeTypeRouting(nodeTypes),
     },
   };
 }

package/src/server/image-source.ts

@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { IMAGE_MIME_MAP } from './canvas-state.js';
+
+const IMAGE_HEADER_BYTES = 512;
+const IMAGE_HEADER_READ_TIMEOUT_MS = 5000;
+// Set by `chflags hidden`, iCloud Drive, OneDrive, etc. on macOS — the
+// metadata exists but the file content has not been downloaded locally.
+const MACOS_DATALESS_FLAG = 0x40000000;
+// Per macOS `man stat -f %Xf`, this bit is also set on iCloud Documents
+// & Files for content-not-yet-downloaded entries on newer OS releases.
+const MACOS_BSD_NODUMP_FLAG = 0x00000001;
+
+function fileName(path: string): string {
+  return basename(path) || path;
+}
+
+function readMacosFileFlags(path: string): number | null {
+  if (process.platform !== 'darwin') return null;
+
+  try {
+    const raw = execFileSync('/usr/bin/stat', ['-f', '%Xf', path], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+    }).trim();
+    return raw.length > 0 ? Number.parseInt(raw, 16) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isMacosCloudPlaceholder(path: string): boolean {
+  const flags = readMacosFileFlags(path);
+  if (flags === null) return false;
+  // Both flags can indicate iCloud-on-demand status depending on macOS
+  // release; treat either as a placeholder.
+  return (flags & MACOS_DATALESS_FLAG) !== 0 || (flags & MACOS_BSD_NODUMP_FLAG) !== 0;
+}
+
+function assertNotCloudPlaceholder(path: string): void {
+  if (isMacosCloudPlaceholder(path)) {
+    throw new Error(
+      `Invalid image node: "${fileName(path)}" appears to be a cloud-on-demand placeholder. ` +
+        'Ensure the file is downloaded locally before adding it as an image.',
+    );
+  }
+}
+
+function readHeaderWithDirectFs(path: string, size: number): Buffer {
+  const length = Math.min(IMAGE_HEADER_BYTES, size);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, 'r');
+  try {
+    const bytesRead = readSync(fd, buffer, 0, length, 0);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+interface ProcessSpawnError {
+  code?: string;
+  signal?: NodeJS.Signals;
+  status?: number;
+}
+
+function isProcessSpawnError(value: unknown): value is ProcessSpawnError {
+  return value !== null && typeof value === 'object';
+}
+
+function readHeaderWithDd(path: string): Buffer {
+  return execFileSync('/bin/dd', [`if=${path}`, `bs=${IMAGE_HEADER_BYTES}`, 'count=1'], {
+    encoding: 'buffer',
+    maxBuffer: IMAGE_HEADER_BYTES,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: IMAGE_HEADER_READ_TIMEOUT_MS,
+  });
+}
+
+function readHeaderWithTimeout(path: string, size: number): Buffer {
+  // Direct fs read is the fast path on every platform — no fork, no shell,
+  // no timeout required because the kernel either returns bytes immediately
+  // or fails synchronously. The `dd` escape hatch only matters for macOS
+  // cloud-on-demand placeholders, which `assertNotCloudPlaceholder` rejected
+  // at the call site, so this path is safe.
+  try {
+    return readHeaderWithDirectFs(path, size);
+  } catch (directError) {
+    // On macOS, fall through to `/bin/dd` so a kernel-level stall on a path
+    // we did not flag as a placeholder (e.g. an unmounted SMB share that
+    // still satisfies `existsSync`) cannot wedge a Bun fiber.
+    if (process.platform !== 'darwin' || !existsSync('/bin/dd')) {
+      throw directError;
+    }
+    try {
+      return readHeaderWithDd(path);
+    } catch (ddError) {
+      const reason = isProcessSpawnError(ddError) ? ddError : null;
+      const timedOut = reason?.signal === 'SIGTERM' || reason?.code === 'ETIMEDOUT';
+      if (timedOut) {
+        throw new Error(
+          `Invalid image node: could not read image header for "${fileName(path)}" within ${IMAGE_HEADER_READ_TIMEOUT_MS}ms. ` +
+            'If this file is stored in OneDrive, iCloud Drive, or another cloud-on-demand provider, download it locally first.',
+        );
+      }
+      const detail = ddError instanceof Error ? ddError.message : String(ddError);
+      throw new Error(
+        `Invalid image node: could not read "${fileName(path)}" — ${detail}.`,
+      );
+    }
+  }
+}
+
+function hasAscii(buffer: Buffer, offset: number, value: string): boolean {
+  return buffer.subarray(offset, offset + value.length).toString('ascii') === value;
+}
+
+function detectImageMimeType(header: Buffer): string | null {
+  if (
+    header.length >= 8 &&
+    header[0] === 0x89 &&
+    hasAscii(header, 1, 'PNG') &&
+    header[4] === 0x0d &&
+    header[5] === 0x0a &&
+    header[6] === 0x1a &&
+    header[7] === 0x0a
+  ) {
+    return 'image/png';
+  }
+
+  if (header.length >= 3 && header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff) {
+    return 'image/jpeg';
+  }
+
+  if (header.length >= 6 && (hasAscii(header, 0, 'GIF87a') || hasAscii(header, 0, 'GIF89a'))) {
+    return 'image/gif';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 0, 'RIFF') && hasAscii(header, 8, 'WEBP')) {
+    return 'image/webp';
+  }
+
+  if (header.length >= 2 && hasAscii(header, 0, 'BM')) {
+    return 'image/bmp';
+  }
+
+  if (
+    header.length >= 4 &&
+    header[0] === 0x00 &&
+    header[1] === 0x00 &&
+    (header[2] === 0x01 || header[2] === 0x02) &&
+    header[3] === 0x00
+  ) {
+    return 'image/x-icon';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 4, 'ftyp')) {
+    const brandArea = header.subarray(8, Math.min(header.length, 32)).toString('ascii');
+    if (brandArea.includes('avif') || brandArea.includes('avis')) return 'image/avif';
+  }
+
+  const text = header.toString('utf8').replace(/^\uFEFF/, '').trimStart().toLowerCase();
+  if (text.startsWith('<svg') || (text.startsWith('<?xml') && text.includes('<svg'))) {
+    return 'image/svg+xml';
+  }
+
+  return null;
+}
+
+export function validateLocalImageFile(path: string): { mimeType: string } {
+  const name = fileName(path);
+  if (!existsSync(path)) {
+    throw new Error(`Invalid image node: "${name}" does not exist.`);
+  }
+
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    throw new Error(`Invalid image node: "${name}" is not a regular file.`);
+  }
+  if (stat.size <= 0) {
+    throw new Error(`Invalid image node: "${name}" is empty.`);
+  }
+
+  const ext = name.split('.').pop()?.toLowerCase() ?? '';
+  if (!IMAGE_MIME_MAP[ext]) {
+    throw new Error(
+      `Invalid image node: "${name}" 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.',
+    );
+  }
+
+  assertNotCloudPlaceholder(path);
+  const header = readHeaderWithTimeout(path, stat.size);
+  const mimeType = detectImageMimeType(header);
+  if (!mimeType) {
+    throw new Error(
+      `Invalid image node: "${name}" is not a recognized image file. ` +
+        'Expected PNG, JPEG, GIF, SVG, WebP, BMP, ICO, or AVIF image bytes.',
+    );
+  }
+
+  return { mimeType };
+}

package/src/server/server.ts

@@ -36,6 +36,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
 import * as marked from 'marked';
 import type {
@@ -67,6 +68,7 @@ import { diffLayouts, formatDiff, mutationHistory } from './mutation-history.js'
 import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   addCanvasEdge,
@@ -1091,7 +1093,7 @@ async function handleCanvasViewport(req: Request): Promise<Response> {
 }
 
 // ── Serve image file for image nodes ─────────────────────────
-function handleCanvasImage(pathname: string): Response {
+async function handleCanvasImage(pathname: string): Promise<Response> {
   const nodeId = pathname.replace('/api/canvas/image/', '');
   const node = canvasState.getNode(nodeId);
   if (!node || node.type !== 'image') {
@@ -1105,9 +1107,13 @@ function handleCanvasImage(pathname: string): Response {
   if (!existsSync(safePath)) {
     return responseText('Image file not found', 404);
   }
-  const ext = safePath.split('.').pop()?.toLowerCase() ?? '';
-  const contentType = IMAGE_MIME_MAP[ext] || 'application/octet-stream';
-  const data = readFileSync(safePath);
+  let contentType: string;
+  try {
+    contentType = validateLocalImageFile(safePath).mimeType;
+  } catch (error) {
+    return responseText(error instanceof Error ? error.message : 'Invalid image file', 400);
+  }
+  const data = await readFile(safePath);
   return new Response(data, {
     headers: {
       'Content-Type': contentType,
@@ -1495,6 +1501,12 @@ async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
       bytes: result.fileSize,
       projectPath: result.projectPath,
       openedInCanvas: result.openedInCanvas,
+      // `id` is the canvas node id alias used by every other add-style
+      // response. It is only present when a canvas node was actually
+      // created (i.e. openInCanvas was not explicitly disabled). When
+      // there is no canvas node, the alias is intentionally omitted so
+      // consumers can `'id' in response` to detect the build-only case.
+      ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
       nodeId: result.nodeId,
       url: result.url,
       metadata: result.metadata,
@@ -3773,7 +3785,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           }
 
           if (url.pathname.startsWith('/api/canvas/image/') && req.method === 'GET') {
-            return handleCanvasImage(url.pathname);
+            return await handleCanvasImage(url.pathname);
           }
 
           if (url.pathname === '/api/canvas/edge' && req.method === 'POST') {