pmx-canvas 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.7] - 2026-04-26
+
+Small retest-driven follow-up to 0.1.6. Three agent-facing ergonomics:
+`canvas_evaluate` now accepts top-level `await`, snapshot responses gain
+a flat `id` alias for add-style consistency, and the PMX Canvas skill
+documents real DOM selectors plus several quirks an agent would
+otherwise have to discover by trial and error.
+
+### Added
+
+- **Snapshot save responses include a flat `id` alias.** Both
+  `canvas_snapshot` and `POST /api/canvas/snapshots` still return the
+  nested `snapshot` object, and now also include `id: snapshot.id` at
+  the top level — same shape as every other add-style response in the
+  canvas API. HTTP and MCP surfaces are aligned.
+
+### Changed
+
+- **`canvas_evaluate` script mode supports top-level `await`.** Both
+  MCP and HTTP WebView script mode wrap multi-statement bodies in an
+  async IIFE and serialize the resolved return value, so an agent can
+  write `const r = await fetch(...); return r.json();` directly without
+  scaffolding the wrapper itself. WebView script documentation now
+  describes the async behavior explicitly.
+- **PMX Canvas skill docs now ship a defensive ID extractor pattern.**
+  The skill recommends `r.id ?? r.nodeId ?? r.snapshot?.id` so agents
+  pull the right id field across add-style, web-artifact, and snapshot
+  responses without branching per tool.
+- **PMX Canvas skill docs name the real WebView CSS selectors.** The
+  bundled skill calls out `.canvas-node`, `.hud-layer`,
+  `.canvas-toolbar`, `.connection-dot`, and related classes, and is
+  explicit that nodes do **not** expose stable `data-node-id`
+  attributes — agents driving the canvas via `canvas_evaluate` no
+  longer have to discover selectors by trial and error.
+- **PMX Canvas skill edge docs list the valid edge types.** `flow`,
+  `depends-on`, `relation`, `references` — same as the rest of the
+  surface but now explicit in the skill so the agent doesn't guess.
+- **PMX Canvas skill diagram docs clarify
+  `canvas_add_diagram.elements`.** The field expects Excalidraw element
+  objects (rectangles, ellipses, arrows with bindings, labels), not
+  Mermaid / DOT / Graphviz source text or any other diagram DSL.
+
+### Internal
+
+- Regression coverage for snapshot flat-`id` aliases on both MCP and
+  HTTP surfaces, plus async / top-level-`await` WebView script bodies.
+
+[0.1.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.7
+
 ## [0.1.6] - 2026-04-26
 
 CLI/MCP regression cleanup after the 0.1.5 coverage pass. This release tightens
@@ -50,7 +99,6 @@ drift without guessing.
   omitted from the response instead of being `undefined`. Consumers can now
   reliably use `'id' in response` to detect the build-only case. `nodeId` is
   always present and remains the canonical identifier.
-
 ### Fixed
 
 - **`pmx-canvas graph add` no longer starts a rogue server.** The top-level

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

@@ -60,6 +60,7 @@ export declare function getCanvasAutomationWebViewStatus(): CanvasAutomationWebV
 export declare function stopCanvasAutomationWebView(): Promise<boolean>;
 export declare function startCanvasAutomationWebView(url: string, options?: CanvasAutomationWebViewOptions): Promise<CanvasAutomationWebViewStatus>;
 export declare function evaluateCanvasAutomationWebView(expression: string): Promise<unknown>;
+export declare function wrapCanvasAutomationScript(script: string): string;
 export declare function resizeCanvasAutomationWebView(width: number, height: number): Promise<CanvasAutomationWebViewStatus>;
 export declare function screenshotCanvasAutomationWebView(options?: Record<string, unknown>): Promise<Uint8Array>;
 export interface PrimaryWorkbenchIntent {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -332,6 +332,10 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - Cold builds commonly take 45-60 seconds; use a long client timeout such as 300000 ms or more
 - Returns both `id` and `nodeId` for the created artifact node when `openInCanvas` is true
 
+ID extraction for mixed tool responses:
+- Most add-style tools return a flat `id`; web artifacts return `id` plus `nodeId`; snapshots return `id` plus nested `snapshot.id`.
+- Defensive extractor: `const getId = (r) => r.id ?? r.nodeId ?? r.snapshot?.id;`
+
 **`canvas_open_mcp_app`** — Open a tool-backed external MCP app node
 - Required: `toolName`, `transport`
 - `transport` is either `{ type: "stdio", command, args?, cwd?, env? }` or `{ type: "http", url, headers? }`
@@ -366,7 +370,7 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - `from`, `to` (required): source and target node IDs
 - `fromSearch`, `toSearch`: optional search-based selectors when you do not have IDs. Each search
   query must resolve to exactly one node or the edge creation fails with an ambiguity error.
-- `type`: edge type (default: `relation`)
+- `type`: `flow`, `depends-on`, `relation`, or `references` (default: `relation`)
 - `label`: descriptive relationship label
 - `style`: `solid`, `dashed`, or `dotted`
 - `animated`: boolean for visual emphasis
@@ -465,6 +469,7 @@ Current product caveats for grouped comparison boards:
 **`canvas_redo`** — Redo the last undone mutation
 **`canvas_snapshot`** — Save a named snapshot to disk
 - `name` (required): descriptive snapshot name (e.g., "before-refactor")
+- Returns `{ ok, id, snapshot }`; the flat `id` is an alias for `snapshot.id`
 **`canvas_restore`** — Restore canvas from a saved snapshot
 - `id`: snapshot to restore
 **`canvas_diff`** — Compare current canvas against a saved snapshot
@@ -502,7 +507,8 @@ tools below operate on the live canvas state.
 **`canvas_webview_stop`** — Tear down the automation session
 
 **`canvas_evaluate`** — Run JavaScript inside the workbench page and return the result
-- Required: `expression` (a JS expression or a function body)
+- Required: exactly one of `expression` (single JS expression) or `script` (multi-statement body)
+- `script` is wrapped in an async IIFE, so top-level `await` works inside script bodies
 - Useful for asserting DOM state after a sequence of canvas mutations
 - Example: read the count of rendered `.canvas-node` elements:
 
@@ -510,6 +516,20 @@ tools below operate on the live canvas state.
   canvas_evaluate({ expression: 'document.querySelectorAll(".canvas-node").length' })
   ```
 
+Useful workbench selectors:
+- Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
+- Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
+- Canvas chrome: `.hud-layer`, `.canvas-toolbar`, `.connection-dot`, `.canvas-bootstrap-card`
+- Nodes do not expose stable `data-node-id` attributes. Use `canvas_get_layout`, `canvas_search`, or MCP resource data for exact node IDs.
+
+Async script example:
+
+```typescript
+canvas_evaluate({
+  script: 'const title = await Promise.resolve(document.title); return title;',
+})
+```
+
 **`canvas_resize`** — Change the WebView viewport
 - Required: `width`, `height`
 - Use before `canvas_screenshot` when the human needs a specific aspect ratio
@@ -535,6 +555,7 @@ canvas_webview_stop();
 [Excalidraw MCP app](https://github.com/excalidraw/excalidraw-mcp)
 - Required: `elements` — an array of Excalidraw elements (rectangles, ellipses, diamonds, arrows,
   text). Can also be a JSON-array string.
+- `elements` must be Excalidraw element objects, not Mermaid/DOT/source-text diagrams. Convert source diagrams to Excalidraw elements first or use a markdown/web-artifact node.
 - 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"`

package/src/cli/agent.ts

@@ -12,7 +12,7 @@
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
-import { openUrlInExternalBrowser } from '../server/server.js';
+import { openUrlInExternalBrowser, wrapCanvasAutomationScript } from '../server/server.js';
 import { DEFAULT_EXCALIDRAW_ELEMENTS } from '../server/diagram-presets.js';
 import {
   ALL_SEMANTIC_WATCH_EVENT_TYPES,
@@ -1856,9 +1856,9 @@ cmd('webview evaluate', 'Evaluate JavaScript in the active Bun.WebView automatio
         'pmx-canvas webview evaluate --file ./probe.js',
       );
     }
-    expression = `(() => {\n${script}\n})()`;
+    expression = wrapCanvasAutomationScript(script);
   } else if (typeof flags.script === 'string') {
-    expression = `(() => {\n${flags.script}\n})()`;
+    expression = wrapCanvasAutomationScript(flags.script);
   } else {
     expression = requireFlag(
       flags,

package/src/mcp/server.ts

@@ -32,7 +32,7 @@ import {
   type PmxCanvas,
 } from '../server/index.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
-import { emitPrimaryWorkbenchEvent } from '../server/server.js';
+import { emitPrimaryWorkbenchEvent, wrapCanvasAutomationScript } from '../server/server.js';
 import { searchNodes, buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
 import { mutationHistory, diffLayouts, formatDiff } from '../server/mutation-history.js';
 import { buildCodeGraphSummary, formatCodeGraph } from '../server/code-graph.js';
@@ -899,7 +899,7 @@ export async function startMcpServer(): Promise<void> {
     'Evaluate JavaScript in the active Bun.WebView automation session for the workbench page. Use this to inspect rendered browser state. Requires an active automation session started via canvas_webview_start.',
     {
       expression: z.string().optional().describe('JavaScript expression to evaluate in the page context'),
-      script: z.string().optional().describe('Multi-statement JavaScript body. The MCP server wraps it in an IIFE and evaluates the return value.'),
+      script: z.string().optional().describe('Multi-statement JavaScript body. The MCP server wraps it in an async IIFE and evaluates the resolved return value.'),
     },
     async ({ expression, script }) => {
       const c = await ensureCanvas();
@@ -910,7 +910,7 @@ export async function startMcpServer(): Promise<void> {
         };
       }
 
-      const source = script ? `(() => {\n${script}\n})()` : expression!;
+      const source = script ? wrapCanvasAutomationScript(script) : expression!;
       try {
         const value = await c.evaluateAutomationWebView(source);
         return {
@@ -1401,7 +1401,7 @@ export async function startMcpServer(): Promise<void> {
       if (!snapshot) {
         return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'Failed to save snapshot' }) }] };
       }
-      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, snapshot }) }] };
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, id: snapshot.id, snapshot }) }] };
     },
   );
 

