pmx-canvas 0.1.1 → 0.1.3

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'),
@@ -347,6 +348,7 @@ export async function startMcpServer(): Promise<void> {
       mainTsx: z.string().optional().describe('Optional contents for src/main.tsx'),
       indexHtml: z.string().optional().describe('Optional contents for index.html'),
       files: z.record(z.string(), z.string()).optional().describe('Optional map of additional project-relative file paths to file contents'),
+      deps: z.array(z.string()).optional().describe('Optional npm dependencies to install before bundling (e.g. ["recharts", "framer-motion@^11"]). Validated against npm-name format; flags and shell metacharacters are rejected.'),
       projectPath: z.string().optional().describe('Optional workspace-relative reusable project path. Defaults to .pmx-canvas/artifacts/.web-artifacts/<slug>'),
       outputPath: z.string().optional().describe('Optional workspace-relative HTML output path. Defaults to .pmx-canvas/artifacts/<slug>.html'),
       openInCanvas: z.boolean().optional().describe('Open the generated artifact in canvas after build (default true)'),
@@ -365,6 +367,7 @@ export async function startMcpServer(): Promise<void> {
           ...(typeof input.mainTsx === 'string' ? { mainTsx: input.mainTsx } : {}),
           ...(typeof input.indexHtml === 'string' ? { indexHtml: input.indexHtml } : {}),
           ...(input.files ? { files: input.files } : {}),
+          ...(Array.isArray(input.deps) ? { deps: input.deps } : {}),
           ...(typeof input.projectPath === 'string'
             ? { projectPath: safeWorkspacePath(input.projectPath) }
             : {}),
@@ -671,13 +674,34 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_focus_node ──────────────────────────────────────────
   server.tool(
     'canvas_focus_node',
-    'Pan the viewport to center on a specific node.',
-    { id: z.string().describe('Node ID to focus on') },
-    async ({ id }) => {
+    'Bring a node into focus. By default the viewport pans so the node is centered. Pass noPan=true to raise/select the node without moving the human\'s camera (useful when reacting to background events without disrupting the human\'s current view).',
+    {
+      id: z.string().describe('Node ID to focus on'),
+      noPan: z
+        .boolean()
+        .optional()
+        .describe('If true, raise/select the node without panning the viewport. Default false.'),
+    },
+    async ({ id, noPan }) => {
       const c = await ensureCanvas();
-      c.focusNode(id);
+      const result = c.focusNode(id, { ...(noPan === true ? { noPan: true } : {}) });
+      if (!result) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ ok: false, error: `Node "${id}" not found.` }),
+            },
+          ],
+        };
+      }
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ok: true, focused: id }) }],
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, focused: result.focused, panned: result.panned }),
+          },
+        ],
       };
     },
   );
@@ -1158,6 +1182,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

@@ -36,6 +36,7 @@ import {
   getWebpageFetchErrorDetails,
   normalizeWebpageUrl,
 } from './webpage-node.js';
+import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId, isExcalidrawCreateView } from './diagram-presets.js';
 
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
@@ -82,6 +83,29 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function getStoredExcalidrawCheckpointId(node: CanvasNodeState): string | null {
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  const checkpointId = appCheckpoint?.id;
+  return typeof checkpointId === 'string' && checkpointId.trim().length > 0 ? checkpointId.trim() : null;
+}
+
+function resolveExtAppRehydratedToolInput(
+  node: CanvasNodeState,
+  openedToolInput: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!isExcalidrawCreateView(node.data.serverName, node.data.toolName)) return openedToolInput;
+  const checkpointId = getStoredExcalidrawCheckpointId(node);
+  if (!checkpointId) return openedToolInput;
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  return {
+    ...openedToolInput,
+    elements: buildExcalidrawRestoreCheckpointToolInput(
+      checkpointId,
+      typeof appCheckpoint?.data === 'string' ? appCheckpoint.data : undefined,
+    ),
+  };
+}
+
 function isExtAppNode(node: CanvasNodeState | undefined): node is CanvasNodeState {
   return node?.type === 'mcp-app' && node.data.mode === 'ext-app';
 }
@@ -280,13 +304,18 @@ export async function syncCanvasRuntimeBackends(
           ? { serverName: current.data.serverName.trim() }
           : {}),
       });
