pmx-canvas 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -3,6 +3,106 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.8] - 2026-04-25
+
+Retest-driven follow-up to 0.1.7. This next release restores compatibility
+for image and json-render node creation, fixes the counter MCP fixture's
+accidental iframe overflow, and syncs packaged testing guidance with the
+canonical repo skill.
+
+### Fixed
+
+- **Image `path` is accepted as a compatibility alias for `content`.**
+  `pmx-canvas node add --type image --path <file>`, HTTP
+  `/api/canvas/node` payloads with `{ type: "image", path }`, and MCP
+  `canvas_add_node({ type: "image", path })` now all validate the file
+  and populate `data.src` instead of creating an empty/broken image node.
+- **json-render creation keeps 0.1.7 compatibility.**
+  `canvas_add_json_render_node`, `POST /api/canvas/json-render`, and
+  CLI `node add --type json-render` accept omitted titles and infer a
+  node title from the root element. Bare legacy component specs like
+  `{ type: "Badge", props: {...} }` are wrapped into a one-element
+  document before validation, while complete `{ root, elements }` specs
+  remain the canonical shape.
+- **Counter MCP fixture no longer creates a scrollable iframe by
+  accident.** The fixture now uses border-box sizing and hides root
+  overflow so `100vh` layouts with padding do not become `100vh +
+  padding`. This removes the observed repeated downward scroll in the
+  counter app and adds browser coverage for zero iframe body overflow.
+
+### Changed
+
+- **Packaged PMX Canvas testing skill is back in sync with canonical
+  guidance.** It now documents that `test:coverage` covers only the Bun
+  unit suite, names the coverage artifact, and calls out the WebView
+  automation timeout caveat used to distinguish environment limits from
+  product regressions.
+- **Schema metadata for the `path` alias and relaxed json-render contract
+  is version-stable.** `canvas_describe_schema` and `canvas://schema`
+  surface the image `path` alias and `title.required: false` on
+  json-render so agents discover the new shapes without reading the
+  CHANGELOG.
+- **Agent-facing `skills/pmx-canvas/SKILL.md` documents the same
+  contract.** The skill now describes the `path` alias for image nodes
+  and the relaxed json-render contract (omitted titles, bare component
+  specs) so agents do not need to retry across shapes.
+
+### Internal
+
+- Regression coverage for image `path` alias handling across CLI/HTTP/MCP,
+  json-render compatibility for omitted titles plus bare component specs,
+  and hosted counter MCP app iframe overflow.
+
+## [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.8]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.8
+[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 +150,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/json-render/server.d.ts

@@ -4,7 +4,7 @@ export interface JsonRenderSpec {
     state?: Record<string, unknown>;
 }
 export interface JsonRenderNodeInput {
-    title: string;
+    title?: string;
     spec: unknown;
     x?: number;
     y?: number;
@@ -44,6 +44,7 @@ export declare const GRAPH_NODE_SIZE: {
     height: number;
 };
 export type GraphChartType = 'LineChart' | 'BarChart' | 'PieChart' | 'AreaChart' | 'ScatterChart' | 'RadarChart' | 'StackedBarChart' | 'ComposedChart';
+export declare function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback?: string): string;
 export declare function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec;
 export declare function normalizeGraphType(value: string): GraphChartType;
 export declare function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec;

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.8",
   "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

@@ -270,6 +270,7 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - `content`: for most types, this is markdown text. For `file` type, pass the **file path**
   (e.g., `"src/auth/login.ts"`) — the server auto-loads the file content and watches for changes.
   For `image` type, pass a file path, URL, or data URI.
+- `path`: compatibility alias for image paths only; prefer `content` for new image calls
 - `x`, `y`: position (auto-placed if omitted — prefer omitting for auto-layout)
 - `width`, `height`: dimensions (sensible defaults provided)
 - `color`: semantic color
@@ -306,8 +307,9 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
   ```
 
 **`canvas_add_json_render_node`** — Add a native json-render node
-- Required: `title`, `spec`
-- The `spec` must be a complete json-render object with `root`, `elements`, and optional `state`
+- Required: `spec`; `title` is optional and inferred from the root element when omitted
+- Prefer a complete json-render object with `root`, `elements`, and optional `state`
+- Legacy bare component specs like `{ type: "Badge", props: {...} }` are accepted and wrapped into a one-element document for compatibility
 - Use this when you want a structured UI panel rendered directly inside PMX Canvas
 - For shadcn `Badge`, prefer `props.text` with variants `default`, `secondary`, `destructive`, or
   `outline`. Legacy `props.label` and status variants (`success`, `info`, `warning`, `error`,
@@ -332,6 +334,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 +372,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 +471,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 +509,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 +518,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 +557,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/skills/pmx-canvas-testing/SKILL.md

@@ -40,11 +40,25 @@ bun run test:all            # Bun suite + browser smoke
   Manual browser validation also requires a fresh client bundle. `bun run test:web-canvas`
   already does this for you.
 
+## Coverage Notes
+
+- `bun run test:coverage` covers the Bun unit suite under `tests/unit/`
+- Coverage output is written to `coverage/lcov.info` and also printed as a text summary
+- CI currently uses that same unit-test coverage command, then runs browser smoke separately
+- Do not describe `test:coverage` as full-stack coverage; Playwright coverage is not wired in here
+
 ## Current Project Test Surface
 
 - Bun tests live under `tests/unit/`
 - Playwright browser smoke lives under `tests/e2e/`
-- CI runs coverage plus the browser smoke flow
+- CI runs Bun coverage plus the browser smoke flow
+
+## WebView Automation Caveat
+
+- Some Linux/CI environments expose `Bun.WebView` but still cannot start a usable automation
+  session within the timeout window
+- When testing WebView automation, treat a cleanly reported unsupported/timeout runtime boundary
+  as distinct from a product regression
 
 Prefer extending the existing suites before inventing a one-off script.
 

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,
@@ -522,11 +522,8 @@ async function buildJsonRenderRequestBody(
   flags: Record<string, string | true>,
 ): Promise<Record<string, unknown>> {
   const hint =
-    'Use: pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json';
+    'Use: pmx-canvas node add --type json-render --spec-file ./dashboard.json --title "Ops Dashboard"';
   const title = typeof flags.title === 'string' ? flags.title.trim() : '';
-  if (!title) {
-    die('json-render nodes require --title.', hint);
-  }
 
   const rawSpec = await readTextInput(flags, {
     fileFlags: ['spec-file'],
@@ -538,7 +535,7 @@ async function buildJsonRenderRequestBody(
   });
 
   const spec = parseJsonValue(rawSpec, 'JSON spec', hint);
-  const body: Record<string, unknown> = { title, spec };
+  const body: Record<string, unknown> = { ...(title ? { title } : {}), spec };
   applyCommonGeometryFlags(body, flags, {
     x: 'Use a finite number, e.g. --x 500',
     y: 'Use a finite number, e.g. --y 300',
@@ -985,8 +982,11 @@ cmd('node add', 'Add a node to the canvas', [
   const body: Record<string, unknown> = { type };
   if (flags.title) body.title = flags.title;
   const webpageUrl = getStringFlag(flags, 'url');
+  const imagePath = getStringFlag(flags, 'path');
   if (type === 'webpage' && webpageUrl) {
     body.url = webpageUrl;
+  } else if (type === 'image' && imagePath && !flags.content) {
+    body.content = imagePath;
   } else if (flags.content) {
     body.content = flags.content;
   }
@@ -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/json-render/server.ts

@@ -11,7 +11,7 @@ export interface JsonRenderSpec {
 }
 
 export interface JsonRenderNodeInput {
-  title: string;
+  title?: string;
   spec: unknown;
   x?: number;
   y?: number;
@@ -447,10 +447,38 @@ function normalizeSpec(spec: Record<string, unknown>): Record<string, unknown> {
   return changed ? { ...spec, elements: normalizedElements } : spec;
 }
 
-export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+function isBareJsonRenderElement(spec: Record<string, unknown>): boolean {
+  return typeof spec.type === 'string' && !('root' in spec) && !('elements' in spec);
+}
+
+function normalizeJsonRenderInput(spec: unknown): unknown {
   const specRecord = asRecord(spec);
+  if (!specRecord || !isBareJsonRenderElement(specRecord)) return spec;
+
+  return {
+    root: 'root',
+    elements: {
+      root: {
+        ...specRecord,
+        children: Array.isArray(specRecord.children)
+          ? specRecord.children.filter((child: unknown) => typeof child === 'string')
+          : [],
+      },
+    },
+  };
+}
+
+export function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback = 'json-render'): string {
+  const rootElement = asRecord(spec.elements[spec.root]);
+  const rootProps = asRecord(rootElement?.props);
+  const title = rootProps?.title ?? rootProps?.text ?? rootElement?.type;
+  return typeof title === 'string' && title.trim().length > 0 ? title.trim() : fallback;
+}
+
+export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+  const specRecord = asRecord(normalizeJsonRenderInput(spec));
   if (!specRecord || typeof specRecord.root !== 'string' || !asRecord(specRecord.elements)) {
-    throw new Error('Missing root and elements in spec.');
+    throw new Error('Missing root and elements in spec. Pass a complete {root, elements} document, or a single bare component object with a type field.');
   }
 
   const normalizedSpec = normalizeSpec(specRecord);

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';
@@ -41,11 +41,18 @@ import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js
 
 let canvas: PmxCanvas | null = null;
 
-const jsonRenderSpecSchema = z.object({
-  root: z.string(),
-  elements: z.record(z.string(), z.unknown()),
-  state: z.record(z.string(), z.unknown()).optional(),
-}).passthrough();
+const jsonRenderSpecSchema = z.union([
+  z.object({
+    root: z.string(),
+    elements: z.record(z.string(), z.unknown()),
+    state: z.record(z.string(), z.unknown()).optional(),
+  }).passthrough(),
+  z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    children: z.array(z.string()).optional(),
+  }).passthrough(),
+]);
 
 function structuredSchemaDescription(): string {
   const routing = describeCanvasSchema().mcp.nodeTypeRouting;
@@ -140,6 +147,7 @@ export async function startMcpServer(): Promise<void> {
         .describe('Node type (prefer canvas_create_group for groups)'),
       title: z.string().optional().describe('Node title'),
       content: z.string().optional().describe('Node content (markdown for markdown nodes, file path for file nodes, image path/URL/data-URI for image nodes, URL for webpage nodes)'),
+      path: z.string().optional().describe('Compatibility alias for image node content. Prefer content for image paths.'),
       url: z.string().optional().describe('Canonical webpage URL field for webpage nodes. Overrides content when both are provided.'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
@@ -169,7 +177,10 @@ export async function startMcpServer(): Promise<void> {
           ...(result.ok ? {} : { isError: true }),
         };
       }
-      const id = c.addNode(input);
+      const nodeInput = input.type === 'image' && input.path && !input.content
+        ? { ...input, content: input.path }
+        : input;
+      const id = c.addNode(nodeInput);
       return {
         content: [{ type: 'text', text: JSON.stringify(createdNodePayload(c, id), null, 2) }],
       };
@@ -442,8 +453,8 @@ export async function startMcpServer(): Promise<void> {
     'canvas_add_json_render_node',
     'Create a native json-render canvas node from a complete spec. Use this for structured dashboards, forms, tables, and other interactive UI panels that should render directly inside PMX Canvas.',
     {
-      title: z.string().describe('Node title'),
-      spec: jsonRenderSpecSchema.describe('Complete json-render spec with root, elements, and optional state'),
+      title: z.string().optional().describe('Optional node title. If omitted, PMX Canvas infers one from the root element.'),
+      spec: z.unknown().describe('json-render spec. Prefer a complete {root, elements, state?} document; a single bare component object is accepted for legacy callers.'),
       x: z.number().optional().describe('Optional X position'),
       y: z.number().optional().describe('Optional Y position'),
       width: z.number().optional().describe('Optional node width'),
@@ -453,7 +464,7 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       try {
         const result = c.addJsonRenderNode({
-          title: input.title,
+          ...(typeof input.title === 'string' ? { title: input.title } : {}),
           spec: input.spec,
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
@@ -899,7 +910,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 +921,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 +1412,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/canvas-operations.ts

@@ -24,6 +24,7 @@ import {
   buildGraphSpec,
   createJsonRenderNodeData,
   GRAPH_NODE_SIZE,
+  inferJsonRenderNodeTitle,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -1000,7 +1001,7 @@ export function createCanvasJsonRenderNode(
     collapsed: false,
     pinned: false,
     dockPosition: null,
-    data: createJsonRenderNodeData(id, input.title, spec, {
+    data: createJsonRenderNodeData(id, input.title?.trim() || inferJsonRenderNodeTitle(spec), spec, {
       viewerType: 'json-render',
     }),
   };

package/src/server/canvas-schema.ts

@@ -171,7 +171,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_add_node',
     fields: [
-      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.' },
+      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.', aliases: ['path'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'data.warning', type: 'string | { title?: string; detail: string }', required: false, description: 'Optional agent-supplied warning shown above the image.' },
       { name: 'data.warnings', type: 'Array<string | { title?: string; detail: string }>', required: false, description: 'Optional list of agent-supplied image warnings.' },
@@ -280,8 +280,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/json-render',
     mcpTool: 'canvas_add_json_render_node',
     fields: [
-      { name: 'title', type: 'string', required: true, description: 'Rendered node title.' },
-      { name: 'spec', type: 'JsonRenderSpec', required: true, description: 'Complete json-render spec.' },
+      { name: 'title', type: 'string', required: false, description: 'Optional rendered node title; inferred from the root element when omitted.' },
+      { name: 'spec', type: 'JsonRenderSpec | JsonRenderElement', required: true, description: 'Complete {root, elements} json-render spec, or a legacy single bare component object with a type field.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },

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,
@@ -1206,12 +1210,15 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
+  const content = type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string'
+    ? body.path
+    : body.content;
   let added: ReturnType<typeof addCanvasNode>;
   try {
     added = addCanvasNode({
       type: type as CanvasNodeState['type'],
       ...(typeof body.title === 'string' ? { title: body.title } : {}),
-      ...(typeof body.content === 'string' ? { content: body.content } : {}),
+      ...(typeof content === 'string' ? { content } : {}),
       ...(extraData ? { data: extraData } : {}),
       ...(typeof body.x === 'number' ? { x: body.x } : {}),
       ...(typeof body.y === 'number' ? { y: body.y } : {}),
@@ -1599,13 +1606,10 @@ async function handleCanvasAddJsonRender(req: Request): Promise<Response> {
   const title = typeof body.title === 'string' ? body.title.trim() : '';
   const rawSpec =
     body.spec && typeof body.spec === 'object' && !Array.isArray(body.spec) ? body.spec : body;
-  if (!title) {
-    return responseJson({ ok: false, error: 'Missing required field: title.' }, 400);
-  }
 
   try {
     const result = createCanvasJsonRenderNode({
-      title,
+      ...(title ? { title } : {}),
       spec: rawSpec,
       ...(typeof body.x === 'number' ? { x: body.x } : {}),
       ...(typeof body.y === 'number' ? { y: body.y } : {}),
@@ -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> {