pmx-canvas 0.1.27 → 0.1.28

package/dist/types/json-render/charts/components.d.ts

@@ -67,6 +67,16 @@ export declare function useChartFrameHeight(explicitHeight: number | null | unde
     height: number;
     width: number;
 };
+/**
+ * Height available for the plotted SVG inside `.pmx-chart`, i.e. the measured
+ * frame height minus the non-plot chrome: the `.pmx-chart__title` block (~24px
+ * of text + margin, only when a title is shown) plus the chart's own vertical
+ * padding. Sizing the SVG to this — instead of the full frame height — keeps a
+ * filled chart's title+plot within the frame so it doesn't push a scrollbar onto
+ * the single iframe-document scroller. Dense charts still exceed it and scroll
+ * (one scrollbar, as expected).
+ */
+export declare function chartPlotHeight(height: number, hasTitle: boolean): number;
 /** Shared wrapper for cartesian charts (Line + Bar). */
 export declare function CartesianChart({ props, children, className, }: {
     props: CartesianChartProps;

package/dist/types/json-render/directives.d.ts

@@ -18,6 +18,16 @@ export declare const pmxCanvasDirectives: DirectiveDefinition[];
  * `$cond`/`$template`/`$computed`). These objects are resolved inside the
  * renderer, so the server-side validators must leave them untouched instead of
  * string-coercing them to `"[object Object]"` or rejecting them as the wrong
- * primitive type.
+ * primitive type. An object whose only `$`-key is unrecognized (e.g. `$path`)
+ * is NOT dynamic — the renderer has no directive to resolve it.
  */
 export declare function isDynamicPropValue(value: unknown): boolean;
+/**
+ * Returns the offending key when a prop value looks like a dynamic expression
+ * (it has `$`-prefixed keys) but none of them is a recognized binding or
+ * registered directive — e.g. `{ "$path": "…" }`. Such objects pass a naive
+ * "has a $-key" check yet render as `"[object Object]"` because the renderer has
+ * no directive to resolve them. Returns null for plain values and for genuinely
+ * dynamic expressions.
+ */
+export declare function findUnknownDirectiveKey(value: unknown): string | null;

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

@@ -64,6 +64,14 @@ export declare const MCP_APP_NODE_DEFAULT_SIZE: {
     width: number;
     height: number;
 };
+export declare const IMAGE_NODE_DEFAULT_SIZE: {
+    width: number;
+    height: number;
+};
+export declare const LEDGER_NODE_DEFAULT_SIZE: {
+    width: number;
+    height: number;
+};
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];

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

@@ -23,6 +23,11 @@ export declare class PmxCanvas extends EventEmitter {
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
     }): Promise<void>;
     stop(): void;
