pmx-canvas 0.1.7 → 0.1.9

package/dist/types/client/canvas/auto-fit.d.ts

@@ -0,0 +1,5 @@
+import type { CanvasNodeState } from '../types';
+export declare const AUTO_FIT_MAX_HEIGHT = 600;
+export declare const AUTO_FIT_TITLEBAR_HEIGHT = 37;
+export declare function shouldAutoFitNode(node: CanvasNodeState): boolean;
+export declare function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null;

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -5,6 +5,8 @@ type IframeLoadTarget = Pick<HTMLIFrameElement, 'addEventListener' | 'removeEven
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
 interface ExtAppHostDimensionsTarget {
+    clientWidth?: number;
+    clientHeight?: number;
     getBoundingClientRect(): Pick<DOMRectReadOnly, 'width' | 'height'>;
 }
 export declare function waitForExtAppFrameLoad(target: IframeLoadTarget): Promise<void>;

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,9 +44,11 @@ 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;
+export declare function buildGraphConfig(input: GraphNodeInput): Record<string, unknown>;
 export declare function createJsonRenderNodeData(nodeId: string, title: string, spec: JsonRenderSpec, extra?: Record<string, unknown>): Record<string, unknown>;
 export declare function buildJsonRenderViewerHtml(options: {
     title: string;

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

@@ -2,6 +2,38 @@ import { type CanvasEdge, type CanvasNodeState, type CanvasNodeUpdate, type Canv
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
+export interface CanvasFitViewOptions {
+    width?: number;
+    height?: number;
+    padding?: number;
+    maxScale?: number;
+    nodeIds?: string[];
+}
+export interface CanvasFitViewResult {
+    ok: true;
+    viewport: {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    nodeCount: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+export interface CanvasGraphNodeUpdateInput extends Partial<GraphNodeInput> {
+    spec?: unknown;
+    type?: string;
+}
+export interface CanvasStructuredNodeUpdateInput extends Omit<CanvasGraphNodeUpdateInput, 'data'> {
+    content?: unknown;
+    data?: unknown;
+    arrangeLocked?: unknown;
+    chartHeight?: unknown;
+}
 interface CanvasAddNodeInput {
     type: CanvasNodeState['type'];
     title?: string;
@@ -34,6 +66,22 @@ interface CanvasNodeLookupInput {
     id?: string;
     search?: string;
 }
+export declare function hasStructuredNodeUpdateFields(input: Record<string, unknown>): boolean;
+export declare function buildStructuredNodeUpdate(node: CanvasNodeState, input: CanvasStructuredNodeUpdateInput): {
+    data: Record<string, unknown>;
+};
+export declare function buildJsonRenderNodeUpdate(node: CanvasNodeState, input: {
+    title?: string;
+    spec: unknown;
+}): {
+    data: Record<string, unknown>;
+    spec: JsonRenderSpec;
+};
+export declare function buildGraphNodeUpdate(node: CanvasNodeState, input: CanvasGraphNodeUpdateInput): {
+    data: Record<string, unknown>;
+    spec: JsonRenderSpec;
+    graphConfig: Record<string, unknown>;
+};
 export declare function primeCanvasRuntimeBackends(options?: {
     forceRehydrateExtApps?: boolean;
 }): {
@@ -144,6 +192,7 @@ export declare function createCanvasGraphNode(input: GraphNodeInput): {
     spec: JsonRenderSpec;
     node: CanvasNodeState;
 };
+export declare function fitCanvasView(options?: CanvasFitViewOptions): CanvasFitViewResult;
 export declare function executeCanvasBatch(operations: CanvasBatchOperation[]): Promise<{
     ok: boolean;
     results: Array<Record<string, unknown>>;

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

@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:events';
 import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
+import { fitCanvasView } from './canvas-operations.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
@@ -48,7 +49,7 @@ export declare class PmxCanvas extends EventEmitter {
         id: string;
         error?: string;
     }>;
-    updateNode(id: string, patch: Partial<CanvasNodeState>): void;
+    updateNode(id: string, patch: Partial<CanvasNodeState> & Record<string, unknown>): void;
     removeNode(id: string): void;
     addEdge(input: {
         from?: string;
@@ -89,6 +90,13 @@ export declare class PmxCanvas extends EventEmitter {
         focused: string;
         panned: boolean;
     } | null;
+    fitView(options?: {
+        width?: number;
+        height?: number;
+        padding?: number;
+        maxScale?: number;
+        nodeIds?: string[];
+    }): ReturnType<typeof fitCanvasView>;
     getLayout(): CanvasLayout;
     getNode(id: string): CanvasNodeState | undefined;
     search(query: string): ReturnType<typeof searchNodes>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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

@@ -143,6 +143,8 @@ pmx-canvas search "auth"
 pmx-canvas open
 pmx-canvas arrange --layout flow
 pmx-canvas focus <node-id> --no-pan             # Select/raise without moving the user's viewport
+pmx-canvas fit --width 1440 --height 900        # Fit the whole board for screenshots/review
+pmx-canvas node update <node-id> --spec-file ./dashboard.json
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
 pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
 pmx-canvas node list --type web-artifact --summary
@@ -167,6 +169,7 @@ pmx-canvas spatial
   `"DVT O3"` can be ambiguous; prefer the full visible title such as `"DVT O3 — GitOps"`.
 - `search`, `layout`, `status`, `arrange`, `focus` — inspect and navigate the canvas. Prefer
   `focus --no-pan` when you only need to select/raise a node without hijacking the human's camera.
+- `fit [id ...]` — set the server viewport to fit the whole canvas or selected nodes before screenshots or whole-board review
 - `open` — open the current workbench in the browser
 - `pin --list|--clear|<ids...>` — manage context pins
 - `undo`, `redo`, `history` — time travel
@@ -270,6 +273,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
@@ -278,7 +282,9 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 
 **`canvas_update_node`** — Update an existing node
 - `id` (required): node to update
-- Any of: `title`, `content`, `color`, `x`, `y`, `width`, `height`, `collapsed`, `metadata`
+- Any of: `title`, `content`, `x`, `y`, `width`, `height`, `collapsed`, `arrangeLocked`, `data`
+- For `json-render`, pass `spec` to update the rendered spec in place while preserving node ID, edges, pins, and position
+- For `graph`, pass graph fields such as `graphType`, `data`, `xKey`, `yKey`, `color`, and `chartHeight` to rebuild the chart in place; use `height`/`nodeHeight` for frame geometry and `chartHeight` for chart content in CLI flows
 - Use to update status nodes as work progresses
 
 **`canvas_remove_node`** — Remove a node and all its connected edges
@@ -306,8 +312,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`,
@@ -355,6 +362,10 @@ ID extraction for mixed tool responses:
 - Returns the normalized json-render spec the server would accept
 - Use this when you want a dry run before creating a `json-render` or `graph` node
 
+**`canvas_fit_view`** — Fit viewport to all nodes or selected nodes
+- Optional: `width`, `height`, `padding`, `maxScale`, `nodeIds`
+- Use before screenshot workflows or whole-board review so the server viewport matches the intended camera
+
 **Batch graph creation**
 - Use `graph.add` inside `canvas_batch` / `pmx-canvas batch` when you need a graph node as part of
   a larger one-shot build.
@@ -510,6 +521,8 @@ tools below operate on the live canvas state.
 - 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
+- Do not use `fetch()` inside `canvas_evaluate` to call PMX HTTP APIs; WebView security/CORS
+  restrictions can block those requests. Use the matching MCP tools instead.
 - Example: read the count of rendered `.canvas-node` elements:
 
   ```typescript
@@ -664,6 +677,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | POST | `/api/canvas/group/ungroup` | Ungroup |
 | POST | `/api/canvas/arrange` | Auto-arrange |
 | POST | `/api/canvas/focus` | Center viewport on node |
+| POST | `/api/canvas/fit` | Fit viewport to canvas bounds or selected nodes |
 | POST | `/api/canvas/clear` | Clear canvas |
 | POST | `/api/canvas/update` | Batch update positions |
 | GET | `/api/canvas/spatial-context` | Spatial clusters and reading order |

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/skills/published-consumer-e2e/scripts/run-published-consumer-e2e.sh

@@ -144,7 +144,7 @@ for _ in $(seq 1 120); do
 
   NODE_COUNT="$(
     curl -fsS "http://127.0.0.1:${PORT}/api/canvas/state" \
-      | "${BUN_BIN}" -e 'let raw="";for await (const chunk of Bun.stdin.stream()){raw+=chunk instanceof Uint8Array ? Buffer.from(chunk).toString() : String(chunk);} const state=JSON.parse(raw); console.log(state.nodes.length);'
+      | python3 -c 'import json, sys; print(len(json.load(sys.stdin).get("nodes", [])))'
   )"
 
   if [[ "${NODE_COUNT}" -ge 18 ]]; then

package/skills/web-artifacts-builder/scripts/bundle-artifact.sh

@@ -109,6 +109,17 @@ function ensure_bundle_dependencies() {
     fi
   done
 
+  # package.json lists the deps, but node_modules may not be in sync (e.g. fresh
+  # CI checkout where node_modules is gitignored). Run a regular install so the
+  # local binaries actually exist before we hand off to Parcel. The build
+  # allowlist is already persisted in package.json's pnpm.onlyBuiltDependencies
+  # by the original `pnpm add` step, so plain `install` is enough here.
+  if [ ! -x "./node_modules/.bin/parcel" ]; then
+    echo "📦 Syncing bundling dependencies into node_modules..."
+    run_pnpm_quiet install
+    return 0
+  fi
+
   echo "✅ Reusing existing bundling dependencies"
 }
 

package/src/cli/agent.ts

@@ -503,6 +503,41 @@ async function readTextInput(
   die(options.requiredMessage, options.hint);
 }
 
+async function readOptionalTextInput(
+  flags: Record<string, string | true>,
+  options: {
+    fileFlags?: string[];
+    valueFlags?: string[];
+    allowStdin?: boolean;
+    label: string;
+    hint: string;
+  },
+): Promise<string | undefined> {
+  for (const name of options.fileFlags ?? []) {
+    const path = getStringFlag(flags, name);
+    if (!path) continue;
+    try {
+      return readFileSync(path, 'utf-8');
+    } catch (error) {
+      die(
+        `Unable to read --${name}: ${error instanceof Error ? error.message : String(error)}`,
+        options.hint,
+      );
+    }
+  }
+
+  for (const name of options.valueFlags ?? []) {
+    const value = getStringFlag(flags, name);
+    if (value !== undefined) return value;
+  }
+
+  if (options.allowStdin && flags.stdin) {
+    return await readStdin();
+  }
+
+  return undefined;
+}
+
 function applyCommonGeometryFlags(
   body: Record<string, unknown>,
   flags: Record<string, string | true>,
@@ -518,15 +553,33 @@ function applyCommonGeometryFlags(
   if (height !== undefined) body.height = height;
 }
 
+async function applyStructuredNodeUpdateFlags(
+  body: Record<string, unknown>,
+  flags: Record<string, string | true>,
+): Promise<void> {
+  const specRaw = await readOptionalTextInput(flags, {
+    fileFlags: ['spec-file'],
+    valueFlags: ['spec-json'],
+    allowStdin: false,
+    label: 'JSON spec',
+    hint: 'Use: pmx-canvas node update <node-id> --spec-file ./new-spec.json',
+  });
+  if (specRaw !== undefined) {
+    body.spec = parseJsonValue(specRaw, 'JSON spec', 'Use: pmx-canvas node update <node-id> --spec-file ./new-spec.json');
+  }
+
+  const graphPatch = await buildGraphRequestBody(flags, { requireData: false, allowStdin: false });
+  for (const [key, value] of Object.entries(graphPatch)) {
+    body[key === 'height' ? 'chartHeight' : key] = value;
+  }
+}
+
 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 +591,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',
@@ -550,23 +603,30 @@ async function buildJsonRenderRequestBody(
 
 async function buildGraphRequestBody(
   flags: Record<string, string | true>,
+  options: { requireData?: boolean; allowStdin?: boolean } = {},
 ): Promise<Record<string, unknown>> {
+  const requireData = options.requireData !== false;
+  const allowStdin = options.allowStdin !== false;
   const hint =
     'Use: pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value';
-  const rawData = await readTextInput(flags, {
+
+  const body: Record<string, unknown> = {
+    ...(requireData ? { graphType: getStringFlag(flags, 'graph-type', 'graphType') ?? 'line' } : {}),
+  };
+  const rawData = await readOptionalTextInput(flags, {
     fileFlags: ['data-file'],
     valueFlags: ['data-json', 'data'],
-    allowStdin: true,
+    allowStdin,
     label: 'graph JSON dataset',
     hint,
-    requiredMessage: 'Graph nodes require --data-file, --data-json, --data, or --stdin JSON data.',
   });
-  const data = parseRecordArrayJson(rawData, hint);
-
-  const body: Record<string, unknown> = {
-    graphType: getStringFlag(flags, 'graph-type', 'graphType') ?? 'line',
-    data,
-  };
+  if (rawData !== undefined) {
+    body.data = parseRecordArrayJson(rawData, hint);
+  } else if (requireData) {
+    die('Graph nodes require --data-file, --data-json, --data, or --stdin JSON data.', hint);
+  }
+  const graphType = getStringFlag(flags, 'graph-type', 'graphType');
+  if (graphType) body.graphType = graphType;
   if (typeof flags.title === 'string') body.title = flags.title;
   const xKey = getStringFlag(flags, 'x-key', 'xKey');
   const yKey = getStringFlag(flags, 'y-key', 'yKey');
@@ -985,8 +1045,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;
   }
@@ -1151,6 +1214,8 @@ cmd('node update', 'Update a node by ID', [
   'pmx-canvas node update <node-id> --content "Updated content"',
   'pmx-canvas node update <node-id> --title "Moved" --x 500 --y 300',
   'pmx-canvas node update <node-id> --width 840 --height 620',
+  'pmx-canvas node update <node-id> --spec-file ./dashboard.json',
+  'pmx-canvas node update <graph-id> --data-file ./metrics.json --chart-height 420',
   'pmx-canvas node update <node-id> --lock-arrange',
 ], async (args) => {
   const { positional, flags } = parseFlags(args);
@@ -1160,6 +1225,7 @@ cmd('node update', 'Update a node by ID', [
   if (!id) die('Missing node ID', 'pmx-canvas node update <node-id> --title "New Title"');
 
   const body: Record<string, unknown> = {};
+  await applyStructuredNodeUpdateFlags(body, flags);
   if (flags.title && flags.title !== true) body.title = flags.title;
   if (flags.content && flags.content !== true) body.content = flags.content;
   if (flags.stdin) body.content = await readStdin();
@@ -1199,10 +1265,7 @@ cmd('node update', 'Update a node by ID', [
     }
 
     if (arrangeLocked !== undefined) {
-      body.data = {
-        ...existing.data,
-        arrangeLocked,
-      };
+      body.arrangeLocked = arrangeLocked;
     }
   }
 
@@ -1396,6 +1459,29 @@ cmd('focus', 'Pan viewport to center on a node', [
   output(result);
 });
 
+cmd('fit', 'Fit the viewport to all nodes or a selected subset', [
+  'pmx-canvas fit',
+  'pmx-canvas fit --width 1440 --height 900 --padding 80',
+  'pmx-canvas fit node-a node-b',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('fit');
+
+  const body: Record<string, unknown> = {};
+  const width = optionalPositiveFiniteFlag(flags, 'width', 'Use a positive number, e.g. --width 1440');
+  const height = optionalPositiveFiniteFlag(flags, 'height', 'Use a positive number, e.g. --height 900');
+  const padding = optionalPositiveFiniteFlag(flags, 'padding', 'Use a positive number, e.g. --padding 80');
+  const maxScale = optionalPositiveFiniteFlag(flags, 'max-scale', 'Use a positive number, e.g. --max-scale 1');
+  if (width !== undefined) body.width = width;
+  if (height !== undefined) body.height = height;
+  if (padding !== undefined) body.padding = padding;
+  if (maxScale !== undefined) body.maxScale = maxScale;
+  if (positional.length > 0) body.nodeIds = positional;
+
+  const result = await api('POST', '/api/canvas/fit', body);
+  output(result);
+});
+
 // ── external-app add ─────────────────────────────────────────
 cmd('external-app add', 'Create a hosted external app node', [
   'pmx-canvas external-app add --kind excalidraw --title "Diagram"',
@@ -1816,7 +1902,7 @@ cmd('webview start', 'Start or replace the Bun.WebView automation session', [
     if (chromeArgv.length > 0) body.chromeArgv = chromeArgv;
   }
 
-  const result = await api('POST', '/api/workbench/webview/start', body);
+  const result = await api('POST', '/api/workbench/webview/start', body, { allowErrorJson: true });
   output(result);
 });
 
@@ -2112,6 +2198,13 @@ function showCommandHelp(name: string): void {
     console.log('\nViewport:');
     console.log('  --no-pan                  Select/raise the node without moving the viewport');
   }
+  if (name === 'fit') {
+    console.log('\nViewport:');
+    console.log('  --width <px>              Viewport width used for fit math (default 1440)');
+    console.log('  --height <px>             Viewport height used for fit math (default 900)');
+    console.log('  --padding <px>            World-space padding around fitted nodes (default 60)');
+    console.log('  --max-scale <scale>       Maximum zoom scale (default 1)');
+  }
   if (name === 'external-app add') {
     console.log('\nOptions:');
     console.log('  --kind excalidraw          External app kind to create');
@@ -2161,6 +2254,7 @@ Canvas commands:
   pmx-canvas validate spec            Validate json-render/graph payloads without creating nodes
   pmx-canvas watch [options]          Watch semantic canvas changes over SSE
   pmx-canvas focus <id>               Pan viewport to node
+  pmx-canvas fit [id ...]             Fit viewport to canvas or selected nodes
   pmx-canvas external-app add          Add hosted external apps like Excalidraw
   pmx-canvas webview status           Show WebView automation status
   pmx-canvas webview start [options]  Start or replace automation session
@@ -2222,6 +2316,7 @@ Examples:
   pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
   pmx-canvas search "authentication"
   pmx-canvas open
+  pmx-canvas fit --width 1440 --height 900
   pmx-canvas layout --summary
   pmx-canvas arrange --layout column
   pmx-canvas batch --file ./canvas-ops.json

package/src/client/canvas/CanvasNode.tsx

@@ -28,6 +28,7 @@ import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-brid
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
+import { computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
 import { activeGuides, buildSnapCache, clearSnapCache, snapToGuides } from './snap-guides';
 import { useNodeDrag } from './use-node-drag';
 import { useNodeResize } from './use-node-resize';
@@ -141,12 +142,9 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
   const bodyRef = useRef<HTMLDivElement>(null);
   const hasAutoFit = useRef(false);
   const autoFitPersistTimer = useRef<number | null>(null);
-  const AUTO_FIT_MAX = 600;
-  const TITLEBAR_HEIGHT = 37;
-  const isExtAppNode = node.type === 'mcp-app' && node.data.mode === 'ext-app';
 
   useEffect(() => {
-    if (hasAutoFit.current || node.collapsed || node.dockPosition || node.type === 'group' || isExtAppNode) return;
+    if (hasAutoFit.current || !shouldAutoFitNode(node)) return;
     const body = bodyRef.current;
     if (!body) return;
 
@@ -156,9 +154,9 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
         return;
       }
       const contentHeight = body.scrollHeight;
-      if (contentHeight <= 0) return;
+      const fitHeight = computeAutoFitHeight(node, contentHeight);
+      if (fitHeight === null) return;
 
-      const fitHeight = Math.min(contentHeight + TITLEBAR_HEIGHT, AUTO_FIT_MAX);
       // Only resize if the fit height differs meaningfully from current
       if (Math.abs(fitHeight - node.size.height) > 8) {
         resizeNode(node.id, { width: node.size.width, height: fitHeight });
@@ -181,7 +179,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
         autoFitPersistTimer.current = null;
       }
     };
-  }, [node.id, node.type, isExtAppNode, node.collapsed, node.dockPosition, node.size.width, node.size.height]);
+  }, [node.id, node.type, node.data.mode, node.collapsed, node.dockPosition, node.size.width, node.size.height]);
 
   const isPinned = node.pinned;
   const isTrace = node.type === 'trace';

package/src/client/canvas/auto-fit.ts

@@ -0,0 +1,21 @@
+import type { CanvasNodeState } from '../types';
+
+export const AUTO_FIT_MAX_HEIGHT = 600;
+export const AUTO_FIT_TITLEBAR_HEIGHT = 37;
+
+function isExtAppNode(node: CanvasNodeState): boolean {
+  return node.type === 'mcp-app' && node.data.mode === 'ext-app';
+}
+
+function hasExplicitStructuredFrame(node: CanvasNodeState): boolean {
+  return (node.type === 'graph' || node.type === 'json-render') && node.size.height > AUTO_FIT_MAX_HEIGHT;
+}
+
+export function shouldAutoFitNode(node: CanvasNodeState): boolean {
+  return !node.collapsed && !node.dockPosition && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node);
+}
+
+export function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null {
+  if (!shouldAutoFitNode(node) || contentHeight <= 0) return null;
+  return Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT, AUTO_FIT_MAX_HEIGHT);
+}

package/src/client/nodes/ExtAppFrame.tsx

@@ -23,6 +23,8 @@ type DisplayMode = 'inline' | 'fullscreen' | 'pip';
 const DEFAULT_EXT_APP_SANDBOX = 'allow-scripts allow-popups allow-popups-to-escape-sandbox';
 
 interface ExtAppHostDimensionsTarget {
+  clientWidth?: number;
+  clientHeight?: number;
   getBoundingClientRect(): Pick<DOMRectReadOnly, 'width' | 'height'>;
 }
 
@@ -120,8 +122,8 @@ export function resolveExtAppContainerDimensions(
 ): { width: number; height: number } {
   const rect = target?.getBoundingClientRect();
   return {
-    width: positiveDimension(rect?.width ?? 0, fallback.width),
-    height: positiveDimension(rect?.height ?? 0, fallback.height),
+    width: positiveDimension(target?.clientWidth ?? 0, positiveDimension(rect?.width ?? 0, fallback.width)),
+    height: positiveDimension(target?.clientHeight ?? 0, positiveDimension(rect?.height ?? 0, fallback.height)),
   };
 }