pmx-canvas 0.1.1 → 0.1.3

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

@@ -4,6 +4,9 @@ import type { CanvasNodeState } from '../types';
 type IframeLoadTarget = Pick<HTMLIFrameElement, 'addEventListener' | 'removeEventListener' | 'contentDocument'>;
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+interface ExtAppHostDimensionsTarget {
+    getBoundingClientRect(): Pick<DOMRectReadOnly, 'width' | 'height'>;
+}
 export declare function waitForExtAppFrameLoad(target: IframeLoadTarget): Promise<void>;
 export declare function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string;
 export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMode, isExpanded: boolean): {
@@ -12,7 +15,16 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
     shouldCollapse: boolean;
 };
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
+export declare function resolveExtAppSandbox(value: unknown): string;
+export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+};
+export declare function shouldApplyExtAppSizeChange(height: unknown, isExpanded: boolean): height is number;
 export declare function ExtAppFrame({ node }: {
     node: CanvasNodeState;
-}): import("preact/src").JSX.Element;
+}): import("preact/jsx-runtime").JSX.Element;
 export {};

package/dist/types/client/state/canvas-store.d.ts

@@ -1,4 +1,4 @@
-import type { CanvasEdge, CanvasLayout, CanvasNodeState, ConnectionStatus, ViewportState } from '../types';
+import { type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
 export declare const viewport: import("@preact/signals-core").Signal<ViewportState>;
 export declare const nodes: import("@preact/signals-core").Signal<Map<string, CanvasNodeState>>;
 export declare const edges: import("@preact/signals-core").Signal<Map<string, CanvasEdge>>;
@@ -9,6 +9,7 @@ export declare const traceEnabled: import("@preact/signals-core").Signal<boolean
 export declare const canvasTheme: import("@preact/signals-core").Signal<string>;
 export declare const hasInitialServerLayout: import("@preact/signals-core").Signal<boolean>;
 export declare const expandedNodeId: import("@preact/signals-core").Signal<string | null>;
+export declare const pendingExpandedNodeCloseId: import("@preact/signals-core").Signal<string | null>;
 export declare const pendingConnection: import("@preact/signals-core").Signal<{
     from: string;
 } | null>;

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

@@ -33,6 +33,9 @@ export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 export declare const TYPE_LABELS: Record<CanvasNodeState['type'], string>;
 /** Node types that support the full-viewport expand/focus overlay. */
 export declare const EXPANDABLE_TYPES: Set<"markdown" | "mcp-app" | "webpage" | "json-render" | "graph" | "prompt" | "response" | "status" | "context" | "ledger" | "trace" | "file" | "image" | "group">;
+export declare const EXCALIDRAW_SERVER_NAME = "Excalidraw";
+export declare const EXCALIDRAW_CREATE_VIEW_TOOL = "create_view";
+export declare function isExcalidrawNode(node: CanvasNodeState): boolean;
 export interface CanvasLayout {
     viewport: ViewportState;
     nodes: CanvasNodeState[];

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/server/diagram-presets.d.ts

@@ -1,7 +1,11 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 export declare const EXCALIDRAW_MCP_URL = "https://mcp.excalidraw.com/mcp";
 export declare const EXCALIDRAW_SERVER_NAME = "Excalidraw";
 export declare const EXCALIDRAW_CREATE_VIEW_TOOL = "create_view";
+export declare const EXCALIDRAW_SAVE_CHECKPOINT_TOOL = "save_checkpoint";
+export declare const EXCALIDRAW_READ_CHECKPOINT_TOOL = "read_checkpoint";
+export declare const DEFAULT_EXCALIDRAW_ELEMENTS: ReadonlyArray<Record<string, unknown>>;
 export declare const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig;
 export interface DiagramPresetOpenInput {
     elements: unknown;
@@ -24,5 +28,14 @@ export interface ExcalidrawOpenMcpAppInput {
     width?: number;
     height?: number;
 }
+export declare function inferExcalidrawCameraUpdate(elements: Array<Record<string, unknown>>): Record<string, unknown> | null;
 export declare function normalizeExcalidrawElements(elements: unknown): string;
+export declare function normalizeExcalidrawElementsForToolInput(elements: unknown): string;
+export declare function normalizeExcalidrawCheckpointDataForToolInput(data: unknown): string | null;
+export declare function buildExcalidrawRestoreCheckpointToolInput(checkpointId: string, data?: unknown): string;
+export declare function isExcalidrawCreateView(serverName: unknown, toolName: unknown): boolean;
+export declare function buildExcalidrawCheckpointId(seed: string): string;
+export declare function getExcalidrawCheckpointIdFromToolResult(result: unknown): string | null;
+export declare function withExcalidrawCheckpointId(result: CallToolResult, checkpointId: string): CallToolResult;
+export declare function ensureExcalidrawCheckpointId(result: CallToolResult, seed: string, checkpointId?: string | null): CallToolResult;
 export declare function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput;

package/dist/types/server/index.d.ts

@@ -83,7 +83,12 @@ export declare class PmxCanvas extends EventEmitter {
     ungroupNodes(groupId: string): boolean;
     clear(): void;
     arrange(layout?: 'grid' | 'column' | 'flow'): void;
-    focusNode(id: string): void;
+    focusNode(id: string, options?: {
+        noPan?: boolean;
+    }): {
+        focused: string;
+        panned: boolean;
+    } | null;
     getLayout(): CanvasLayout;
     getNode(id: string): CanvasNodeState | undefined;
     search(query: string): ReturnType<typeof searchNodes>;

package/dist/types/server/web-artifacts.d.ts

@@ -9,6 +9,7 @@ export interface WebArtifactBuildInput {
     outputPath?: string;
     initScriptPath?: string;
     bundleScriptPath?: string;
+    deps?: string[];
     timeoutMs?: number;
 }
 export interface WebArtifactBuildOutput {

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.3",
   "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",
@@ -44,6 +44,7 @@
     "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun x playwright test",
     "test:e2e": "bun run test:web-canvas",
+    "test:e2e-cli": "bash scripts/e2e-cli-coverage.sh",
     "test:web-canvas:headed": "bun run build && bun x playwright test --headed",
     "test:e2e:headed": "bun run test:web-canvas:headed",
     "test:all": "bun run test && bun run test:web-canvas",

package/skills/pmx-canvas/SKILL.md

@@ -10,7 +10,7 @@ description: >
   working memory — pin nodes to curate context, read spatial arrangement to understand intent.
 ---
 
-# PMX Canvas — Agent Skill
+# PMX Canvas - Agent Skill
 
 PMX Canvas is a spatial canvas workbench you control through MCP tools or HTTP API. It renders an
 infinite 2D canvas in the browser with nodes, edges, groups, pan/zoom, and a minimap. State lives
@@ -33,6 +33,10 @@ relatedness, clusters imply grouping, reading order (top-left to bottom-right) i
 
 ## Starting the Canvas
 
+If this skill is installed before the `pmx-canvas` command exists, install the project first. See
+`references/installing-pmx-canvas.md` for local development, npm/global install, and MCP config
+options.
+
 The canvas auto-starts on first MCP tool call when running in MCP mode (`pmx-canvas --mcp`).
 For manual start:
 
@@ -81,6 +85,8 @@ pmx-canvas status                          # Quick summary
 pmx-canvas node add --type markdown --title "Plan"
 pmx-canvas node add --type webpage --url https://example.com/docs
 pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
+pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas external-app add --kind excalidraw --title "Diagram"
 pmx-canvas node add --help --type webpage --json
 pmx-canvas node schema --type json-render --component Table --summary
 pmx-canvas node list --type file --ids
@@ -88,8 +94,9 @@ pmx-canvas edge add --from node-a --to node-b --type depends-on
 pmx-canvas search "auth"
 pmx-canvas open
 pmx-canvas arrange --layout flow
+pmx-canvas focus <node-id> --no-pan             # Select/raise without moving the user's viewport
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
-pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --include-logs
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
 pmx-canvas pin --list
 pmx-canvas snapshot save --name "before-refactor"
 pmx-canvas code-graph
@@ -103,7 +110,8 @@ pmx-canvas spatial
 - `edge add|list|remove` — manage edges
 - Search-based edge selectors must be specific enough to resolve exactly one node. Queries like
   `"DVT O3"` can be ambiguous; prefer the full visible title such as `"DVT O3 — GitOps"`.
-- `search`, `layout`, `status`, `arrange`, `focus` — inspect and navigate the canvas
+- `search`, `layout`, `status`, `arrange`, `focus` — inspect and navigate the canvas. Prefer
+  `focus --no-pan` when you only need to select/raise a node without hijacking the human's camera.
 - `open` — open the current workbench in the browser
 - `pin --list|--clear|<ids...>` — manage context pins
 - `undo`, `redo`, `history` — time travel
@@ -124,6 +132,9 @@ Current caveat:
   diagram/app flow gives you a session-oriented result first, resolve the final canvas node from
   live layout or `node list --type mcp-app` before you try to group it, wire edges to it, or
   revisit it later.
+- Generic `pmx-canvas node add --type mcp-app` is intentionally not supported because app nodes
+  need app/session metadata. Use `pmx-canvas web-artifact build` for bundled React artifacts or
+  `pmx-canvas external-app add --kind excalidraw` for the Excalidraw preset.
 
 The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_URL` or
 `PMX_CANVAS_PORT` when the canvas is running elsewhere.
@@ -141,7 +152,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | `context` | Context card | Key context the human should see |
 | `ledger` | Log/ledger viewer | Structured log data, audit trails |
 | `trace` | Trace/timeline viewer | Execution traces, timelines |
-| `mcp-app` | Hosted app/embed frame | Embedded MCP apps or external app content |
+| `mcp-app` | Hosted app/embed frame | Tool-backed MCP apps or external app content; not generic CLI-created notes |
 | `json-render` | Native structured UI panel | Dashboards, forms, tables, interactive layouts from json-render specs |
 | `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts rendered inside the canvas |
 | `group` | Spatial container/frame | Visually group related nodes together |
@@ -267,6 +278,8 @@ Use color consistently to convey meaning:
 **`canvas_focus_node`** — Pan viewport to center on a specific node
 - `id` (required): node to focus
 - Good for drawing the human's attention
+- Avoid focusing every node in a batch. Focus only the final result or use CLI `focus --no-pan`
+  when the goal is selection/raising without camera movement.
 
 ### Groups
 
@@ -360,6 +373,9 @@ Current product caveats for grouped comparison boards:
   text). Can also be a JSON-array string.
 - Optional: `title`, `x`, `y`, `width`, `height`
 - The diagram opens inside an `mcp-app` node with fullscreen editing and draw-on animations
+- CLI equivalent: `pmx-canvas external-app add --kind excalidraw --title "Diagram"`
+- Edits made in expanded/fullscreen mode are persisted back into the node model context and replayed
+  when the app iframe remounts.
 - Use this when the human needs a quick sketch, architecture diagram, or flowchart and a
   geometric `graph` node would feel too rigid
 - Prefer labeled shapes (`"label": { "text": "..." }` on rectangle/ellipse/diamond) over
@@ -380,9 +396,12 @@ server's `ui://` resource as an iframe node on the canvas
 
 **`canvas_build_web_artifact`** — Build a single-file HTML artifact from React/Tailwind source
 - Required: `title`, `appTsx`
-- Optional: `indexCss`, `mainTsx`, `indexHtml`, extra `files`, `projectPath`, `outputPath`, `includeLogs`
+- Optional: `indexCss`, `mainTsx`, `indexHtml`, extra `files`, `projectPath`, `outputPath`, `deps`, `includeLogs`
 - By default it opens the result on the canvas as an embedded app node
 - By default it returns compact log summaries; set `includeLogs: true` when you need raw stdout/stderr
+- `recharts` is available in the scaffold. For additional libraries, pass CLI `--deps name,name2`
+  or MCP/API `deps: ["name"]` before bundling.
+- Failed or empty CLI bundles print `ok: false`, exit non-zero, and do not create a canvas node.
 - Use this when the output should be a richer interactive UI than a simple markdown/file/image node
 - Prefer the dedicated `web-artifacts-builder` skill when you need the full React + shadcn workflow
 - Use the `playwright-cli` skill when you need to validate the built artifact in a live browser
@@ -451,6 +470,8 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | GET | `/api/canvas/schema` | Get running-server create schemas, examples, and json-render catalog metadata |
 | POST | `/api/canvas/schema/validate` | Validate a json-render spec or graph payload without creating a node |
 | GET | `/api/canvas/json-render/view?nodeId=...` | View a native json-render or graph node |
+| POST | `/api/canvas/diagram` | Create an Excalidraw external app node |
+| POST | `/api/canvas/mcp-app/open` | Open a tool-backed MCP app node |
 | POST | `/api/canvas/web-artifact` | Build a bundled web artifact and optionally open it on canvas |
 | POST | `/api/canvas/group` | Create group |
 | POST | `/api/canvas/group/add` | Add nodes to group |

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -0,0 +1,66 @@
+# Installing PMX Canvas
+
+Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas` command is not available yet.
+
+## From npm
+
+```bash
+npm install -g pmx-canvas
+pmx-canvas serve --daemon --no-open --wait-ms=20000
+pmx-canvas open
+```
+
+## From a local checkout
+
+```bash
+git clone https://github.com/pskoett/pmx-canvas.git
+cd pmx-canvas
+bun install
+bun run build
+bun run src/cli/index.ts serve --daemon --no-open --wait-ms=20000
+```
+
+For development, run commands through Bun from the checkout:
+
+```bash
+bun run src/cli/index.ts status
+bun run src/cli/index.ts node add --type markdown --title "Hello" --content "# PMX"
+```
+
+## MCP Config
+
+For agents that support MCP, configure PMX Canvas as a stdio MCP server:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"]
+    }
+  }
+}
+```
+
+If you are using a local checkout instead of the published package, point the command at the CLI entry:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bun",
+      "args": ["run", "/path/to/pmx-canvas/src/cli/index.ts", "--mcp"]
+    }
+  }
+}
+```
+
+## Verify
+
+```bash
+pmx-canvas --version
+pmx-canvas serve status
+pmx-canvas layout
+```
+
+The CLI defaults to `http://localhost:4313`. Override with `PMX_CANVAS_URL` or `PMX_CANVAS_PORT` if the server runs elsewhere.

package/skills/web-artifacts-builder/scripts/bundle-artifact.sh

@@ -152,10 +152,20 @@ rm -rf dist bundle.html
 echo "🔨 Building with Parcel..."
 run_with_filtered_stderr run_local_binary parcel build index.html --dist-dir dist --no-source-maps --log-level error
 
+if [ ! -s "dist/index.html" ]; then
+  echo "❌ Error: Parcel did not produce dist/index.html" >&2
+  exit 1
+fi
+
 # Inline everything into single HTML
 echo "🎯 Inlining all assets into single HTML file..."
 run_with_filtered_stderr run_local_binary html-inline dist/index.html > bundle.html
 
+if [ ! -s "bundle.html" ]; then
+  echo "❌ Error: Bundled artifact is empty" >&2
+  exit 1
+fi
+
 # Get file size
 FILE_SIZE=$(du -h bundle.html | cut -f1)
 

package/skills/web-artifacts-builder/scripts/init-artifact.sh

@@ -172,7 +172,7 @@ fi
 
 echo "📦 Installing Tailwind CSS and dependencies..."
 run_pnpm_allow_build add -D tailwindcss@3.4.1 postcss @types/node tailwindcss-animate parcel @parcel/config-default parcel-resolver-tspaths html-inline
-run_pnpm_quiet add class-variance-authority clsx tailwind-merge lucide-react next-themes
+run_pnpm_quiet add class-variance-authority clsx tailwind-merge lucide-react next-themes recharts
 
 echo "⚙️  Creating Tailwind and PostCSS configuration..."
 cat > .postcssrc.json << 'EOF'

package/src/cli/agent.ts

@@ -13,6 +13,7 @@
 
 import { readFileSync, writeFileSync } from 'node:fs';
 import { openUrlInExternalBrowser } from '../server/server.js';
+import { DEFAULT_EXCALIDRAW_ELEMENTS } from '../server/diagram-presets.js';
 import {
   ALL_SEMANTIC_WATCH_EVENT_TYPES,
   formatCompactWatchEvent,
@@ -24,6 +25,7 @@ import {
 // ── Helpers ──────────────────────────────────────────────────
 
 const DEFAULT_PORT = 4313;
+const defaultConsoleLog = console.log;
 
 interface CanvasSchemaField {
   name: string;
@@ -91,13 +93,19 @@ function die(message: string, hint?: string): never {
 }
 
 function output(data: unknown): void {
-  console.log(JSON.stringify(data, null, 2));
+  const text = JSON.stringify(data, null, 2);
+  if (console.log !== defaultConsoleLog) {
+    console.log(text);
+    return;
+  }
+  process.stdout.write(`${text}\n`);
 }
 
 async function api(
   method: string,
   path: string,
   body?: Record<string, unknown>,
+  options?: { allowErrorJson?: boolean },
 ): Promise<unknown> {
   const base = getBaseUrl();
   const url = `${base}${path}`;
@@ -128,6 +136,7 @@ async function api(
   }
 
   if (!res.ok) {
+    if (options?.allowErrorJson) return json;
     const err = json as Record<string, unknown>;
     die(
       err.error ? String(err.error) : `HTTP ${res.status}`,
@@ -146,7 +155,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   const BOOL_FLAGS = new Set([
     'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run',
     'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact', 'summary',
-    'verbose', 'include-logs',
+    'verbose', 'include-logs', 'no-pan',
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -532,11 +541,11 @@ async function buildGraphRequestBody(
     'Use: pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value';
   const rawData = await readTextInput(flags, {
     fileFlags: ['data-file'],
-    valueFlags: ['data-json'],
+    valueFlags: ['data-json', 'data'],
     allowStdin: true,
     label: 'graph JSON dataset',
     hint,
-    requiredMessage: 'Graph nodes require --data-file, --data-json, or --stdin JSON data.',
+    requiredMessage: 'Graph nodes require --data-file, --data-json, --data, or --stdin JSON data.',
   });
   const data = parseRecordArrayJson(rawData, hint);
 
@@ -621,6 +630,8 @@ async function buildWebArtifactRequestBody(
   if (typeof flags['output-path'] === 'string') body.outputPath = flags['output-path'];
   if (typeof flags['init-script-path'] === 'string') body.initScriptPath = flags['init-script-path'];
   if (typeof flags['bundle-script-path'] === 'string') body.bundleScriptPath = flags['bundle-script-path'];
+  const deps = parseStringListFlag(flags, 'deps', 'Use a comma-separated list, e.g. --deps recharts,zod');
+  if (deps) body.deps = deps;
   if (flags['no-open-in-canvas']) body.openInCanvas = false;
   if (flags.verbose || flags['include-logs']) body.includeLogs = true;
 
@@ -631,8 +642,11 @@ async function buildWebArtifactRequestBody(
 }
 
 async function runWebArtifactBuildCommand(flags: Record<string, string | true>): Promise<void> {
-  const result = await api('POST', '/api/canvas/web-artifact', await buildWebArtifactRequestBody(flags));
+  const result = await api('POST', '/api/canvas/web-artifact', await buildWebArtifactRequestBody(flags), { allowErrorJson: true });
   output(result);
+  if (isRecord(result) && result.ok === false) {
+    process.exit(1);
+  }
 }
 
 async function loadCanvasSchema(): Promise<CanvasSchemaResponse> {
@@ -915,6 +929,13 @@ cmd('node add', 'Add a node to the canvas', [
     return;
   }
 
+  if (type === 'mcp-app') {
+    die(
+      'mcp-app nodes require tool-backed app metadata and cannot be created with generic node add.',
+      'Use: pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx, or pmx-canvas external-app add --kind excalidraw --title "Diagram"',
+    );
+  }
+
   const body: Record<string, unknown> = { type };
   if (flags.title) body.title = flags.title;
   const webpageUrl = getStringFlag(flags, 'url');
@@ -1269,7 +1290,10 @@ cmd('status', 'Quick canvas summary', [
 
   const typeCounts: Record<string, number> = {};
   for (const n of layout.nodes) {
-    const t = n.type as string;
+    const data = isRecord(n.data) ? n.data : {};
+    const t = n.type === 'mcp-app' && data.hostMode === 'hosted' && typeof data.path === 'string'
+      ? 'web-artifact'
+      : n.type as string;
     typeCounts[t] = (typeCounts[t] || 0) + 1;
   }
 
@@ -1308,7 +1332,38 @@ cmd('focus', 'Pan viewport to center on a node', [
   const id = positional[0];
   if (!id) die('Missing node ID', 'pmx-canvas focus <node-id>');
 
-  const result = await api('POST', '/api/canvas/focus', { id });
+  const result = await api('POST', '/api/canvas/focus', { id, ...(flags['no-pan'] ? { noPan: true } : {}) });
+  output(result);
+});
+
+// ── external-app add ─────────────────────────────────────────
+cmd('external-app add', 'Create a hosted external app node', [
+  'pmx-canvas external-app add --kind excalidraw --title "Diagram"',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('external-app add');
+
+  const kind = typeof flags.kind === 'string' ? flags.kind.trim() : '';
+  if (kind !== 'excalidraw') {
+    die('Unsupported external app kind.', 'Use: pmx-canvas external-app add --kind excalidraw --title "Diagram"');
+  }
+
+  const body: Record<string, unknown> = {
+    title: typeof flags.title === 'string' ? flags.title : 'Excalidraw Diagram',
+    elements: DEFAULT_EXCALIDRAW_ELEMENTS,
+  };
+  const elementsJson = getStringFlag(flags, 'elements-json');
+  if (elementsJson !== undefined) body.elements = parseJsonValue(elementsJson, 'Excalidraw elements', 'Use --elements-json \'[{"type":"rectangle","id":"r1","x":0,"y":0,"width":120,"height":80}]\'');
+  const elementsFile = getStringFlag(flags, 'elements-file', 'initial-file');
+  if (elementsFile) body.elements = parseJsonValue(readFileSync(elementsFile, 'utf-8'), 'Excalidraw elements file', 'Use --elements-file ./scene.excalidraw');
+  applyCommonGeometryFlags(body, flags, {
+    x: 'Use a finite number, e.g. --x 500',
+    y: 'Use a finite number, e.g. --y 300',
+    width: 'Use a positive number, e.g. --width 960',
+    height: 'Use a positive number, e.g. --height 720',
+  });
+
+  const result = await api('POST', '/api/canvas/diagram', body);
   output(result);
 });
 
@@ -1979,10 +2034,24 @@ function showCommandHelp(name: string): void {
     console.log('  --summary                 Return only validation summary metadata');
   }
   if (name === 'web-artifact build') {
+    console.log('\nDependencies:');
+    console.log('  --deps <list>              Add npm dependencies before bundling, e.g. --deps recharts,zod');
     console.log('\nOutput control:');
     console.log('  --include-logs            Include raw build stdout/stderr in the response');
     console.log('  --verbose                 Alias for --include-logs');
   }
+  if (name === 'focus') {
+    console.log('\nViewport:');
+    console.log('  --no-pan                  Select/raise the node without moving the viewport');
+  }
+  if (name === 'external-app add') {
+    console.log('\nOptions:');
+    console.log('  --kind excalidraw          External app kind to create');
+    console.log('  --title <title>            Node title');
+    console.log('  --elements-json <json>     Optional Excalidraw elements array JSON');
+    console.log('  --elements-file <path>     Optional file containing Excalidraw elements JSON');
+    console.log('  --initial-file <path>      Alias for --elements-file');
+  }
   console.log('');
 }
 
@@ -2023,6 +2092,7 @@ Canvas commands:
   pmx-canvas validate spec            Validate json-render/graph payloads without creating nodes
   pmx-canvas watch [options]          Watch semantic canvas changes over SSE
   pmx-canvas focus <id>               Pan viewport to node
+  pmx-canvas external-app add          Add hosted external apps like Excalidraw
   pmx-canvas webview status           Show WebView automation status
   pmx-canvas webview start [options]  Start or replace automation session
   pmx-canvas webview evaluate         Evaluate JS in automation session
@@ -2090,6 +2160,7 @@ Examples:
   pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
   pmx-canvas history --summary
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx
+  pmx-canvas external-app add --kind excalidraw --title "Diagram"
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --include-logs
   pmx-canvas webview evaluate --script "const title = document.title; return title"
   pmx-canvas snapshot save --name "pre-refactor"

package/src/cli/index.ts

@@ -1,19 +1,37 @@
 #!/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([
   'node', 'edge', 'search', 'layout', 'status', 'arrange', 'focus',
   'pin', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
-  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'batch', 'validate', 'serve',
+  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'batch', 'validate', 'serve',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -483,6 +501,7 @@ Agent CLI (works against running server):
   validate spec                       Validate json-render/graph payloads without creating nodes
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
+  external-app add                    Add hosted external apps like Excalidraw
   pin <ids...> | --list | --clear     Manage context pins
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
@@ -524,6 +543,7 @@ Examples:
   pmx-canvas node list                                        List all nodes
   pmx-canvas node schema --type json-render                   Show running-server schema info
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx
+  pmx-canvas external-app add --kind excalidraw --title "Diagram"
   pmx-canvas validate spec --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas open                                             Open the workbench in a browser
   pmx-canvas webview status                                   Show WebView automation status

package/src/client/App.tsx

@@ -28,6 +28,7 @@ import {
   forceDirectedArrange,
   hasInitialServerLayout,
   nodes,
+  pendingExpandedNodeCloseId,
   persistLayout,
   selectedNodeIds,
   sessionId,
@@ -366,7 +367,7 @@ export function App() {
       }
 
       // Esc always collapses expanded node first (even from inside inputs)
-      if (e.key === 'Escape' && expandedNodeId.value) {
+      if (e.key === 'Escape' && expandedNodeId.value && !pendingExpandedNodeCloseId.value) {
         e.preventDefault();
         collapseExpandedNode();
         return;