pmx-canvas 0.1.27 → 0.1.29

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

@@ -21,8 +21,19 @@ export declare class PmxCanvas extends EventEmitter {
     start(options?: {
         open?: boolean;
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
+        /**
+         * Bind a nearby free port when the preferred one is taken instead of
+         * failing. Default false (an explicit SDK port is honored exactly); the
+         * MCP auto-start opts in so a daemon already on the port can't crash it.
+         */
+        allowPortFallback?: boolean;
     }): 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 +53,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.29",
   "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);
@@ -1061,11 +1082,24 @@ const RESOURCE_COMMAND_ALIASES: Record<string, Record<string, string>> = {
     delete: 'remove',
     rm: 'remove',
   },
+  ax: {
+    // Single-subcommand AX groups: the bare verb maps to its only action so
+    // `ax event` / `ax evidence` suggest the full command instead of erroring.
+    event: 'event add',
+    evidence: 'evidence add',
+  },
 };
 const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
   node: {
     pin: 'Use the top-level pin command instead: pmx-canvas pin <node-id>',
   },
+  ax: {
+    // Multi-subcommand AX groups: point at the available actions.
+    host: 'Pick an action: pmx-canvas ax host report | pmx-canvas ax host status',
+    work: 'Pick an action: pmx-canvas ax work add | update | list',
+    approval: 'Pick an action: pmx-canvas ax approval request | resolve | list',
+    review: 'Pick an action: pmx-canvas ax review add | list',
+  },
 };
 
 function cmd(

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/client/nodes/LedgerNode.tsx

@@ -1,12 +1,25 @@
 import type { CanvasNodeState } from '../types';
 
+// Layout/internal metadata that lives in node.data but is not ledger content.
+const HIDDEN_LEDGER_KEYS = new Set(['title', '__type', 'content', 'strictSize', 'arrangeLocked']);
+
 export function LedgerNode({ node }: { node: CanvasNodeState }) {
   const data = node.data as Record<string, unknown>;
 
-  // Render key-value pairs from ledger summary
-  const entries = Object.entries(data).filter(([key]) => key !== 'title' && key !== '__type');
+  // Body text renders as a log: one line per entry. CLI flags frequently deliver
+  // a literal "\n" (backslash-n, the shell does not expand it inside quotes)
+  // rather than a real newline, so split on both — plus CR/CRLF — instead of
+  // dropping the whole string on one wrapped line.
+  const rawContent = typeof data.content === 'string' ? data.content : '';
+  const lines = rawContent
+    .split(/\r\n|\r|\n|\\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+
+  // Any remaining non-internal keys render as structured key/value rows.
+  const entries = Object.entries(data).filter(([key]) => !HIDDEN_LEDGER_KEYS.has(key));
 
-  if (entries.length === 0) {
+  if (lines.length === 0 && entries.length === 0) {
     return (
       <div style={{ color: 'var(--c-dim)', fontSize: '12px', fontStyle: 'italic' }}>No ledger data</div>
     );
@@ -14,20 +27,41 @@ export function LedgerNode({ node }: { node: CanvasNodeState }) {
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '4px', fontSize: '12px' }}>
+      {lines.length > 0 && (
+        <div style={{ display: 'flex', flexDirection: 'column' }}>
+          {lines.map((line, i) => (
+            <div
+              key={i}
+              style={{
+                padding: '3px 0',
+                borderBottom: i < lines.length - 1 ? '1px solid rgba(45,55,90,0.3)' : 'none',
+                color: 'var(--c-text)',
+                fontFamily: 'var(--mono)',
+                fontSize: '11px',
+                whiteSpace: 'pre-wrap',
+                wordBreak: 'break-word',
+              }}
+            >
+              {line}
+            </div>
+          ))}
+        </div>
+      )}
       {entries.map(([key, value]) => (
         <div
           key={key}
           style={{
             display: 'flex',
             justifyContent: 'space-between',
+            gap: '8px',
             padding: '3px 0',
             borderBottom: '1px solid rgba(45,55,90,0.3)',
           }}
         >
-          <span style={{ color: 'var(--c-muted)', fontSize: '11px' }}>
+          <span style={{ color: 'var(--c-muted)', fontSize: '11px', flexShrink: 0 }}>
             {key.replace(/([A-Z])/g, ' $1').replace(/^./, (s) => s.toUpperCase())}
           </span>
-          <span style={{ color: 'var(--c-text)', fontFamily: 'var(--mono)', fontSize: '11px' }}>
+          <span style={{ color: 'var(--c-text)', fontFamily: 'var(--mono)', fontSize: '11px', textAlign: 'right', wordBreak: 'break-word' }}>
             {typeof value === 'object' ? JSON.stringify(value) : String(value ?? '—')}
           </span>
         </div>

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) {
@@ -545,6 +563,20 @@ function collectDataKeys(data: Array<Record<string, unknown>>): Set<string> {
   return keys;
 }
 
+/**
+ * Pick the first candidate key that actually exists in the data. Lets a chart
+ * accept a conventional synonym (e.g. a bullet chart's "actual" measure as well
+ * as "value") without an explicit valueKey, instead of failing the data-key
+ * check on a reasonable guess.
+ */
+function firstPresentDataKey(
+  data: Array<Record<string, unknown>>,
+  candidates: string[],
+): string | undefined {
+  const keys = collectDataKeys(data);
+  return candidates.find((key) => keys.has(key));
+}
+
 function assertGraphDataKeys(
   data: Array<Record<string, unknown>>,
   chartType: GraphChartType,
@@ -711,7 +743,10 @@ export function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec {
     }
     case 'BulletChart': {
       chartProps.labelKey = input.labelKey ?? input.xKey ?? null;
-      chartProps.valueKey = input.valueKey ?? input.yKey ?? 'value';
+      // The measure column is conventionally "value", but bullet charts also
+      // call it "actual" — accept either when no valueKey is given.
+      chartProps.valueKey =
+        input.valueKey ?? input.yKey ?? firstPresentDataKey(input.data, ['value', 'actual']) ?? 'value';
       chartProps.targetKey = input.targetKey ?? null;
       chartProps.rangesKey = input.rangesKey ?? null;
       chartProps.color = input.color ?? null;

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']>>> {
@@ -1061,7 +1063,23 @@ export async function createCanvasAccess(): Promise<CanvasAccess> {
   const remoteBaseUrl = await findExistingCanvasServer(workspaceRoot, port);
   if (remoteBaseUrl) return new RemoteCanvasAccess(remoteBaseUrl);
 
+  // No same-workspace server to attach to. Allow a port fallback so a daemon
+  // already holding the preferred port (e.g. one serving a *different*
+  // workspace) doesn't crash this MCP/SDK session with EADDRINUSE — start our
+  // own canvas on a free port instead, and explain how to share one if intended.
   const canvas = createCanvas({ port });
-  await canvas.start({ open: true });
+  await canvas.start({ open: true, allowPortFallback: true });
+  const boundPort = canvas.port;
+  if (boundPort !== port) {
+    const occupant = await readHealth(`http://127.0.0.1:${port}`);
+    const occupantWorkspace =
+      typeof occupant?.workspace === 'string' ? ` (serving ${occupant.workspace})` : '';
+    // stderr only — stdout is the MCP stdio JSON-RPC channel.
+    process.stderr.write(
+      `[pmx-canvas] preferred port ${port} was in use${occupantWorkspace}; ` +
+        `started this canvas on port ${boundPort} instead. To share one canvas, run the daemon ` +
+        `from this workspace or set PMX_CANVAS_URL / PMX_CANVAS_PORT to point at it.\n`,
+    );
+  }
   return new LocalCanvasAccess(canvas, workspaceRoot, port);
 }

package/src/mcp/server.ts

@@ -263,13 +263,16 @@ function compactBatchResult(result: { ok: boolean; results: Array<Record<string,
 }
 
 async function createdNodePayload(c: CanvasAccess, id: string, options: { full?: boolean; verbose?: boolean; includeData?: boolean } = {}): Promise<Record<string, unknown>> {
+  // Expose both `id` and a `nodeId` alias on every node-create response so
+  // agents using either key (or a cached schema) work — matching the
+  // external-app / web-artifact responses that already return both.
   const node = await c.getNode(id);
-  if (!node) return { ok: true, id };
+  if (!node) return { ok: true, id, nodeId: id };
   if (!wantsFullPayload(options)) {
-    return { ok: true, node: compactNodePayload(node), id };
+    return { ok: true, node: compactNodePayload(node), id, nodeId: id };
   }
   const serialized = serializeCanvasNodeForAgent(node);
-  return { ok: true, node: serialized, ...serialized };
+  return { ok: true, node: serialized, ...serialized, nodeId: node.id };
 }
 
 function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
@@ -764,8 +767,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) };