+    /**
+     * Add a node to the canvas and return the created node (including its `id`,
+     * resolved geometry, and data). Destructure `const { id } = canvas.addNode(...)`
+     * or keep the whole node — both work. (Previously returned a bare id string.)
+     */
     addNode(input: {
         type: CanvasNodeState['type'];
         title?: string;
@@ -42,7 +47,7 @@ export declare class PmxCanvas extends EventEmitter {
         width?: number;
         height?: number;
         strictSize?: boolean;
-    }): string;
+    }): CanvasNodeState;
     addWebpageNode(input: {
         title?: string;
         url: string;

package/docs/sdk.md

@@ -15,16 +15,16 @@ import { createCanvas } from 'pmx-canvas';
 const canvas = createCanvas({ port: 4313 });
 await canvas.start({ open: true });
 
-// Add nodes
+// Add nodes — addNode returns the created node (with `.id`, geometry, and data)
 const n1 = canvas.addNode({ type: 'markdown', title: 'Plan', content: '# Step 1\nDo the thing.' });
 const n2 = canvas.addNode({ type: 'status', title: 'Build', content: 'passing' });
 const n3 = canvas.addNode({ type: 'file', content: 'src/index.ts' });
 
-// Connect them
-canvas.addEdge({ from: n1, to: n2, type: 'flow' });
+// Connect them (edges and groups reference node ids)
+canvas.addEdge({ from: n1.id, to: n2.id, type: 'flow' });
 
 // Group related nodes
-canvas.createGroup({ title: 'Build Pipeline', childIds: [n1, n2] });
+canvas.createGroup({ title: 'Build Pipeline', childIds: [n1.id, n3.id] });
 
 // Self-contained HTML in a sandboxed iframe
 canvas.addHtmlNode({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "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/src/cli/agent.ts

@@ -805,7 +805,28 @@ 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), { allowErrorJson: true });
+  const body = await buildWebArtifactRequestBody(flags);
+  // The build (init + dependency install + bundle) runs server-side and only
+  // returns a single HTTP response on completion, which can take minutes on a
+  // cold workspace. With no output an agent's tool wait expires before the node
+  // appears and the build looks hung. Emit a default-on heartbeat to stderr
+  // while the request is in flight — stdout (output) and the JSON response body
+  // stay untouched, so anything parsing stdout is unaffected.
+  const startedMs = Date.now();
+  process.stderr.write(
+    `[web-artifact] building "${String(body.title)}" — init + install + bundle (this can take a few minutes)...\n`,
+  );
+  const heartbeat = setInterval(() => {
+    const elapsedSeconds = Math.round((Date.now() - startedMs) / 1000);
+    process.stderr.write(`[web-artifact] still building... ${elapsedSeconds}s elapsed\n`);
+  }, 10_000);
+  if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  let result: unknown;
+  try {
+    result = await api('POST', '/api/canvas/web-artifact', body, { allowErrorJson: true });
+  } finally {
+    clearInterval(heartbeat);
+  }
   output(result);
   if (isRecord(result) && result.ok === false) {
     process.exit(1);

package/src/client/nodes/ExtAppFrame.tsx

@@ -221,6 +221,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
     let hostContextResizeObserver: ResizeObserver | null = null;
     let hostContextRaf: number | null = null;
+    let readyNudgeRaf: number | null = null;
     toolResultSentRef.current = false;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
@@ -266,6 +267,24 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         });
       };
 
+      // Re-deliver host context once the iframe has been laid out and painted.
+      // Canvas-backed widgets (e.g. Excalidraw) size their drawing surface from
+      // containerDimensions at first render; the single handshake-time delivery
+      // can land before the embedded frame has settled, leaving a black canvas
+      // until an expand/collapse forces a reflow. A double rAF lands after
+      // layout+paint, and sendHostContextChange always delivers (setHostContext
+      // would diff-suppress the identical context just sent at handshake).
+      const nudgeHostContextAfterLayout = () => {
+        if (readyNudgeRaf !== null) return;
+        readyNudgeRaf = requestAnimationFrame(() => {
+          readyNudgeRaf = requestAnimationFrame(() => {
+            readyNudgeRaf = null;
+            if (disposed || !bridgeReadyRef.current) return;
+            void bridge.sendHostContextChange?.(buildHostContext());
+          });
+        });
+      };
+
       const bridge = new AppBridge(
         null,
         { name: 'PMX Canvas', version: '1.0.0' },
@@ -404,6 +423,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         void Promise.resolve(bridge.sendHostContextChange(buildHostContext(isExpanded ? 'fullscreen' : 'inline')))
           .then(() => sendExtAppBootstrapState(bridge, latestToolInputRef.current, undefined))
           .then(() => flushToolResult(bridge))
+          .then(() => nudgeHostContextAfterLayout())
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             setError(`Bridge bootstrap failed: ${msg}`);
@@ -428,6 +448,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             }
             setStatus(bootstrapToolResult ? 'done' : 'ready');
             setError(null);
+            nudgeHostContextAfterLayout();
           })
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -478,6 +499,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         cancelAnimationFrame(hostContextRaf);
         hostContextRaf = null;
       }
+      if (readyNudgeRaf !== null) {
+        cancelAnimationFrame(readyNudgeRaf);
+        readyNudgeRaf = null;
+      }
       bridgeReadyRef.current = false;
       toolResultSendingRef.current = null;
       themeUnsubRef.current?.();

package/src/json-render/charts/components.tsx

