pmx-canvas 0.3.4 → 0.4.0

package/skills/pmx-canvas/evals/evals.json

@@ -172,7 +172,7 @@
       "id": 7,
       "name": "snapshot-before-changes",
       "prompt": "I want to reorganize the canvas to explore a different approach, but I don't want to lose what's there now. Can you save the current state, clear it, and set up a fresh workspace for the new approach? If it doesn't work out I want to go back.",
-      "expected_output": "Takes a named snapshot of current state, then clears the canvas. Mentions that canvas_restore can bring back the old state. Does NOT just clear without snapshotting.",
+      "expected_output": "Takes a named snapshot of current state, then clears the canvas. Mentions that canvas_snapshot { action: \"restore\" } can bring back the old state. Does NOT just clear without snapshotting.",
       "assertions": [
         {
           "name": "takes-snapshot",
@@ -186,7 +186,7 @@
         },
         {
           "name": "mentions-restore",
-          "description": "Tells the user how to restore (canvas_restore) if they want to go back",
+          "description": "Tells the user how to restore (canvas_snapshot action restore) if they want to go back",
           "type": "output_check"
         }
       ]

package/skills/pmx-canvas/references/full-reference.md

@@ -73,7 +73,7 @@ section below.
 3. **Read before write** — `canvas_query { action: "search", query }` (or `pmx-canvas search`)
    to find existing nodes; avoid duplicates. Use `canvas_query { action: "layout" }` only when
    you need the full board.
