pmx-canvas 0.1.27 → 0.1.29

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,
@@ -128,8 +130,14 @@ export class PmxCanvas extends EventEmitter {
   async 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> {
-    const base = startCanvasServer({ port: this._port, allowPortFallback: false });
+    const base = startCanvasServer({ port: this._port, allowPortFallback: options?.allowPortFallback ?? false });
     if (!base) {
       throw new Error(`Failed to start canvas server on port ${this._port}`);
     }
@@ -186,6 +194,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 +218,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 +233,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 +243,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 +269,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 }
         : {}),

package/src/server/web-artifacts.ts

@@ -5,11 +5,12 @@ import {
   readdirSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   statSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ensureArtifactsDir, getWorkspaceRoot } from './artifact-paths.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
 import { findOpenCanvasPosition } from './placement.js';
@@ -338,6 +339,33 @@ async function runProcess(
   return { stdout: stdout.trim(), stderr: stderr.trim() };
 }
 
+/**
+ * Resolve the init/bundle script path. Without an override the trusted bundled
+ * resolver is used. An override (a test/debugging escape hatch exposed on every
+ * surface — CLI --init-script-path/--bundle-script-path, the MCP tool, the HTTP
+ * endpoint, and the SDK) is only honored when it resolves inside the active
+ * workspace root — otherwise it would let a caller exec an arbitrary host script
+ * via bash as the server user. This containment is the single chokepoint that
+ * makes forwarding the field safe across all of those surfaces.
+ */
+function resolveTrustedScriptPath(override: string | undefined, kind: 'init' | 'bundle'): string {
+  if (!override) return resolveWebArtifactScriptPath(kind);
+  const resolved = resolve(override);
+  // Compare real (symlink-resolved) paths on both sides so a legitimately
+  // contained override under a symlinked root (e.g. macOS /var -> /private/var,
+  // or a workspace that itself lives beneath a symlink) is not wrongly rejected.
+  // The candidate is realpath'd only when it exists; a non-existent escape path
+  // still fails the containment check below (or the existsSync guard at the call
+  // site). This keeps the guard strict — genuine escapes are still rejected.
+  const realRoot = realpathSync(currentWorkspaceRoot());
+  const realCandidate = existsSync(resolved) ? realpathSync(resolved) : resolved;
+  const workspaceRel = relative(realRoot, realCandidate);
+  if (workspaceRel === '..' || workspaceRel.startsWith(`..${sep}`) || isAbsolute(workspaceRel)) {
+    throw new Error(`Web-artifact ${kind} script override must resolve inside the workspace: ${override}`);
+  }
+  return resolved;
+}
+
 export function resolveWebArtifactScriptPath(kind: 'init' | 'bundle'): string {
   const scriptFile = kind === 'init' ? 'init-artifact.sh' : 'bundle-artifact.sh';
   const candidates = [
@@ -459,10 +487,8 @@ export async function executeWebArtifactBuild(
   const slug = slugify(input.title);
   const projectPath = resolve(input.projectPath ?? join(artifactsDir, '.web-artifacts', slug));
   const outputPath = resolve(input.outputPath ?? join(artifactsDir, `${slug}.html`));
-  const initScriptPath = resolve(input.initScriptPath ?? resolveWebArtifactScriptPath('init'));
-  const bundleScriptPath = resolve(
-    input.bundleScriptPath ?? resolveWebArtifactScriptPath('bundle'),
-  );
+  const initScriptPath = resolveTrustedScriptPath(input.initScriptPath, 'init');
+  const bundleScriptPath = resolveTrustedScriptPath(input.bundleScriptPath, 'bundle');
   const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
   if (!existsSync(initScriptPath)) {