@@ -124,12 +124,24 @@ export function useChartFrameHeight(explicitHeight: number | null | undefined, f
 
     const updateHeight = () => {
       const rect = frame.getBoundingClientRect();
-      const doc = document.documentElement;
-      const currentHeight = frame.getBoundingClientRect().height;
-      const overflow = Math.max(0, doc.scrollHeight - doc.clientHeight);
-      const available = overflow > 0 ? currentHeight - overflow : window.innerHeight - rect.top - 24;
-      setAutoHeight(Math.max(220, Math.round(available)));
-      setAutoWidth(Math.round(rect.width));
+      // Available height runs from the frame's top to the bottom of the iframe
+      // viewport. It is deliberately NOT derived from the document's own scroll
+      // overflow: feeding the chart's own overflow back into its height creates a
+      // shrink -> no-overflow -> grow -> overflow feedback loop that repaints
+      // forever (the reported Tufte-chart flicker). When natural content exceeds
+      // the viewport the document simply scrolls (with a stable gutter, see
+      // index.css) instead of the height oscillating.
+      // Reserve ~44px below the frame for the chrome that sits under the chart
+      // inside the json-render card (card padding/margin ≈ 41px, measured stable
+      // across node sizes). rect.top already accounts for everything above. With
+      // too small a reserve a filled chart spills ~17px past the viewport and the
+      // iframe document shows a needless scrollbar.
+      const available = Math.max(220, Math.round(window.innerHeight - rect.top - 44));
+      const nextWidth = Math.round(rect.width);
+      // Dead-band: ignore sub-threshold churn so a stray re-measure (e.g. a
+      // scrollbar toggling) can't ping-pong state and repaint.
+      setAutoHeight((prev) => (Math.abs(available - prev) > 2 ? available : prev));
+      setAutoWidth((prev) => (Math.abs(nextWidth - prev) > 2 ? nextWidth : prev));
     };
 
     updateHeight();
@@ -150,6 +162,19 @@ export function useChartFrameHeight(explicitHeight: number | null | undefined, f
   };
 }
 
