pmx-canvas 0.1.2 → 0.1.4

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,6 +15,15 @@ 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/jsx-runtime").JSX.Element;

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/json-render/charts/components.d.ts

@@ -39,9 +39,10 @@ export declare const tooltipStyle: {
     fontSize: number;
 };
 /** Shared wrapper for cartesian charts (Line + Bar). */
-export declare function CartesianChart({ props, children, }: {
+export declare function CartesianChart({ props, children, className, }: {
     props: CartesianChartProps;
     children: (data: Record<string, unknown>[]) => ReactNode;
+    className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 declare function ChartLineChart({ props }: BaseComponentProps<CartesianChartProps>): import("react/jsx-runtime").JSX.Element;
 declare function ChartBarChart({ props }: BaseComponentProps<CartesianChartProps>): import("react/jsx-runtime").JSX.Element;

package/dist/types/server/canvas-serialization.d.ts

@@ -1,6 +1,7 @@
 import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import { type CanvasNodeProvenance } from './canvas-provenance.js';
 export interface SerializedCanvasNode extends CanvasNodeState {
+    kind: string;
     title: string | null;
     content: string | null;
     path: 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/ext-app-lookup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve the canvas node ID for a given ext-app `toolCallId`.
+ *
+ * v0.1.4 fixed a long-standing `ext-app-ext-app-…` double-prefix bug where
+ * both `nodeId` and `toolCallId` carried the `ext-app-` prefix. This helper
+ * encodes the lookup contract so it doesn't drift between the
+ * `PmxCanvas` SDK class and the HTTP server.
+ *
+ * Resolution order:
+ *   1. The direct prefixed form (`ext-app-<toolCallId>` if not already
+ *      prefixed, otherwise `toolCallId` as-is).
+ *   2. The legacy `ext-app-ext-app-…` form, for canvases persisted before
+ *      v0.1.4 and still on disk. Remove this fallback in v0.2.x.
+ *   3. A scan of the layout for any `mcp-app` ext-app node carrying that
+ *      `toolCallId` in its data.
+ */
+import type { CanvasNodeState } from './canvas-state.js';
+export interface ExtAppLookupSource {
+    getNode(id: string): CanvasNodeState | undefined;
+    listNodes(): readonly CanvasNodeState[];
+}
+export declare function findCanvasExtAppNodeId(toolCallId: string, source: ExtAppLookupSource): string | null;

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>;
@@ -190,6 +195,7 @@ export declare class PmxCanvas extends EventEmitter {
         height?: number;
     }): Promise<{
         ok: true;
+        id?: string;
         nodeId: string | null;
         toolCallId: string;
         sessionId: string;
@@ -197,6 +203,7 @@ export declare class PmxCanvas extends EventEmitter {
     }>;
     addDiagram(input: DiagramPresetOpenInput): Promise<{
         ok: true;
+        id?: string;
         nodeId: string | null;
         toolCallId: string;
         sessionId: string;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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:
 
@@ -80,7 +84,9 @@ pmx-canvas layout                          # Full canvas state
 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 node add --type graph --graphType bar --data '[{"x":"a","y":1}]' --xKey x --yKey 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,11 @@ 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 node list --type web-artifact --summary
+pmx-canvas node list --type external-app --summary
 pmx-canvas pin --list
 pmx-canvas snapshot save --name "before-refactor"
 pmx-canvas code-graph
@@ -100,10 +109,12 @@ pmx-canvas spatial
 
 - `node add|list|get|update|remove` — manage nodes
 - `node schema` — inspect running-server create schemas and canonical examples, with `--summary`, `--field`, and `--component` filters
+- Graph CLI fields accept both kebab-case flags and camelCase schema names, e.g. `--graph-type`/`--graphType`, `--x-key`/`--xKey`, and `--bar-color`/`--barColor`.
 - `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
@@ -111,6 +122,8 @@ pmx-canvas spatial
 - `group create|add|remove` — manage groups
 - `clear --yes` — destructive clear with explicit confirmation
 - `validate spec` — validate json-render specs and graph payloads without creating nodes
+- `web-artifact build` — build bundled React/Tailwind HTML artifacts; use `--deps` for extra packages and `--include-logs` only when raw logs are useful
+- `external-app add --kind excalidraw` — create the hosted Excalidraw preset; response includes `id` and `nodeId` aliases for the same canvas node
 - `serve status|stop` — inspect and stop daemonized servers started with `serve --daemon`
 - `code-graph`, `spatial` — analysis commands
 
@@ -120,10 +133,12 @@ Current caveat:
   through search later in the session. When you plan to curate an app-heavy comparison area,
   capture node IDs immediately after creation and verify membership with `node get --summary`,
   `layout --summary`, or the browser selection state instead of relying on search alone.
-- Some `mcp-app` creation flows are still awkward to address immediately after creation. If a
-  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.
+- App-like nodes persist as `type: "mcp-app"` internally but serialized results include `kind`:
+  `web-artifact`, `external-app`, or `mcp-app`. Prefer `node list --type web-artifact` or
+  `node list --type external-app` when you need the operational subtype.
+- 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 +156,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 +282,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 +377,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 +400,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 +474,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'