+      const toolInput = resolveExtAppRehydratedToolInput(current, opened.toolInput);
+      const storedCheckpointId = getStoredExcalidrawCheckpointId(current);
+      const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
+        ? ensureExcalidrawCheckpointId(opened.toolResult, nodeId, storedCheckpointId)
+        : opened.toolResult;
 
       canvasState.withSuppressedRecording(() => {
         setExtAppRuntimeState(nodeId, {
           appSessionId: opened.sessionId,
           html: opened.html,
-          toolInput: opened.toolInput,
-          toolResult: opened.toolResult,
+          toolInput,
+          toolResult,
           resourceUri: opened.resourceUri,
           toolDefinition: opened.tool,
           resourceMeta: opened.resourceMeta,
@@ -392,17 +421,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,
     };
   }
 
@@ -685,7 +733,7 @@ function collectArrangeExcludedNodeIds(nodes: CanvasNodeState[]): Set<string> {
   const excluded = new Set<string>();
   for (const node of nodes) {
     const parentGroup = typeof node.data.parentGroup === 'string' ? node.data.parentGroup : null;
-    if (isArrangeLocked(node) || (parentGroup && excludedGroupIds.has(parentGroup))) {
+    if (parentGroup || isArrangeLocked(node)) {
       excluded.add(node.id);
     }
   }
@@ -728,12 +776,13 @@ export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: numbe
       return;
     }
 
-    const cols = Math.max(1, Math.floor(1440 / (360 + gap)));
+    const maxNodeWidth = movableNodes.reduce((max, node) => Math.max(max, node.size.width), 360);
+    const cols = Math.max(1, Math.floor(1440 / (maxNodeWidth + gap)));
     let col = 0;
     let rowY = 80;
     let rowMaxHeight = 0;
     for (const node of movableNodes) {
-      const x = 40 + col * (360 + gap);
+      const x = 40 + col * (maxNodeWidth + gap);
       canvasState.updateNode(node.id, { position: { x, y: rowY } });
       rowMaxHeight = Math.max(rowMaxHeight, node.size.height);
       col++;

package/src/server/canvas-schema.ts

@@ -283,7 +283,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
         required: true,
         description: 'Chart type. Aliases like "stack" and "combo" are normalized server-side.',
       },
-      { name: 'data', type: 'Record<string, unknown>[]', required: true, description: 'Chart dataset.' },
+      { name: 'data', type: 'Record<string, unknown>[]', required: true, description: 'Chart dataset.', aliases: ['data-json'] },
       { name: 'title', type: 'string', required: false, description: 'Optional graph title.' },
       { name: 'xKey', type: 'string', required: false, description: 'X-axis/category key for line, bar, area, scatter, stacked-bar, and composed charts.' },
       { name: 'yKey', type: 'string', required: false, description: 'Y-axis value key for line, bar, area, and scatter charts. Also used as a fallback bar key for composed charts.' },
@@ -334,6 +334,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'outputPath', type: 'string', required: false, description: 'Optional output HTML path.' },
       { name: 'openInCanvas', type: 'boolean', required: false, description: 'Open the built artifact on the canvas (default true).' },
       { name: 'includeLogs', type: 'boolean', required: false, description: 'Include raw build stdout/stderr in the response (default false).' },
+      { name: 'deps', type: 'string[]', required: false, description: 'Optional npm dependencies to add before bundling, e.g. recharts.', aliases: ['deps'] },
     ],
     example: {
       title: 'Dashboard Artifact',

package/src/server/diagram-presets.ts

@@ -1,8 +1,40 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 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_SAVE_CHECKPOINT_TOOL = 'save_checkpoint';
+export const EXCALIDRAW_READ_CHECKPOINT_TOOL = 'read_checkpoint';
+const EXCALIDRAW_CAMERA_PADDING = 80;
+const EXCALIDRAW_MIN_CAMERA_WIDTH = 320;
+const EXCALIDRAW_MIN_CAMERA_HEIGHT = 240;
+const EXCALIDRAW_CAMERA_ASPECT_RATIO = 4 / 3;
+const EXCALIDRAW_CAMERA_SIZES = [
+  { width: 400, height: 300 },
+  { width: 600, height: 450 },
+  { width: 800, height: 600 },
+  { width: 1200, height: 900 },
+  { width: 1600, height: 1200 },
+];
+
+export const DEFAULT_EXCALIDRAW_ELEMENTS: ReadonlyArray<Record<string, unknown>> = [
+  {
+    type: 'rectangle',
+    id: 'pmx-start',
+    x: 80,
+    y: 80,
+    width: 280,
+    height: 120,
+    roundness: { type: 3 },
+    backgroundColor: '#a5d8ff',
+    fillStyle: 'solid',
+    label: {
+      text: 'PMX Canvas',
+      fontSize: 24,
+    },
+  },
+];
 
 export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
   type: 'http',
@@ -30,7 +62,11 @@ export interface ExcalidrawOpenMcpAppInput {
   height?: number;
 }
 
-export function normalizeExcalidrawElements(elements: unknown): string {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseExcalidrawElements(elements: unknown): Array<Record<string, unknown>> {
   if (typeof elements === 'string') {
     const trimmed = elements.trim();
     if (!trimmed) {
@@ -46,16 +82,195 @@ export function normalizeExcalidrawElements(elements: unknown): string {
     if (!Array.isArray(parsed)) {
       throw new Error('diagram.elements string must encode a JSON array.');
     }
-    return JSON.stringify(parsed);
+    return parsed.filter(isRecord);
   }
+
   if (Array.isArray(elements)) {
-    return JSON.stringify(elements);
+    return elements.filter(isRecord);
   }
+
   throw new Error('diagram.elements must be a JSON array string or an array of Excalidraw elements.');
 }
 
+function parseExcalidrawCheckpointElements(data: unknown): Array<Record<string, unknown>> | null {
+  let parsed: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+
+  if (Array.isArray(parsed)) return parsed.filter(isRecord);
+  if (isRecord(parsed) && Array.isArray(parsed.elements)) return parsed.elements.filter(isRecord);
+  return null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boolean {
+  return elements.some((element) => element.type === 'cameraUpdate');
+}
+
+function resolveExcalidrawCameraSize(width: number, height: number): { width: number; height: number } {
+  const requiredWidth = Math.max(EXCALIDRAW_MIN_CAMERA_WIDTH, width);
+  const requiredHeight = Math.max(EXCALIDRAW_MIN_CAMERA_HEIGHT, height);
+  const standard = EXCALIDRAW_CAMERA_SIZES.find(
+    (size) => size.width >= requiredWidth && size.height >= requiredHeight,
+  );
+  if (standard) return standard;
+
+  const heightFromWidth = requiredWidth / EXCALIDRAW_CAMERA_ASPECT_RATIO;
+  const widthFromHeight = requiredHeight * EXCALIDRAW_CAMERA_ASPECT_RATIO;
+  const cameraWidth = Math.ceil(Math.max(requiredWidth, widthFromHeight));
+  return {
+    width: cameraWidth,
+    height: Math.ceil(cameraWidth / EXCALIDRAW_CAMERA_ASPECT_RATIO),
+  };
+}
+
+export function inferExcalidrawCameraUpdate(
+  elements: Array<Record<string, unknown>>,
+): Record<string, unknown> | null {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+
+  const includePoint = (x: number, y: number) => {
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x);
+    maxY = Math.max(maxY, y);
+  };
+
+  for (const element of elements) {
+    if (element.isDeleted === true || element.type === 'cameraUpdate' || element.type === 'restoreCheckpoint' || element.type === 'delete') {
+      continue;
+    }
+
+    const x = finiteNumber(element.x);
+    const y = finiteNumber(element.y);
+    if (x === null || y === null) continue;
+
+    includePoint(x, y);
+    const width = finiteNumber(element.width) ?? 0;
+    const height = finiteNumber(element.height) ?? 0;
+    includePoint(x + width, y + height);
+
+    if (Array.isArray(element.points)) {
+      for (const point of element.points) {
+        if (!Array.isArray(point)) continue;
+        const pointX = finiteNumber(point[0]);
+        const pointY = finiteNumber(point[1]);
+        if (pointX === null || pointY === null) continue;
+        includePoint(x + pointX, y + pointY);
+      }
+    }
+  }
+
+  if (!Number.isFinite(minX) || !Number.isFinite(minY) || !Number.isFinite(maxX) || !Number.isFinite(maxY)) {
+    return null;
+  }
+
+  const contentWidth = Math.max(1, maxX - minX);
+  const contentHeight = Math.max(1, maxY - minY);
+  const padding = Math.max(
+    EXCALIDRAW_CAMERA_PADDING,
+    Math.round(Math.max(contentWidth, contentHeight) * 0.18),
+  );
+  const camera = resolveExcalidrawCameraSize(contentWidth + padding * 2, contentHeight + padding * 2);
+  const centerX = minX + contentWidth / 2;
+  const centerY = minY + contentHeight / 2;
+
+  return {
+    type: 'cameraUpdate',
+    x: Math.round(centerX - camera.width / 2),
+    y: Math.round(centerY - camera.height / 2),
+    width: camera.width,
+    height: camera.height,
+  };
+}
+
+function withInferredCameraUpdate(
+  elements: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  if (elementHasCameraUpdate(elements)) return elements;
+  const camera = inferExcalidrawCameraUpdate(elements);
+  return camera ? [camera, ...elements] : elements;
+}
+
+export function normalizeExcalidrawElements(elements: unknown): string {
+  const parsed = parseExcalidrawElements(elements);
+  return JSON.stringify(parsed.length > 0 ? parsed : DEFAULT_EXCALIDRAW_ELEMENTS);
+}
+
+export function normalizeExcalidrawElementsForToolInput(elements: unknown): string {
+  const parsed = parseExcalidrawElements(elements);
+  const seeded = parsed.length > 0 ? parsed : [...DEFAULT_EXCALIDRAW_ELEMENTS];
+  return JSON.stringify(withInferredCameraUpdate(seeded));
+}
+
+export function normalizeExcalidrawCheckpointDataForToolInput(data: unknown): string | null {
+  const elements = parseExcalidrawCheckpointElements(data);
+
+  return elements ? JSON.stringify(withInferredCameraUpdate(elements)) : null;
+}
+
+export function buildExcalidrawRestoreCheckpointToolInput(checkpointId: string, data?: unknown): string {
+  const elements = parseExcalidrawCheckpointElements(data);
+  const camera = elements ? inferExcalidrawCameraUpdate(elements) : null;
+  return JSON.stringify([
+    { type: 'restoreCheckpoint', id: checkpointId },
+    ...(camera ? [camera] : []),
+  ]);
+}
+
+export function isExcalidrawCreateView(serverName: unknown, toolName: unknown): boolean {
+  return serverName === EXCALIDRAW_SERVER_NAME && toolName === EXCALIDRAW_CREATE_VIEW_TOOL;
+}
+
+export function buildExcalidrawCheckpointId(seed: string): string {
+  const safe = seed.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 96);
+  return `pmx-${safe || 'checkpoint'}`;
+}
+
+export function getExcalidrawCheckpointIdFromToolResult(result: unknown): string | null {
+  if (!isRecord(result) || !isRecord(result.structuredContent)) return null;
+  const checkpointId = result.structuredContent.checkpointId;
+  return typeof checkpointId === 'string' && checkpointId.trim().length > 0 ? checkpointId.trim() : null;
+}
+
+export function withExcalidrawCheckpointId(
+  result: CallToolResult,
+  checkpointId: string,
+): CallToolResult {
+  const structuredContent = isRecord(result.structuredContent) ? result.structuredContent : {};
+  return {
+    ...result,
+    structuredContent: {
+      ...structuredContent,
+      checkpointId,
+    },
+  };
+}
+
+export function ensureExcalidrawCheckpointId(
+  result: CallToolResult,
+  seed: string,
+  checkpointId?: string | null,
+): CallToolResult {
+  return withExcalidrawCheckpointId(
+    result,
+    checkpointId ?? getExcalidrawCheckpointIdFromToolResult(result) ?? buildExcalidrawCheckpointId(seed),
+  );
+}
+
 export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput {
-  const elements = normalizeExcalidrawElements(input.elements);
+  const elements = normalizeExcalidrawElementsForToolInput(input.elements);
   const out: ExcalidrawOpenMcpAppInput = {
     transport: EXCALIDRAW_MCP_TRANSPORT,
     toolName: EXCALIDRAW_CREATE_VIEW_TOOL,