+/**
+ * Height available for the plotted SVG inside `.pmx-chart`, i.e. the measured
+ * frame height minus the non-plot chrome: the `.pmx-chart__title` block (~24px
+ * of text + margin, only when a title is shown) plus the chart's own vertical
+ * padding. Sizing the SVG to this — instead of the full frame height — keeps a
+ * filled chart's title+plot within the frame so it doesn't push a scrollbar onto
+ * the single iframe-document scroller. Dense charts still exceed it and scroll
+ * (one scrollbar, as expected).
+ */
+export function chartPlotHeight(height: number, hasTitle: boolean): number {
+  return Math.max(60, height - (hasTitle ? 36 : 12));
+}
+
 /** Shared wrapper for cartesian charts (Line + Bar). */
 export function CartesianChart({
   props,

package/src/json-render/charts/tufte-components.tsx

@@ -12,7 +12,7 @@
  */
 
 import type { BaseComponentProps } from '@json-render/react';
-import { CHART_COLORS, useChartFrameHeight } from './components';
+import { CHART_COLORS, chartPlotHeight, useChartFrameHeight } from './components';
 
 const ACCENT = CHART_COLORS[0];
 const INK = 'var(--foreground, #111)';
@@ -155,7 +155,12 @@ function ChartDotPlot({ props }: BaseComponentProps<DotPlotProps>) {
   const labelW = 140;
   const valueW = 52;
   const padX = 12;
-  const rowH = rows.length > 0 ? Math.min(36, (height - 12) / rows.length) : 24;
+  // Distribute rows across the available plot height with 36px as a MINIMUM (not
+  // a maximum): a sparse chart fills a tall expanded card instead of staying
+  // tile-sized and top-aligned with whitespace below; a dense chart keeps ≥36px
+  // rows and scrolls cleanly (height no longer oscillates — see useChartFrameHeight).
+  const plotH = chartPlotHeight(height, Boolean(props.title));
+  const rowH = rows.length > 0 ? Math.max(36, plotH / rows.length) : 24;
   const plotLeft = labelW + padX;
 
   return (
@@ -231,7 +236,11 @@ function ChartBulletChart({ props }: BaseComponentProps<BulletChartProps>) {
   const w = width || 480;
   const labelW = 120;
   const padX = 12;
-  const rowH = rows.length > 0 ? Math.min(56, (height - 12) / rows.length) : 48;
+  // Fill the available plot height with 56px as a MINIMUM per row (the bar itself
+  // is capped at barH below, so extra row height just adds breathing room) so a
+  // sparse bullet chart fills a tall expanded card instead of leaving whitespace.
+  const plotH = chartPlotHeight(height, Boolean(props.title));
+  const rowH = rows.length > 0 ? Math.max(56, plotH / rows.length) : 48;
 
   return (
     <div ref={frameRef} className="pmx-chart pmx-chart--bullet" style={{ height }}>
@@ -328,12 +337,15 @@ function ChartSlopegraph({ props }: BaseComponentProps<SlopegraphProps>) {
   // measured pixels (fallback width until the ResizeObserver reports the size).
   const w = width || 480;
   const rightX = Math.max(leftX + 40, w - rightInset);
-  const scaleY = (v: number) => topPad + (1 - (v - min) / (max - min)) * (height - topPad - botPad);
+  // Size the SVG to the plot height (frame minus title/padding) so the chart
+  // fills without pushing a scrollbar onto the iframe document.
+  const plotH = chartPlotHeight(height, Boolean(props.title));
+  const scaleY = (v: number) => topPad + (1 - (v - min) / (max - min)) * (plotH - topPad - botPad);
 
   return (
     <div ref={frameRef} className="pmx-chart pmx-chart--slopegraph" style={{ height }}>
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
-      <svg className="pmx-chart__slopegraph-svg" width="100%" height={height} role="img" aria-label={props.title ?? 'slopegraph'}>
+      <svg className="pmx-chart__slopegraph-svg" width="100%" height={plotH} role="img" aria-label={props.title ?? 'slopegraph'}>
         <text x={leftX} y={14} textAnchor="end" fontSize={12} fontWeight={600} fill={MUTED}>
           {props.beforeLabel ?? props.beforeKey}
         </text>

package/src/json-render/directives.ts

@@ -15,15 +15,50 @@ import { standardDirectives } from '@json-render/directives';
  */
 export const pmxCanvasDirectives: DirectiveDefinition[] = [...standardDirectives];
 
+/**
+ * The $-prefixed keys the renderer can actually resolve: core built-in bindings
+ * plus the names of the directives registered above. Anything else (e.g. a
+ * hallucinated `$path`) is NOT a valid dynamic expression — to read a value from
+ * state by path the correct binding is `$state`.
+ */
+const KNOWN_DYNAMIC_KEYS = new Set<string>([
+  '$state',
+  '$item',
+  '$index',
+  '$bindState',
+  '$bindItem',
+  '$cond',
+  '$computed',
+  '$template',
+  ...pmxCanvasDirectives.map((directive) => directive.name),
+]);
+
 /**
  * True when a prop value is a render-time dynamic expression — a directive
  * (`$format`/`$math`/…) or an existing binding (`$state`/`$item`/`$bindItem`/
  * `$cond`/`$template`/`$computed`). These objects are resolved inside the
  * renderer, so the server-side validators must leave them untouched instead of
  * string-coercing them to `"[object Object]"` or rejecting them as the wrong
- * primitive type.
+ * primitive type. An object whose only `$`-key is unrecognized (e.g. `$path`)
+ * is NOT dynamic — the renderer has no directive to resolve it.
  */
 export function isDynamicPropValue(value: unknown): boolean {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
-  return Object.keys(value as Record<string, unknown>).some((key) => key.startsWith('$'));
+  return Object.keys(value as Record<string, unknown>).some((key) => KNOWN_DYNAMIC_KEYS.has(key));
+}
+
+/**
+ * Returns the offending key when a prop value looks like a dynamic expression
+ * (it has `$`-prefixed keys) but none of them is a recognized binding or
+ * registered directive — e.g. `{ "$path": "…" }`. Such objects pass a naive
+ * "has a $-key" check yet render as `"[object Object]"` because the renderer has
+ * no directive to resolve them. Returns null for plain values and for genuinely
+ * dynamic expressions.
+ */
+export function findUnknownDirectiveKey(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+  const dollarKeys = Object.keys(value as Record<string, unknown>).filter((key) => key.startsWith('$'));
+  if (dollarKeys.length === 0) return null;
+  if (dollarKeys.some((key) => KNOWN_DYNAMIC_KEYS.has(key))) return null;
+  return dollarKeys[0] ?? null;
 }

package/src/json-render/renderer/index.css

@@ -268,7 +268,12 @@ button {
 .pmx-chart {
   width: 100%;
   min-width: 280px;
-  overflow-x: auto;
+  /* overflow:visible (not overflow-x:auto) so the chart is NOT its own scroll
+     container. overflow-x:auto makes overflow-y compute to auto too (CSS quirk),
+     which — once a chart fills the viewport — added a second nested scrollbar on
+     top of the iframe document's. Let the single iframe document handle any
+     overflow instead. */
+  overflow: visible;
   padding: 0.5rem 0;
 }
 

package/src/json-render/server.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { buildAppHtml } from '@json-render/mcp/build-app-html';
 import { applySpecPatch, parseSpecStreamLine, type Spec, type SpecStreamLine } from '@json-render/core';
 import { allComponentDefinitions, catalog, validateShadcnElementProps, type JsonRenderIssue } from './catalog.js';
-import { isDynamicPropValue } from './directives.js';
+import { findUnknownDirectiveKey, isDynamicPropValue } from './directives.js';
 
 export interface JsonRenderSpec {
   root: string;
@@ -512,6 +512,24 @@ export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpe
     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.');
   }
 
+  // Reject an unrecognized $-keyed expression object in any element prop BEFORE
+  // normalization can string-coerce it to "[object Object]" (the reported $path
+  // symptom). The error names the offending key and points at $state, the
+  // correct path-read binding.
+  const elementsRecord = asRecord(specRecord.elements) ?? {};
+  for (const [elementKey, rawElement] of Object.entries(elementsRecord)) {
+    const props = asRecord(asRecord(rawElement)?.props);
+    if (!props) continue;
+    for (const [propKey, propValue] of Object.entries(props)) {
+      const unknownKey = findUnknownDirectiveKey(propValue);
+      if (unknownKey) {
+        throw new Error(
+          `Unknown directive "${unknownKey}" on elements.${elementKey}.props.${propKey}. Valid directives are $format, $math, $concat, $count, $truncate, $pluralize, $join; to read a value from state by path use { "$state": "/path" } (there is no $path directive).`,
+        );
+      }
+    }
+  }
+
   const normalizedSpec = normalizeSpec(specRecord);
   const validation = catalog.validate(normalizedSpec);
   if (!validation.success || !validation.data) {

package/src/mcp/canvas-access.ts

@@ -212,7 +212,9 @@ class LocalCanvasAccess implements CanvasAccess {
   }
 
   async addNode(input: AddNodeInput): Promise<string> {
-    return this.canvas.addNode(input);
+    // PmxCanvas.addNode returns the created node; the CanvasAccess contract
+    // (shared with the remote proxy + MCP) stays id-only.
+    return this.canvas.addNode(input).id;
   }
 
   async addWebpageNode(input: AddWebpageNodeInput): Promise<Awaited<ReturnType<PmxCanvas['addWebpageNode']>>> {

package/src/mcp/server.ts

@@ -764,8 +764,8 @@ export async function startMcpServer(): Promise<void> {
       outputPath: z.string().optional().describe('Optional workspace-relative HTML output path. Defaults to .pmx-canvas/artifacts/<slug>.html'),
       openInCanvas: z.boolean().optional().describe('Open the generated artifact in canvas after build (default true)'),
       includeLogs: z.boolean().optional().describe('Include raw build stdout/stderr in the response (default false)'),
-      initScriptPath: z.string().optional().describe('Optional absolute script path override for tests/debugging'),
-      bundleScriptPath: z.string().optional().describe('Optional absolute script path override for tests/debugging'),
+      initScriptPath: z.string().optional().describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
+      bundleScriptPath: z.string().optional().describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
       timeoutMs: z.number().optional().describe('Optional timeout in milliseconds for init and bundle commands'),
     },
     async (input) => {

package/src/server/canvas-operations.ts

@@ -107,6 +107,12 @@ interface CanvasAddNodeInput {
 
 export const MARKDOWN_NODE_DEFAULT_SIZE = { width: 640, height: 420 };
 export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
+// Image and ledger nodes previously fell through to the generic 360x200 frame,
+// which clipped content (a 360-wide image / log stream is cramped). Give them
+// roomier defaults; height still auto-fits to content (see auto-fit.ts), so the
+// width bump is the reliable lever.
+export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
+export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
 interface CanvasCreateGroupInput {
   title?: string;
@@ -1771,14 +1777,22 @@ export async function executeCanvasBatch(
                   ? MARKDOWN_NODE_DEFAULT_SIZE.width
                   : type === 'mcp-app'
                     ? MCP_APP_NODE_DEFAULT_SIZE.width
-                    : 360,
+                    : type === 'image'
+                      ? IMAGE_NODE_DEFAULT_SIZE.width
+                      : type === 'ledger'
+                        ? LEDGER_NODE_DEFAULT_SIZE.width
+                        : 360,
               defaultHeight: type === 'html'
                 ? 640
                 : type === 'markdown'
                   ? MARKDOWN_NODE_DEFAULT_SIZE.height
                   : type === 'mcp-app'
                     ? MCP_APP_NODE_DEFAULT_SIZE.height
-                    : 200,
+                    : type === 'image'
+                      ? IMAGE_NODE_DEFAULT_SIZE.height
+                      : type === 'ledger'
+                        ? LEDGER_NODE_DEFAULT_SIZE.height
+                        : 200,
               fileMode: 'auto',
             });
             result = { ok: true, ...serializeCreatedNode(created.node) };

package/src/server/canvas-schema.ts

@@ -540,6 +540,7 @@ export function describeCanvasSchema(): {
       },
       components: clone(describeJsonRenderCatalog()),
       directives: [
+        { name: '$state', usage: '{ "$state": "/path/to/value" } — read a value from the state model by path (one-way). Use this to bind a value by path; there is no $path directive.' },
         { name: '$format', usage: '{ "$format": "currency"|"number"|"percent"|"date", "value": <num|state-ref>, "currency"?: "USD", "locale"?, "style"?, "options"? } — Intl-formatted string' },
         { name: '$math', usage: '{ "$math": "add"|"subtract"|"multiply"|"divide"|"mod"|"min"|"max"|"round"|"floor"|"ceil"|"abs", "a": <num>, "b"?: <num> }' },
         { name: '$concat', usage: '{ "$concat": [<value>, <value>, ...] } — join values into one string' },

package/src/server/index.ts

@@ -36,6 +36,8 @@ import {
   createCanvasStreamingJsonRenderNode,
   MARKDOWN_NODE_DEFAULT_SIZE,
   MCP_APP_NODE_DEFAULT_SIZE,
+  IMAGE_NODE_DEFAULT_SIZE,
+  LEDGER_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   arrangeCanvasNodes,
   clearCanvas,
@@ -186,6 +188,11 @@ export class PmxCanvas extends EventEmitter {
     this._server = null;
   }
 
+  /**
+   * Add a node to the canvas and return the created node (including its `id`,
+   * resolved geometry, and data). Destructure `const { id } = canvas.addNode(...)`
+   * or keep the whole node — both work. (Previously returned a bare id string.)
+   */
   addNode(input: {
     type: CanvasNodeState['type'];
     title?: string;
@@ -205,12 +212,12 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): string {
+  }): CanvasNodeState {
     if (input.type === 'webpage') {
       throw new Error('Use addWebpageNode for webpage nodes so page content is fetched and cached on the server.');
     }
     if (input.type === 'group') {
-      return this.createGroup({
+      const groupId = this.createGroup({
         ...(typeof input.title === 'string' ? { title: input.title } : {}),
         childIds: input.childIds ?? input.children ?? [],
         ...(typeof input.x === 'number' ? { x: input.x } : {}),
@@ -220,6 +227,9 @@ export class PmxCanvas extends EventEmitter {
         ...(typeof input.color === 'string' ? { color: input.color } : {}),
         ...(input.childLayout ? { childLayout: input.childLayout } : {}),
       });
+      const groupNode = canvasState.getNode(groupId);
+      if (!groupNode) throw new Error(`Group node "${groupId}" was not created.`);
+      return groupNode;
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
@@ -227,12 +237,20 @@ export class PmxCanvas extends EventEmitter {
         ? MARKDOWN_NODE_DEFAULT_SIZE.width
         : input.type === 'mcp-app'
           ? MCP_APP_NODE_DEFAULT_SIZE.width
-          : 360,
+          : input.type === 'image'
+            ? IMAGE_NODE_DEFAULT_SIZE.width
+            : input.type === 'ledger'
+              ? LEDGER_NODE_DEFAULT_SIZE.width
+              : 360,
       defaultHeight: input.type === 'markdown'
         ? MARKDOWN_NODE_DEFAULT_SIZE.height
         : input.type === 'mcp-app'
           ? MCP_APP_NODE_DEFAULT_SIZE.height
-          : 200,
+          : input.type === 'image'
+            ? IMAGE_NODE_DEFAULT_SIZE.height
+            : input.type === 'ledger'
+              ? LEDGER_NODE_DEFAULT_SIZE.height
+              : 200,
       fileMode: 'path',
       ...(input.strictSize ? { strictSize: true } : {}),
     });
@@ -245,7 +263,9 @@ export class PmxCanvas extends EventEmitter {
       });
     }
 
-    return id;
+    const node = canvasState.getNode(id);
+    if (!node) throw new Error(`Node "${id}" was not created.`);
+    return node;
   }
 
   async addWebpageNode(input: {

package/src/server/server.ts

@@ -93,6 +93,8 @@ import {
   addCanvasEdge,
   MARKDOWN_NODE_DEFAULT_SIZE,
   MCP_APP_NODE_DEFAULT_SIZE,
+  IMAGE_NODE_DEFAULT_SIZE,
+  LEDGER_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   appendCanvasJsonRenderStream,
   buildStructuredNodeUpdate,
@@ -1506,7 +1508,13 @@ async function handleCanvasImage(pathname: string): Promise<Response> {
   if (!src || src.startsWith('data:') || src.startsWith('http')) {
     return responseText('Not a file-based image', 400);
   }
-  const safePath = resolve(src);
+  // Contain the file read to the active workspace. `src` comes from node data,
+  // which any unauthenticated local caller can set — without this guard the
+  // image route serves arbitrary host files (e.g. ../../etc/passwd).
+  const safePath = resolveWorkspaceArtifactPath(src);
+  if (!safePath) {
+    return responseText('Image path is outside the workspace', 403);
+  }
   if (!existsSync(safePath)) {
     return responseText('Image file not found', 404);
   }
@@ -1699,14 +1707,22 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
           ? MARKDOWN_NODE_DEFAULT_SIZE.width
           : type === 'mcp-app'
             ? MCP_APP_NODE_DEFAULT_SIZE.width
-            : 360,
+            : type === 'image'
+              ? IMAGE_NODE_DEFAULT_SIZE.width
+              : type === 'ledger'
+                ? LEDGER_NODE_DEFAULT_SIZE.width
+                : 360,
       defaultHeight: type === 'html'
         ? 640
         : type === 'markdown'
           ? MARKDOWN_NODE_DEFAULT_SIZE.height
           : type === 'mcp-app'
             ? MCP_APP_NODE_DEFAULT_SIZE.height
-            : 200,
+            : type === 'image'
+              ? IMAGE_NODE_DEFAULT_SIZE.height
+              : type === 'ledger'
+                ? LEDGER_NODE_DEFAULT_SIZE.height
+                : 200,
       fileMode: 'auto',
     });
   } catch (error) {
@@ -2072,6 +2088,10 @@ async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
       ...(typeof body.outputPath === 'string'
         ? { outputPath: resolveWorkspacePath(body.outputPath, activeWorkspaceRoot) }
         : {}),
+      // Script-path overrides are honored only when contained inside the
+      // workspace (enforced by resolveTrustedScriptPath in
+      // executeWebArtifactBuild), so they cannot point at an arbitrary host
+      // script for bash execution.
       ...(typeof body.initScriptPath === 'string'
         ? { initScriptPath: body.initScriptPath }
         : {}),