-4. **Snapshot before destructive work** — `canvas_snapshot { name }` before clear/major
+4. **Snapshot before destructive work** — `canvas_snapshot { action: "save", name }` before clear/major
    reorg; restore if needed.
 5. **Signal then mutate (default behavior)** — signal with `canvas_intent { action: "signal", … }`
    to telegraph the move before nearly every mutation, then create with the right composite: `canvas_node` (markdown/status/file/webpage/html
@@ -315,6 +315,7 @@ pmx-canvas spatial
 - `group create|add|remove` — manage groups
 - `clear --yes` — destructive clear with explicit confirmation
 - `validate spec` — validate json-render specs and graph payloads without creating nodes
+- `node update` — returns a compact `{ ok, id, nodeId, position, size, updatedFields }` envelope by default; pass `--full` for the complete node payload. Full ext-app/mcp-app payloads embed the bundled app HTML and tool results (hundreds of KB — a no-op ext-app resize once returned ~940 KB), so in agent turns keep the default envelope and read content via `node get --summary`
 - `web-artifact build` — build bundled React/Tailwind HTML artifacts; use `--deps` for extra packages and `--include-logs` only when raw logs are useful. The build pipeline runs bash scripts (POSIX-only) — it is not supported on native Windows; already-built artifacts render everywhere
 - `external-app add --kind excalidraw` — create the hosted Excalidraw preset; response includes `id` and `nodeId` aliases for the same canvas node
 - `serve status|stop` — inspect and stop daemonized servers started with `serve --daemon`
@@ -429,7 +430,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 > registered — use the composites instead. The authoritative legacy→composite mapping table lives
 > in [`docs/mcp.md`](../../../docs/mcp.md) — this skill does not re-enumerate the removed names.
 
-### The 15 composites
+### The 16 composites
 
 | Composite | `action` values | What it does |
 |-----------|-----------------|--------------|
@@ -438,6 +439,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 | `canvas_edge` | `add` · `remove` | Connect / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
+| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
 | `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete a human-drawn annotation by id |
 | `canvas_query` | `search` · `layout` · `validate` | Find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
@@ -505,10 +507,9 @@ investigation board" intent, then run the batch with that linked `intentId` (use
 
 These stay separate by design (trust-boundary, firehose, execution-intent, or not-yet-consolidated
 surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`,
-`canvas_ingest_activity`, `canvas_invoke_command`, and the snapshot tools (`canvas_snapshot`,
-`canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`,
-`canvas_diff` — deprecated pending a `canvas_snapshot` composite in v0.4; the name collides with
-the current save-snapshot tool, so the composite cannot land additively).
+`canvas_ingest_activity`, `canvas_invoke_command`. Snapshots moved into the `canvas_snapshot`
+composite in v0.4.0 (actions `save | list | restore | delete | gc | diff`); the 6 legacy snapshot
+standalones were removed after their deprecated 0.3.x window.
 
 `canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
 `edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
@@ -650,7 +651,7 @@ ID extraction for mixed tool responses:
 
 **`canvas_pin_nodes`** (standalone) — Set, add, or remove pinned context nodes. Use `{ nodeIds: [...] }` — the field is `nodeIds`, not `ids`.
 
-**`canvas_diff`** (standalone) — Compare current canvas state with a saved snapshot. Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default.
+**`canvas_snapshot { action: "diff" }`** — Compare current canvas state with a saved snapshot. Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default.
 
 **`canvas_render { action: "describe-schema" }`** — Inspect the running server's create schemas and
 canonical examples. Use before generating structured payloads when you need the authoritative current
@@ -766,13 +767,14 @@ ranked matches with content snippets. Use instead of parsing the full layout to
 ### History & Snapshots
 
 - **`canvas_history { action: "undo" }`** / **`canvas_history { action: "redo" }`** — step the mutation ring buffer.
-- **`canvas_snapshot`** (standalone) — save a named snapshot; `name` required. Returns `{ ok, id, snapshot }` (flat `id` aliases `snapshot.id`).
-- **`canvas_restore`** (standalone) — restore from a snapshot `id`.
-- **`canvas_diff`** (standalone) — compare current canvas against a saved snapshot (added/removed/modified nodes & edges).
+- **`canvas_snapshot { action: "save", name }`** — save a named snapshot. Returns `{ ok, id, snapshot }` (flat `id` aliases `snapshot.id`).
+- **`canvas_snapshot { action: "list" }`** / **`{ action: "gc", keep }`** / **`{ action: "delete", id }`** — manage saved snapshots.
+- **`canvas_snapshot { action: "restore", id }`** — restore from a snapshot.
+- **`canvas_snapshot { action: "diff", snapshot }`** — compare current canvas against a saved snapshot (added/removed/modified nodes & edges). Note the field is `snapshot` (id or name), not `id`.
 
 ### Canvas Management
 
-**`canvas_view { action: "clear" }`** — Remove all nodes and edges. **Always `canvas_snapshot` first** —
+**`canvas_view { action: "clear" }`** — Remove all nodes and edges. **Always `canvas_snapshot { action: "save" }` first** —
 this is irreversible without a prior snapshot.
 
 ### Browser Automation (WebView)
@@ -1405,19 +1407,19 @@ Monitor ongoing processes:
 
 Show two states side by side for the human to compare:
 
-1. Take a snapshot before changes: `canvas_snapshot` with name "before-X"
+1. Take a snapshot before changes: `canvas_snapshot { action: "save" }` with name "before-X"
 2. Make changes to the canvas
-3. Use `canvas_diff` to show what changed
+3. Use `canvas_snapshot { action: "diff", snapshot }` to show what changed
 4. Or: create two groups ("Before" and "After") with corresponding nodes
 
 ### Save and Start Fresh
 
 When the human wants to explore a different approach without losing current work:
 
-1. **First**, save the current state: `canvas_snapshot` with a descriptive name
+1. **First**, save the current state: `canvas_snapshot { action: "save" }` with a descriptive name
 2. **Then** clear: `canvas_view { action: "clear" }` (never clear without snapshotting first)
 3. Set up the new workspace with initial nodes
-4. Tell the human the snapshot name and that `canvas_restore` can bring everything back
+4. Tell the human the snapshot name and that `canvas_snapshot { action: "restore" }` can bring everything back
 
 ## Best Practices
 

package/src/cli/commands/history.ts

@@ -193,7 +193,7 @@ cmd('snapshot delete', 'Delete a saved snapshot', ['pmx-canvas snapshot delete <
 });
 
 async function runSnapshotDiff(args: string[]): Promise<void> {
-  const { positional, flags } = parseFlags(args);
+  const { positional } = parseFlags(args);
   const snapshot = positional[0];
   if (!snapshot) die('Missing snapshot ID or name', 'pmx-canvas snapshot diff <snapshot-id-or-name>');
   const result = await invokeOperation('snapshot.diff', { id: snapshot });

package/src/cli/commands/nodes.ts

@@ -830,6 +830,7 @@ cmd(
     'pmx-canvas node update <node-id> --dock-position right',
     'pmx-canvas node update <node-id> --dock-position none   # undock back to the canvas',
     'pmx-canvas node update <node-id> --lock-arrange',
+    'pmx-canvas node update <node-id> --width 840 --full   # full node payload instead of the compact envelope',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -932,7 +933,36 @@ cmd(
     }
 
     const result = await invokeOperation('node.update', { id, ...body });
-    output(result);
+    if (flags.full || flags.verbose) {
+      output(result);
+      return;
+    }
+    // Finding R (0.3.4 report): the raw update result echoes the FULL node —
+    // ~940 KB for an ext-app (bundled html + tool result) — which can consume a
+    // large share of an agent turn for a simple resize. Default to a compact
+    // envelope; --full restores the complete response.
+    const updatedNode = isRecord(result) && isRecord(result.node) ? result.node : undefined;
+    // Raw geometry flags also land in the body alongside their structured
+    // position/size forms (the graph-patch builder copies them through); report
+    // only the canonical field once.
+    const structuredDupes: Record<string, string> = {
+      width: 'size',
+      height: 'size',
+      nodeHeight: 'size',
+      x: 'position',
+      y: 'position',
+    };
+    const updatedFields = Object.keys(body)
+      .filter((key) => !(structuredDupes[key] && body[structuredDupes[key]] !== undefined))
+      .sort();
+    output({
+      ok: isRecord(result) && result.ok !== undefined ? result.ok : true,
+      id,
+      nodeId: id,
+      ...(updatedNode && isRecord(updatedNode.position) ? { position: updatedNode.position } : {}),
+      ...(updatedNode && isRecord(updatedNode.size) ? { size: updatedNode.size } : {}),
+      updatedFields,
+    });
   },
 );
 

package/src/cli/index.ts

@@ -163,7 +163,10 @@ function runMcpServerProcess(): Promise<void> {
 const serveSubcommand = firstArg === 'serve' ? (args[1] ?? '') : '';
 
 if (firstArg === 'serve' && (serveSubcommand === 'status' || serveSubcommand === 'stop')) {
-  const port = parseInt(readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? '4313');
+  const port = parseInt(
+    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    10,
+  );
   const daemonLogFile = resolve(readOption('log-file') ?? `.pmx-canvas/daemon-${port}.log`);
   const daemonPidFile = resolve(readOption('pid-file') ?? `.pmx-canvas/daemon-${port}.pid`);
   const daemonWaitMs = readNumberOption('wait-ms') ?? 10_000;
@@ -208,7 +211,10 @@ if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
   await runMcpServerProcess();
 } else {
   // "serve" is also accessible via flags (backward compat)
-  const port = parseInt(readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? '4313');
+  const port = parseInt(
+    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    10,
+  );
   const demo = hasFlag('demo');
   const noOpen = hasFlag('no-open');
   const daemon = hasFlag('daemon');

package/src/cli/shared.ts

@@ -147,6 +147,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
     'json',
     'compact',
     'verbose',
+    'full',
     'include-logs',
     'no-pan',
     'schema',

package/src/client/index.tsx

@@ -1,3 +1,5 @@
+// Must run before any module that mints per-mount nonces at import/render time.
+import './uuid-polyfill';
 import { render } from 'preact';
 import { App } from './App';
 

package/src/client/nodes/ExtAppFrame.tsx

@@ -253,6 +253,19 @@ window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: ${JS
 </script>`;
 }
 
+/**
+ * Base styles injected into every ext-app document (Finding Q, 0.3.4 report):
+ * apps aspect-fit their drawn surface to the frame width, and on narrow/tall
+ * tiles the leftover region shows the app document's own body background —
+ * pure black for the hosted Excalidraw bundle, in every engine. Making the
+ * app document transparent lets the host iframe's theme background
+ * (var(--c-panel)) show through the letterbox instead. Background only — app
+ * content, its drawn scene, and its own foreground styling are untouched.
+ */
+export function buildExtAppSurfaceBaseStyles(): string {
+  return '<style data-pmx-canvas-ext-app-base>html, body { background: transparent !important; }</style>';
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -359,7 +372,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bootBeaconScript =
     typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
   const iframeDocument = useIframeDocument(
-    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    injectExtAppAxBridgeScript(html ?? '', buildExtAppSurfaceBaseStyles() + bootBeaconScript + axBridgeScript),
     iframeSandbox,
   );
 
@@ -688,7 +701,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
 
       bridge.onsandboxready = async () => {
         await bridge.sendSandboxResourceReady({
-          html,
+          // Same Finding Q base styles for the sandbox-proxy path: the inner
+          // resource document is the one that letterboxes on narrow tiles.
+          html: injectExtAppAxBridgeScript(html, buildExtAppSurfaceBaseStyles()),
           sandbox: DEFAULT_EXT_APP_SANDBOX,
           ...(resourceMeta?.csp ? { csp: resourceMeta.csp } : {}),
           ...(resourceMeta?.permissions ? { permissions: resourceMeta.permissions } : {}),

package/src/client/state/node-factory.ts

@@ -0,0 +1,72 @@
+import type { CanvasNodeState } from '../types';
+
+// ── Client node-creation defaults (plan-009 H5, client half) ──
+// Single source of truth for the frame (position/size/zIndex/flags) a NEW
+// client-created node gets when its creating event carries no explicit
+// geometry. Extracted from sse-bridge, which kept one `makeNode` helper plus
+// three inline node literals (ext-app open, prompt, response) duplicating
+// these defaults.
+//
+// Divergences found during extraction — documented, NOT silently unified:
+// - `canvas-store.ts` holds no node-creation defaults today. Human-created
+//   nodes go through `createNodeFromClient` (intent-bridge → POST
+//   /api/canvas/node) and get the SERVER's `defaultNodeSize`
+//   (src/server/operations/ops/nodes.ts), which differs from this table for
+//   most types (e.g. its fallback is 360x200). The server half of H5
+//   (`syncEventToCanvasState`, `ensureDefaultDockedNodes`) is deliberately
+//   deferred — do not "fix" that mismatch from this file.
+// - The server seeds `status-main`/`context-main` docked AND collapsed
+//   (`ensureDefaultDockedNodes` in src/server/server.ts); the SSE bridge
+//   creates the same ids expanded, with `context-main` undocked. Client
+//   behavior is preserved as-is.
+// - sse-bridge's prompt literal hardcoded `height: 400` beside a table entry
+//   of the same value; both now read the table (no rendering change).
+
+export const DEFAULT_POSITIONS: Record<CanvasNodeState['type'], { x: number; y: number; w: number; h: number }> &
+  Record<'prompt' | 'response', { x: number; y: number; w: number; h: number }> = {
+  status: { x: 40, y: 80, w: 300, h: 120 },
+  markdown: { x: 380, y: 80, w: 720, h: 600 },
+  context: { x: 1130, y: 80, w: 320, h: 400 },
+  'mcp-app': { x: 380, y: 720, w: 960, h: 600 },
+  webpage: { x: 380, y: 80, w: 520, h: 420 },
+  'json-render': { x: 380, y: 720, w: 840, h: 620 },
+  graph: { x: 380, y: 720, w: 760, h: 520 },
+  ledger: { x: 1130, y: 520, w: 320, h: 280 },
+  trace: { x: 40, y: 900, w: 200, h: 56 },
+  file: { x: 380, y: 80, w: 720, h: 600 },
+  image: { x: 380, y: 80, w: 720, h: 520 },
+  html: { x: 380, y: 80, w: 720, h: 640 },
+  group: { x: 220, y: 60, w: 840, h: 560 },
+  prompt: { x: 380, y: 1260, w: 520, h: 400 },
+  response: { x: 380, y: 1480, w: 720, h: 400 },
+};
+
+/**
+ * Build a canvas node with the shared client defaults. `position`/`size`
+ * default to the type's DEFAULT_POSITIONS entry; callers that compute
+ * placement (auto-placement, event-supplied geometry) pass explicit values.
+ * Status nodes sit at zIndex 0 (background chrome), everything else at 1.
+ */
+export function makeNodeState(
+  id: string,
+  type: CanvasNodeState['type'],
+  data: Record<string, unknown>,
+  options: {
+    position?: { x: number; y: number };
+    size?: { width: number; height: number };
+    dockPosition?: 'left' | 'right' | null;
+  } = {},
+): CanvasNodeState {
+  const defaults = DEFAULT_POSITIONS[type];
+  return {
+    id,
+    type,
+    position: options.position ?? { x: defaults.x, y: defaults.y },
+    size: options.size ?? { width: defaults.w, height: defaults.h },
+    zIndex: type === 'status' ? 0 : 1,
+    collapsed: false,
+    pinned: false,
+    dockPosition: options.dockPosition ?? null,
+    data,
+  };
+}