package/src/server/server.ts

@@ -473,6 +473,10 @@ export async function evaluateCanvasAutomationWebView(expression: string): Promi
     ));
 }
 
+export function wrapCanvasAutomationScript(script: string): string {
+  return `(async () => {\n${script}\n})()`;
+}
+
 export async function resizeCanvasAutomationWebView(
   width: number,
   height: number,
@@ -2389,10 +2393,10 @@ async function handleWorkbenchWebViewEvaluate(req: Request): Promise<Response> {
   if ((expression ? 1 : 0) + (script ? 1 : 0) !== 1) {
     return responseJson({
       ok: false,
-      error: 'Pass exactly one of "expression" (single JS expression) or "script" (multi-statement body, wrapped in an IIFE).',
+      error: 'Pass exactly one of "expression" (single JS expression) or "script" (multi-statement body, wrapped in an async IIFE).',
     }, 400);
   }
-  const source = script ? `(() => {\n${script}\n})()` : expression;
+  const source = script ? wrapCanvasAutomationScript(script) : expression;
 
   try {
     const value = await evaluateCanvasAutomationWebView(source);
@@ -2899,7 +2903,7 @@ async function handleSnapshotSave(req: Request): Promise<Response> {
   if (!name) return responseText('Missing snapshot name', 400);
   const snapshot = saveCanvasSnapshot(name);
   if (!snapshot) return responseText('Failed to save snapshot', 500);
-  return responseJson({ ok: true, snapshot });
+  return responseJson({ ok: true, id: snapshot.id, snapshot });
 }
 
 async function handleContextPinsUpdate(req: Request): Promise<Response> {